freealberta/mkdocs/docs/build/map.md

Map Build Guide

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

!!! info "Complete Configuration" For detailed configuration, usage instructions, and troubleshooting, see the Map Configuration Guide.

!!! warning "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.