Skip to content
Login Changemaker Archive. Learn more

# Map Build Guide

Map is BNKops canvassing application built for community organizing and door-to-door canvassing.

Complete Configuration

For detailed configuration, usage instructions, and troubleshooting, see the Map Configuration Guide.

Clean NocoDB

Currently the way to get a good result is to ensure the target nocodb database is empty. You can do this by deleting all bases. The script should still work with other volumes however may insert tables into odd locations; still debugging. Again, see config if needing to do manually.

## Prerequisites

- Docker and Docker Compose installed
- NocoDB instance with API access
- Domain name (optional but recommended for production)

## Quick Build Process

### 1. Get NocoDB API Token

1. Login to your NocoDB instance
2. Click user icon → Account Settings → API Tokens
3. Create new token with read/write permissions
4. Copy the token for the next step

### 2. Configure Environment

Edit the `.env` file in the `map/` directory:

    cd map

Update your `.env` file with your NocoDB details, specifically the instance and api token:

    # NocoDB API Configuration
    NOCODB_API_URL=https://your-nocodb-instance.com/api/v1
    NOCODB_API_TOKEN=your-api-token-here

    # These will be populated after running build-nocodb.sh
    NOCODB_VIEW_URL=
    NOCODB_LOGIN_SHEET=
    NOCODB_SETTINGS_SHEET=

    # Server Configuration
    PORT=3000
    NODE_ENV=production
    SESSION_SECRET=your-secure-random-string

    # Map Defaults (Edmonton, AB)
    DEFAULT_LAT=53.5461
    DEFAULT_LNG=-113.4938
    DEFAULT_ZOOM=11

    # Production Settings
    COOKIE_DOMAIN=.yourdomain.com
    ALLOWED_ORIGINS=https://map.yourdomain.com,http://localhost:3000

### 3. Auto-Create Database Structure

Run the build script to create required tables:

    chmod +x build-nocodb.sh
    ./build-nocodb.sh

This creates three tables: - Locations - Main map data with geo-location, contact info, support levels - Login - User authentication (email, name, admin flag) - Settings - Admin configuration and QR codes

### 4. Get Table URLs

After the script completes:

1. Login to your NocoDB instance
2. Navigate to your project ("Map Viewer Project")
3. Copy the view URLs for each table from your browser address bar
4. URLs should look like: `https://your-nocodb.com/dashboard/#/nc/project-id/table-id`

### 5. Update Environment with URLs

Edit your `.env` file and add the table URLs:

    NOCODB_VIEW_URL=https://your-nocodb.com/dashboard/#/nc/project-id/locations-table-id
    NOCODB_LOGIN_SHEET=https://your-nocodb.com/dashboard/#/nc/project-id/login-table-id
    NOCODB_SETTINGS_SHEET=https://your-nocodb.com/dashboard/#/nc/project-id/settings-table-id

### 6. Build and Deploy

Build the Docker image and start the application:

    # Build the Docker image
    docker-compose build

    # Start the application
    docker-compose up -d

## Verify Installation

1. Check container status:

       docker-compose ps

2. View logs:

       docker-compose logs -f map-viewer

3. Access the application at `http://localhost:3000`

## Quick Start

1. Login: Use an email from your Login table
2. Add Locations: Click on the map to add new locations
3. Admin Panel: Admin users can access `/admin.html` for configuration
4. Walk Sheets: Generate printable canvassing forms with QR codes

## Maintenance Commands

### Update Application

    docker-compose down
    git pull origin main
    docker-compose build
    docker-compose up -d

### Development Mode

    cd app
    npm install
    npm run dev

### Health Check

    curl http://localhost:3000/health

## Support

For detailed configuration, troubleshooting, and usage instructions, see the Map Configuration Guide.