Deployment Guide

This guide covers deploying Sightline to various hosting platforms.

Prerequisites

Before deploying, you'll need:

1. Mapbox Access Token - Get one here
2. Your incident data - Either a JSON file or API endpoint
3. Git repository - Fork or clone the project

Environment Variables

All deployments require these environment variables:

Vercel (Recommended)

Vercel provides the smoothest deployment experience for Next.js applications.

One-Click Deploy

Manual Deployment

1. Fork the repository on GitHub

2. Connect to Vercel

   • Go to vercel.com/new
   • Import your forked repository
   • Configure environment variables

3. Configure environment variables

NEXT_PUBLIC_MAPBOX_TOKEN=pk.your_token_here

4. Deploy
   • Vercel will automatically build and deploy
   • Updates deploy automatically when you push to main

Custom Domain

1. Go to Project Settings → Domains
2. Add your custom domain
3. Configure DNS as instructed

Netlify

Netlify also works well with Next.js projects.

Deployment Steps

1. Fork the repository on GitHub

2. Connect to Netlify

   • Go to app.netlify.com
   • Click "Add new site" → "Import an existing project"
   • Connect your GitHub account and select the repository

3. Configure build settings

Build command: pnpm build
Publish directory: .next

4. Add environment variables

   • Go to Site Settings → Environment Variables
   • Add NEXT_PUBLIC_MAPBOX_TOKEN

5. Install Next.js plugin

   Create netlify.toml in your project root:

[build]
  command = "pnpm build"
  publish = ".next"

[[plugins]]
  package = "@netlify/plugin-nextjs"

6. Deploy
   • Commit and push changes
   • Netlify will build and deploy automatically

Docker

Self-host Sightline using Docker.

Dockerfile

Create a Dockerfile in your project root:

# Build stage
FROM node:20-alpine AS builder

WORKDIR /app

# Install pnpm
RUN corepack enable && corepack prepare pnpm@latest --activate

# Copy package files
COPY package.json pnpm-lock.yaml ./

# Install dependencies
RUN pnpm install --frozen-lockfile

# Copy source
COPY . .

# Build arguments for environment variables
ARG NEXT_PUBLIC_MAPBOX_TOKEN
ENV NEXT_PUBLIC_MAPBOX_TOKEN=$NEXT_PUBLIC_MAPBOX_TOKEN

# Build
RUN pnpm build

# Production stage
FROM node:20-alpine AS runner

WORKDIR /app

ENV NODE_ENV=production

# Copy built assets
COPY --from=builder /app/.next/standalone ./
COPY --from=builder /app/.next/static ./.next/static
COPY --from=builder /app/public ./public

EXPOSE 3000

CMD ["node", "server.js"]

Docker Compose

Create docker-compose.yml:

version: '3.8'

services:
  sightline:
    build:
      context: .
      args:
        NEXT_PUBLIC_MAPBOX_TOKEN: ${NEXT_PUBLIC_MAPBOX_TOKEN}
    ports:
      - '3000:3000'
    environment:
      - NODE_ENV=production
    restart: unless-stopped

Building and Running

# Build the image
docker build \
  --build-arg NEXT_PUBLIC_MAPBOX_TOKEN=your_token \
  -t sightline .

# Run the container
docker run -p 3000:3000 sightline

# Or use docker-compose
NEXT_PUBLIC_MAPBOX_TOKEN=your_token docker-compose up -d

Next.js Standalone Output

For Docker deployments, enable standalone output in next.config.ts:

const nextConfig: NextConfig = {
  output: 'standalone',
  // ... other config
};

Static Export (Advanced)

For static hosting without server-side features:

1. Update next.config.ts

const nextConfig: NextConfig = {
  output: 'export',
  images: { unoptimized: true },
};

2. Build

pnpm build

npm run build

yarn build

bun run build

3. Deploy the out directory to any static host (S3, GitHub Pages, etc.)

Note: Static export doesn't support server actions, API routes, or ISR.

Post-Deployment

After deploying:

1. Verify the map loads - Check that Mapbox tiles render correctly
2. Test data loading - Ensure your incidents appear on the map
3. Check mobile responsiveness - Test on various devices
4. Set up monitoring - Consider adding error tracking (Sentry, etc.)

Troubleshooting

Map doesn't render

• Verify NEXT_PUBLIC_MAPBOX_TOKEN is set correctly
• Check browser console for Mapbox errors
• Ensure token has correct scopes for the styles you're using

Data doesn't load

• Check network tab for failed requests
• Verify data file path or API endpoint is correct
• Check CORS settings if using external API

Build fails

• Run npm run build locally first
• Check for TypeScript errors with npm run type-check
• Ensure all dependencies are installed

Performance Optimization

For production deployments:

1. Enable caching - Configure CDN caching for static assets
2. Compress images - Use WebP format for media
3. Monitor performance - Use Vercel Analytics or similar tools
4. Set up ISR - For frequently updated data, use Incremental Static Regeneration