LeAPI Next

A Next.js dashboard for managing Leaptel wholesale services.

Quick Start

# Start everything with Docker
docker compose up

# Or rebuild after package.json changes
docker compose up --build

The app will be available at http://localhost:3000

Services

Service	Port	Description
app	3000	Next.js application
postgres	5432	PostgreSQL database
cron	-	Background sync (every 30 min)
warmup	-	Pre-compiles routes on startup

Environment Variables

The Docker Compose setup includes default values for development, so no .env file is required to get started.

For production or custom configuration, you can create a .env file or set environment variables:

DATABASE_URL=postgresql://leapi:leapi_dev@postgres:5432/leapi
CRON_SECRET=your-secret-here
ENCRYPTION_KEY=your-64-hex-character-encryption-key-here

Note: ENCRYPTION_KEY must be exactly 64 hex characters (32 bytes). Generate one with:

openssl rand -hex 32

Commands

# Start services
docker compose up

# Start in background
docker compose up -d

# Stop services
docker compose down

# View logs
docker compose logs -f app

# Rebuild after dependency changes
docker compose up --build

# Reset everything (including database)
docker compose down -v && docker compose up --build

Database

Data Persistence:

• All data (users, audit events, cached customers/services, credentials) is stored in PostgreSQL
• In development: Data persists in the Docker volume pgdata (survives container restarts)
• In production: PostgreSQL runs in a container on the same VM with persistent storage via Docker volumes
• Important: Audit history, user data, and cached data will persist as long as your PostgreSQL database persists

Run Prisma commands inside the container:

# Generate Prisma client
docker compose exec app npx prisma generate

# Run migrations
docker compose exec app npx prisma migrate dev

# Open Prisma Studio
docker compose exec app npx prisma studio

Database Schema:

• users - User accounts (NextAuth + dev-user)
• audit_events - Audit activity log (all user actions)
• app_config - Shared API credentials (encrypted)
• cached_customers - Cached customer data
• cached_services - Cached service data
• cached_orders - Cached order data
• sync_metadata - Sync status tracking

Production Deployment (Debian/Linux)

The production setup is platform-agnostic and works on Debian, Ubuntu, Fedora, and other Linux distributions.

Using Forgejo Container Registry

The project includes a Forgejo Actions workflow that automatically builds and pushes Docker images to the Forgejo container registry on pushes to main and when version tags are created. On successful main builds it also deploys the refreshed latest image to the production LeAPI host at 10.20.63.21 by pulling the new registry image and recreating the app container in /opt/leapi.

Required Forgejo repository secrets:

• REGISTRY_USERNAME - Forgejo username for the container registry
• REGISTRY_PASSWORD - Forgejo personal access token for the container registry
• DEPLOY_SSH_KEY - private SSH key permitted to log into the production LeAPI host and run sudo docker

Pull the latest image:

docker pull git.launcestonit.com.au/LauncestonIT/leapi-next:latest

Pull a specific version:

docker pull git.launcestonit.com.au/LauncestonIT/leapi-next:v1.0.0

Run from Forgejo Container Registry:

# Note: This example requires a PostgreSQL container running separately
# For production, use docker-compose.prod.yml which includes the database
docker run -d \
  --name leapi-next \
  -p 3000:3000 \
  -e DATABASE_URL="postgresql://leapi:password@postgres:5432/leapi" \
  -e ENCRYPTION_KEY="$(openssl rand -hex 32)" \
  -e CRON_SECRET="your-secure-cron-secret" \
  -e NODE_ENV=production \
  git.launcestonit.com.au/LauncestonIT/leapi-next:latest

Note: You may need to authenticate to the Forgejo Container Registry:

echo $FORGEJO_TOKEN | docker login git.launcestonit.com.au -u USERNAME --password-stdin

Production Database Setup:

• PostgreSQL runs in a container on the same VM with persistent storage
• The docker-compose.prod.yml file includes the PostgreSQL container
• Ensure the pgdata volume is backed up regularly

Example Production DATABASE_URL:

# Database runs in a container on the same VM
DATABASE_URL=postgresql://leapi:secure_password@postgres:5432/leapi

Build and Run Locally

# Build production image
docker build --target production -t leapi-next .

# Run production container with required environment variables
# Note: This example requires a PostgreSQL container running separately
# For production, use docker-compose.prod.yml which includes the database
docker run -d \
  --name leapi-next \
  -p 3000:3000 \
  -e DATABASE_URL="postgresql://leapi:password@postgres:5432/leapi" \
  -e ENCRYPTION_KEY="$(openssl rand -hex 32)" \
  -e CRON_SECRET="your-secure-cron-secret" \
  -e NODE_ENV=production \
  leapi-next

Using Docker Compose for Production

The docker-compose.prod.yml file is already configured with the application and PostgreSQL database containers. Simply create a .env file with your configuration and run:

docker compose -f docker-compose.prod.yml up -d

See DEPLOYMENT.md for detailed deployment instructions.

Important: For production, always set ENCRYPTION_KEY to a secure, randomly generated value. Never use the default development key.