freealberta/mkdocs/docs/build/map.md

Map

Map is BNKops canvassing application. It is built from the ground up to serve our community (Edmonton).

Prerequisites

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

NocoDB Table Setup

Required Columns

Create a table in NocoDB with these required columns. The format here is the Name of the column - column type - details:

1. Geo Location (geo-data) - Format: "latitude;longitude"
2. latitude (Decimal) - Precision: 10, Scale: 8
3. longitude (Decimal) - Precision: 11, Scale: 8

Recommended Columns

• First Name (Text)
• Last Name (Text)
• Email (Email)
• Phone (Phone)
• Unit Number (Text)
• Address (LongText)
• Support Level (Single Select) - Values (only enter numbers):
  • 1 Strong Support (Green)
  • 2 Moderate Support (Yellow)
  • 3 Low Support (Orange)
  • 4 No Support (Red)
• Sign (Checkbox)
• Sign Size (Single Select) - Values: Small, Medium, Large
• Notes (LongText)

Login Sheet Setup

Create a separate table for authorized users with:

• Email (Email) - Primary column
• Name (Text) - Optional

API Token Setup

1. In NocoDB, click user icon → Account Settings
2. Go to "API Tokens" tab
3. Create new token with read/write permissions for both tables

6. Finding NocoDB IDs

• Project and Table IDs: Use the full NocoDB view URL in NOCODB_VIEW_URL
• Login Sheet ID: Use the full URL to your login sheet in NOCODB_LOGIN_SHEET

Environment Configuration

!!! note "Config" The ./config.sh should have created a new .env file. If .env file is present, and it has properly defined domain, skip to step 2

1. Copy the example env file:

cp .env.example .env

2. Edit .env with your NocoDB details:

NOCODB_API_URL=https://your-nocodb-instance.com/api/v1
NOCODB_API_TOKEN=your-api-token-here
NOCODB_VIEW_URL=https://your-nocodb-instance.com/dashboard/#/nc/project-id/table-id
NOCODB_LOGIN_SHEET=https://your-nocodb-instance.com/dashboard/#/nc/project-id/login-sheet-id

# Server Configuration
PORT=3000
NODE_ENV=production

# Session Secret (generate with: openssl rand -hex 32)
SESSION_SECRET=your-secure-random-string

# Map Defaults
DEFAULT_LAT=53.5461
DEFAULT_LNG=-113.4938
DEFAULT_ZOOM=11

# Optional: Map Boundaries
# BOUND_NORTH=53.7
# BOUND_SOUTH=53.4
# BOUND_EAST=-113.3
# BOUND_WEST=-113.7

# Domain Settings (for cookies)
COOKIE_DOMAIN=.yourdomain.com
ALLOWED_ORIGINS=https://map.yourdomain.com,http://localhost:3000

Running the Application

Development Mode

cd app
npm install
npm run dev

Production with Docker

docker-compose up -d

First Run

1. Access the application at http://localhost:3000 (or your domain)
2. Login with an email from your authorized users list
3. Verify locations appear on the map

Maintenance

• To clear the geocoding cache, restart the application
• To update the application:

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

Troubleshooting

• Locations not showing: Verify table has required columns and API token has read permissions
• Cannot add locations: Check API token has write permissions
• Authentication issues: Verify login sheet is properly configured

Security Recommendations

1. Use HTTPS in production
2. Regularly rotate API tokens
3. Restrict API token permissions to only what's needed
4. Set appropriate CORS and cookie domains
5. Keep dependencies updated

The application will automatically:

• Parse project/table IDs from view URLs
• Sync geo fields between different formats
• Cache geocoding results for performance
• Rate limit API endpoints
• Validate all inputs