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

Configure Environment

Edit the .env file with your NocoDB API and API Url:

# NocoDB API Configuration
NOCODB_API_URL=https://db.cmlite.org/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=
NOCODB_SHIFTS_SHEET=
NOCODB_SHIFT_SIGNUPS_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

# Cloudflare Settings
TRUST_PROXY=true
COOKIE_DOMAIN=.cmlite.org

# Allowed Origins
ALLOWED_ORIGINS=https://map.cmlite.org,http://localhost:3000

Auto-Create Database Structure

Run the build script to create required tables:
```
chmod +x build-nocodb.sh
./build-nocodb.sh
```
This creates five 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
- Shifts - Shift scheduling and management
- Shift Signups - User shift registrations
Get Table URLs

After the script completes:
1. Login to your NocoDB instance at https://db.cmlite.org
2. Navigate to your project ("Map Viewer Project - TIMESTAMP")
3. Copy the view URLs for each table from your browser address bar
4. URLs should look like: https://db.cmlite.org/dashboard/#/nc/project-id/table-id

Update Environment with URLs

Edit your .env file and add the table URLs:

NOCODB_VIEW_URL=https://db.cmlite.org/dashboard/#/nc/pnsalzrup2zqvz8/m6g7bkzv7s1w2ur
NOCODB_LOGIN_SHEET=https://db.cmlite.org/dashboard/#/nc/pnsalzrup2zqvz8/mizyc64e4r7ppzh
NOCODB_SETTINGS_SHEET=https://db.cmlite.org/dashboard/#/nc/pnsalzrup2zqvz8/mix06f2mlep7gqb
NOCODB_SHIFTS_SHEET=https://db.cmlite.org/dashboard/#/nc/pnsalzrup2zqvz8/mkx0tex0iquus1u
NOCODB_SHIFT_SIGNUPS_SHEET=https://db.cmlite.org/dashboard/#/nc/pnsalzrup2zqvz8/mi8jg1tn26mu8fj

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
- Access shift management at: http://localhost:3000/shifts.html
- Access admin panel at: http://localhost:3000/admin.html (admin users only)

Database Schema

The build script automatically creates the following table structure:

Main Locations Table

Geo-Location (Geo-Data): Format "latitude;longitude"
latitude (Decimal): Precision 10, Scale 8
longitude (Decimal): Precision 11, Scale 8
First Name (Single Line Text): Person's first name
Last Name (Single Line Text): Person's last name
Email (Email): Email address
Phone (Single Line Text): Phone number
Unit Number (Single Line Text): Unit or apartment number
Support Level (Single Select): Options: "1", "2", "3", "4" (1=Strong Support/Green, 2=Moderate Support/Yellow, 3=Low Support/Orange, 4=No Support/Red)
Address (Single Line Text): Street address
Sign (Checkbox): Has campaign sign
Sign Size (Single Select): Options: "Small", "Medium", "Large"
Notes (Long Text): Additional details and comments
title (Text): Location name (legacy field)
category (Single Select): Classification (legacy field)

Email (Email): User email address
Name (Single Line Text): User display name
Admin (Checkbox): Admin privileges

Settings Table

key (Single Line Text): Setting identifier
title (Single Line Text): Display name
value (Long Text): Setting value
Geo-Location (Text): Format "latitude;longitude"
latitude (Decimal): Precision 10, Scale 8
longitude (Decimal): Precision 11, Scale 8
zoom (Number): Map zoom level
category (Single Select): Setting category
updated_by (Single Line Text): Last updater email
updated_at (DateTime): Last update time
qr_code_1_image (Attachment): QR code 1 image
qr_code_2_image (Attachment): QR code 2 image
qr_code_3_image (Attachment): QR code 3 image

Shifts Table

Standard NocoDB fields for shift scheduling and management
Contains shift dates, times, locations, capacity limits
Status tracking (Active, Cancelled, Full)
Created automatically by build script with basic structure

Shift Signups Table

Links users to shifts they've signed up for
Tracks signup timestamps and user information
Handles cancellations and waitlist management
Created automatically by build script with basic structure

API Endpoints

Public Endpoints

GET /api/locations - Fetch all locations (requires auth)
POST /api/locations - Create new location (requires auth)
GET /api/locations/:id - Get single location (requires auth)
PUT /api/locations/:id - Update location (requires auth)
DELETE /api/locations/:id - Delete location (requires auth)
GET /api/config/start-location - Get map start location
GET /health - Health check

Shifts Endpoints (requires authentication)

GET /api/shifts - Get all available shifts
GET /api/shifts/my-signups - Get current user's shift signups
POST /api/shifts/:shiftId/signup - Sign up for a shift
POST /api/shifts/:shiftId/cancel - Cancel shift signup

Shifts Admin Endpoints (requires admin privileges)

GET /api/shifts/admin - Get all shifts including cancelled ones
POST /api/shifts/admin - Create new shift
PUT /api/shifts/admin/:id - Update existing shift
DELETE /api/shifts/admin/:id - Delete shift

Authentication Endpoints

POST /api/auth/login - User login
GET /api/auth/check - Check authentication status
POST /api/auth/logout - User logout

Admin Endpoints (requires admin privileges)

GET /api/admin/start-location - Get start location with source info
POST /api/admin/start-location - Update map start location
GET /api/admin/walk-sheet-config - Get walk sheet configuration
POST /api/admin/walk-sheet-config - Save walk sheet configuration

Shifts Management

The application includes a comprehensive volunteer shift management system accessible at /shifts.html.

User Features

View Available Shifts: See all upcoming shifts with date, time, and capacity information
Sign Up for Shifts: One-click signup for available shifts
My Shifts Dashboard: View all your current shift signups
Cancel Signups: Cancel your shift signups when needed
Date Filtering: Filter shifts by specific dates
Real-time Updates: Shift availability updates dynamically

Admin Features

Administrators have additional capabilities for managing shifts:

Create New Shifts: Add new volunteer shifts with date, time, location, and capacity
Edit Existing Shifts: Modify shift details, times, or capacity
Cancel Shifts: Mark shifts as cancelled (they remain in system but hidden from users)
View All Signups: See who has signed up for each shift
Manage Capacity: Set maximum number of volunteers per shift

Shift Status System

Active: Available for signups
Full: Capacity reached, no more signups accepted
Cancelled: Hidden from public view but retained in database

Admin Panel

Users with admin privileges can access the admin panel at /admin.html to configure system settings.

Features

Start Location Configuration

Interactive Map: Visual interface for selecting coordinates
Real-time Preview: See changes immediately on the admin map
Validation: Built-in coordinate and zoom level validation

Walk Sheet Generator

Printable Forms: Generate 8.5x11 walk sheets for door-to-door canvassing
QR Code Integration: Add up to 3 QR codes with custom URLs and labels
Form Field Matching: Automatically matches fields from the main location form
Live Preview: See changes as you type
Print Optimization: Proper formatting for printing or PDF export
Persistent Storage: All QR codes and settings saved to NocoDB
Real-time Preview: See changes immediately on the admin map
Validation: Built-in coordinate and zoom level validation

Access Control

Admin access is controlled via the Admin checkbox in the Login table
Only authenticated users with admin privileges can access /admin.html
Admin status is checked on every request to admin endpoints

Start Location Priority

The system uses a cascading fallback system for map start location:

Database: Admin-configured location stored in Settings table (highest priority)
Environment: Default values from .env file (medium priority)
Hardcoded: Edmonton, Canada coordinates (lowest priority)

Configuration

All configuration is done via environment variables:

Variable	Description	Default
`NOCODB_API_URL`	NocoDB API base URL	Required
`NOCODB_API_TOKEN`	API authentication token	Required
`NOCODB_VIEW_URL`	Full NocoDB view URL for locations table	Required
`NOCODB_LOGIN_SHEET`	Login table URL for authentication	Required
`NOCODB_SETTINGS_SHEET`	Settings table URL for admin config	Required
`NOCODB_SHIFTS_SHEET`	Shifts table URL for shift management	Required
`NOCODB_SHIFT_SIGNUPS_SHEET`	Shift signups table URL for user registrations	Required
`PORT`	Server port	3000
`NODE_ENV`	Environment mode	production
`SESSION_SECRET`	Session encryption secret	Required
`DEFAULT_LAT`	Default map latitude	53.5461
`DEFAULT_LNG`	Default map longitude	-113.4938
`DEFAULT_ZOOM`	Default map zoom level	11
`TRUST_PROXY`	Trust proxy headers (for Cloudflare)	true
`COOKIE_DOMAIN`	Cookie domain setting	.cmlite.org
`ALLOWED_ORIGINS`	CORS allowed origins	Multiple URLs

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

Development

To run in development mode:

Install dependencies:
```
cd app
npm install
```
Start with hot reload:
```
npm run dev
```

Security Considerations

API tokens are kept server-side only
CORS is configured for security
Rate limiting prevents abuse
Input validation on all endpoints
Helmet.js for security headers

Troubleshooting

Locations not showing

Verify table has geodata, latitude, and longitude columns
Check that coordinates are valid numbers
Ensure API token has read permissions

Cannot add locations

Verify API token has write permissions
Check browser console for errors
Ensure coordinates are within valid ranges

Connection errors

Verify NocoDB instance is accessible
Check API URL format
Confirm network connectivity

Build Script Issues

Ensure NocoDB instance is accessible
Verify API token has admin permissions
Check that the NocoDB database is clean (delete all bases before running)

License

MIT License - See LICENSE file for details

Support

For issues or questions:

Check the troubleshooting section
Review NocoDB documentation
Open an issue on GitHub

Known Bugs

First load of page often fails, need to debug
Want UI for dots to have an edit button that then brings up the form

README.md Unescape Escape

NocoDB Map Viewer

Features

Quick Start

Prerequisites

Installation

Database Schema

Main Locations Table

Login Table

Settings Table

Shifts Table

Shift Signups Table

API Endpoints

Public Endpoints

Shifts Endpoints (requires authentication)

Shifts Admin Endpoints (requires admin privileges)

Authentication Endpoints

Admin Endpoints (requires admin privileges)

Shifts Management

User Features

Admin Features

Shift Status System

Admin Panel

Features

Start Location Configuration

Walk Sheet Generator

Access Control

Start Location Priority

Configuration

Maintenance Commands

Update Application

Development Mode

Health Check

Development

Security Considerations

Troubleshooting

Locations not showing

Cannot add locations

Connection errors

Build Script Issues

License

Support

Known Bugs

README.md