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¶

Login to your NocoDB instance
Click user icon → Account Settings → API Tokens
Create new token with read/write permissions
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:

Login to your NocoDB instance
Navigate to your project ("Map Viewer Project")
Copy the view URLs for each table from your browser address bar
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¶

Check container status:
```
docker-compose ps
```
View logs:
```
docker-compose logs -f map-viewer
```
Access the application at http://localhost:3000

Quick Start¶

Login: Use an email from your Login table
Add Locations: Click on the map to add new locations
Admin Panel: Admin users can access /admin.html for configuration
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.