Docker & Local Development

Running ZapTicket locally using Docker Compose with PostgreSQL, the .NET backend, Next.js dashboard, and widget.

Overview

ZapTicket uses Docker Compose for local development. The stack includes a PostgreSQL database, the .NET backend API, the Next.js agent dashboard, and the embeddable widget. All services can be started with a single command.

Prerequisites

Docker Desktop (or Docker Engine + Docker Compose v2)
.NET 8 SDK (for running backend outside Docker)
Node.js 20+ and pnpm (for frontend services)

docker-compose.yml Reference

docker-compose.yml

version: "3.8"

services:
  postgres:
    image: postgres:16-alpine
    container_name: zapticket-db
    ports:
      - "5432:5432"
    environment:
      POSTGRES_USER: zapticket
      POSTGRES_PASSWORD: zapticket_local
      POSTGRES_DB: zapticket_dev
    volumes:
      - pgdata:/var/lib/postgresql/data
    healthcheck:
      test: ["CMD-SHELL", "pg_isready -U zapticket"]
      interval: 5s
      timeout: 3s
      retries: 5

  backend:
    build:
      context: ./backend
      dockerfile: Dockerfile
    container_name: zapticket-api
    ports:
      - "5000:5000"
    environment:
      - ASPNETCORE_ENVIRONMENT=Development
      - ConnectionStrings__DefaultConnection=Host=postgres;Database=zapticket_dev;Username=zapticket;Password=zapticket_local
      - JWT_SECRET=dev-secret-change-in-production-min-32-chars!!
      - RUN_MIGRATIONS_ON_STARTUP=true
    depends_on:
      postgres:
        condition: service_healthy

  dashboard:
    build:
      context: ./dashboard
      dockerfile: Dockerfile
    container_name: zapticket-dashboard
    ports:
      - "3000:3000"
    environment:
      - NEXT_PUBLIC_API_URL=http://localhost:5000
      - NEXT_PUBLIC_SIGNALR_URL=http://localhost:5000/hubs/chat

  widget:
    build:
      context: ./widget
      dockerfile: Dockerfile
    container_name: zapticket-widget
    ports:
      - "3001:3000"
    environment:
      - NEXT_PUBLIC_API_URL=http://localhost:5000
      - NEXT_PUBLIC_SIGNALR_URL=http://localhost:5000/hubs/chat

volumes:
  pgdata:

Running the Full Stack

Start All Services

# Clone the repository
git clone https://github.com/your-org/zapticket-v1.git
cd zapticket-v1

# Start everything
docker compose up -d

# Check status
docker compose ps

# View logs
docker compose logs -f backend

💡On first run, the backend will automatically run EF Core migrations against the PostgreSQL database (due to RUN_MIGRATIONS_ON_STARTUP=true). This creates all tables and seed data.

Running Services Individually

For faster iteration during development, you can run just the database in Docker and the services natively:

Database Only

Start PostgreSQL

docker compose up -d postgres

Backend (.NET)

Run Backend

cd backend
dotnet run

# Or with hot-reload:
dotnet watch run

Dashboard (Next.js)

Run Dashboard

cd dashboard
pnpm install
pnpm dev
# → http://localhost:3000

Widget (Next.js)

Run Widget

cd widget
pnpm install
pnpm dev
# → http://localhost:3001

PostgreSQL Connection

Local Database Credentials

Host:     localhost
Port:     5432
Database: zapticket_dev
Username: zapticket
Password: zapticket_local

Connection string:
Host=localhost;Database=zapticket_dev;Username=zapticket;Password=zapticket_local

⚠️These credentials are for local development only. Production should use strong passwords, SSL connections, and ideally managed PostgreSQL (Neon, Supabase, RDS, etc.).

Useful Commands

Common Operations

# Rebuild after code changes
docker compose up -d --build

# Stop all services
docker compose down

# Stop and remove data volumes (fresh start)
docker compose down -v

# Connect to the database
docker exec -it zapticket-db psql -U zapticket -d zapticket_dev

# View real-time backend logs
docker compose logs -f backend

Ports Summary

Default Port Mapping

Service      │ Port  │ URL
─────────────┼───────┼────────────────────────────
PostgreSQL   │ 5432  │ localhost:5432
Backend API  │ 5000  │ http://localhost:5000
Dashboard    │ 3000  │ http://localhost:3000
Widget       │ 3001  │ http://localhost:3001