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
• <EFBFBD> Walk Sheet generator for door-to-door canvassing
• 🔗 QR code integration for digital resources
• <EFBFBD>🐳 Docker containerization for easy deployment
• 🆓 100% open source (no proprietary dependencies)

Quick Start

Prerequisites

• Docker and Docker Compose
• NocoDB instance with a table containing location data
• NocoDB API token

NocoDB Table Setup

1. Main Locations Table - Create a table with these required columns. The format here is Column Name - Column Type - Other Settings:

   • 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)

2. Login Table - Create a table for user authentication:

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

3. Settings Table - Create a table for admin configuration:

   • 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

Installation

1. Clone this repository or create the file structure as shown

2. Copy the environment template:

   cp .env.example .env
   

3. Edit .env with your NocoDB details:

   NOCODB_API_URL=https://db.lindalindsay.org/api/v1
   NOCODB_API_TOKEN=your-token-here
   NOCODB_VIEW_URL=https://db.lindalindsay.org/dashboard/#/nc/p406kno3lbq4zmq/mvtryxrvze6td79
   NOCODB_LOGIN_SHEET=https://db.lindalindsay.org/dashboard/#/nc/p406kno3lbq4zmq/login_sheet_id
   NOCODB_SETTINGS_SHEET=https://db.lindalindsay.org/dashboard/#/nc/p406kno3lbq4zmq/settings_sheet_id
   

4. Start the application:

   docker-compose up -d
   

5. Access the map at: http://localhost:3000

Finding NocoDB IDs

API Token

1. Click user icon → Account Settings
2. Go to "API Tokens" tab
3. Create new token with read/write permissions

Project and Table IDs

• Simply provide the full NocoDB view URL in NOCODB_VIEW_URL
• The system will automatically extract the project and table IDs

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

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

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