# 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 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

# Production Settings
COOKIE_DOMAIN=.yourdomain.com
ALLOWED_ORIGINS=https://map.yourdomain.com,http://localhost:3000
```

### 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=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:

```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).