freealberta/mkdocs/docs/build/map.md

# Map Build Guide

Map is BNKops canvassing application built for community organizing and door-to-door canvassing.

!!! info "Complete Configuration"
    For detailed configuration, usage instructions, and troubleshooting, see the [Map Configuration Guide](../config/map.md).

!!! warning "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

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 in the `map/` directory:

```bash
cd map
```

Update your `.env` file with your NocoDB details, specifically the instance and api token:

```env
NOCODB_API_URL=[change me]
NOCODB_API_TOKEN=[change me]

# NocoDB View URL is the URL to your NocoDB view where the map data is stored.
NOCODB_VIEW_URL=[change me]

# NOCODB_LOGIN_SHEET is the URL to your NocoDB login sheet.
NOCODB_LOGIN_SHEET=[change me]

# NOCODB_SETTINGS_SHEET is the URL to your NocoDB settings sheet.
NOCODB_SETTINGS_SHEET=[change me]

# NOCODB_SHIFTS_SHEET is the URL to your shifts sheet.
NOCODB_SHIFTS_SHEET=[change me]

# NOCODB_SHIFT_SIGNUPS_SHEET is the URL to your NocoDB shift signups sheet where users can add their own shifts.
NOCODB_SHIFT_SIGNUPS_SHEET=[change me]

# NOCODB_CUTS_SHEET is the URL to your NocoDB Cuts sheet.
NOCODB_CUTS_SHEET=[change me]

DOMAIN=[change me]

# MkDocs Integration
MKDOCS_URL=[change me]
MKDOCS_SEARCH_URL=[change me]
MKDOCS_SITE_SERVER_PORT=4002

# Server Configuration
PORT=3000
NODE_ENV=production

# Session Secret (IMPORTANT: Generate a secure random string for production)
SESSION_SECRET=[change me]

# Map Defaults (Edmonton, Alberta, Canada)
DEFAULT_LAT=53.5461
DEFAULT_LNG=-113.4938
DEFAULT_ZOOM=11

# Optional: Map Boundaries (prevents users from adding points outside area)
# BOUND_NORTH=53.7
# BOUND_SOUTH=53.4
# BOUND_EAST=-113.3
# BOUND_WEST=-113.7

# Cloudflare Settings
TRUST_PROXY=true
COOKIE_DOMAIN=[change me]

# Update NODE_ENV to production for HTTPS
NODE_ENV=production

# Add allowed origin
ALLOWED_ORIGINS=[change me]

# SMTP Configuration
SMTP_HOST=[change me]
SMTP_PORT=587   
SMTP_SECURE=false
SMTP_USER=[change me]
SMTP_PASS=[change me]
EMAIL_FROM_NAME="[change me]"
EMAIL_FROM_ADDRESS=[change me]

# App Configuration
APP_NAME="[change me]"

# Listmonk Configuration
LISTMONK_API_URL=[change me]
LISTMONK_USERNAME=[change me]
LISTMONK_PASSWORD=[change me]
LISTMONK_SYNC_ENABLED=true
LISTMONK_INITIAL_SYNC=false  # Set to true only for first run to sync existing data
```

### 3. Auto-Create Database Structure

Run the build script to create required tables:

```bash
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:

```env
# NocoDB View URL is the URL to your NocoDB view where the map data is stored.
NOCODB_VIEW_URL=[change me]

# NOCODB_LOGIN_SHEET is the URL to your NocoDB login sheet.
NOCODB_LOGIN_SHEET=[change me]

# NOCODB_SETTINGS_SHEET is the URL to your NocoDB settings sheet.
NOCODB_SETTINGS_SHEET=[change me]

# NOCODB_SHIFTS_SHEET is the URL to your shifts sheet.
NOCODB_SHIFTS_SHEET=[change me]

# NOCODB_SHIFT_SIGNUPS_SHEET is the URL to your NocoDB shift signups sheet where users can add their own shifts.
NOCODB_SHIFT_SIGNUPS_SHEET=[change me]

# NOCODB_CUTS_SHEET is the URL to your NocoDB Cuts sheet.
NOCODB_CUTS_SHEET=[change me]
```

### 6. Build and Deploy

Build the Docker image and start the application:

```bash
# Build the Docker image
docker-compose build

# Start the application
docker-compose up -d
```

## Verify Installation

1. Check container status:
   ```bash
   docker-compose ps
   ```

2. View logs:
   ```bash
   docker-compose logs -f map-viewer
   ```

3. Access the application at `http://localhost:3000`

## Quick Start

1. **Login**: Use an email from your Login table
2. **Add Locations**: Click on the map to add new locations
3. **Admin Panel**: Admin users can access `/admin.html` for configuration
4. **Walk Sheets**: Generate printable canvassing forms with QR codes

## Maintenance Commands

### Update Application
```bash
docker-compose down
git pull origin main
docker-compose build
docker-compose up -d
```

### Development Mode
```bash
cd app
npm install
npm run dev
```

### Health Check
```bash
curl http://localhost:3000/health
```

## Support

For detailed configuration, troubleshooting, and usage instructions, see the [Map Configuration Guide](../config/map.md).