freealberta/map/README.md

NocoDB Map Viewer

A containerized web application that visualizes geographic data from NocoDB on an interactive map using Leaflet.js.

Features

• 🗺️ Interactive map visualization with OpenStreetMap
• 📍 Real-time geolocation support
• ➕ Add new locations directly from the map
• 🔄 Auto-refresh every 30 seconds
• 📱 Responsive design for mobile devices
• 🔒 Secure API proxy to protect credentials
• 👤 User authentication with login system
• ⚙️ Admin panel for system configuration
• 🎯 Configurable map start location
• 📋 Walk Sheet generator for door-to-door canvassing
• 🔗 QR code integration for digital resources
• 🐳 Docker containerization for easy deployment
• 🆓 100% open source (no proprietary dependencies)

Quick Start

Prerequisites

• Docker and Docker Compose
• NocoDB instance with API access
• NocoDB API token

Installation

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 with your NocoDB API and API Url:

   # 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
   

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
   

7. Verify Installation

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

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)

Login Table

• 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

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

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

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:

1. Database: Admin-configured location stored in Settings table (highest priority)
2. Environment: Default values from .env file (medium priority)
3. 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	Required
NOCODB_LOGIN_SHEET	Login table URL for authentication	Required
NOCODB_SETTINGS_SHEET	Settings table URL for admin config	Optional
PORT	Server port	3000
DEFAULT_LAT	Default map latitude	53.5461
DEFAULT_LNG	Default map longitude	-113.4938
DEFAULT_ZOOM	Default map zoom level	11

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:

1. Install dependencies:

   cd app
   npm install
   

2. 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:

1. Check the troubleshooting section
2. Review NocoDB documentation
3. 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