Local Deploy

Deploy locally using Docker Desktop to run the full stack — database, Redis, proxy, and your app — in containers on your machine.

Prerequisites

Docker Desktop installed and running
Docker Compose v2 (included with Docker Desktop)
Your project's .env configured with DATABASE_URL and REDIS (if used)

TIP

You don't need to create deploy/.env or deploy/server/.env manually. Just edit the .env.example files generated by deploy:init, and the workflow will copy them to .env automatically on first run.

Step 1 — Generate Deploy Scaffolding

Run once per project:

npmpnpmyarnbun

bash

npm run maker deploy:init

bash

pnpm maker deploy:init

bash

yarn maker deploy:init

bash

bun maker deploy:init

This reads your .env, detects your database (MySQL/Postgres/SQLite) and Redis settings, and generates the entire deploy/ directory — including the shared infrastructure compose file and the two workflow configs.

TIP

The generated files are .env.example templates, not .env files. Edit the .example files with your settings, then run deploy:workflow — it will create the actual .env files automatically.

See Deploy Overview for the full file tree.

Step 2 — Start Server Infrastructure

npmpnpmyarnbun

bash

npm run maker deploy:workflow -- --server-only

bash

pnpm maker deploy:workflow --server-only

bash

yarn maker deploy:workflow --server-only

bash

bun maker deploy:workflow --server-only

This single command:

Creates Docker networks if missing:
- nginx-proxy — reverse proxy network (port 80/443)
- infra — internal network for database/Redis communication
Ensures bind-mount files — creates placeholder files for pgAdmin config and Redis config if they don't exist.
Ensures .env — copies .env.example to .env in deploy/server/ if missing.
Starts containers — runs docker compose -f deploy/server/docker-compose.yml up -d

What starts

Container            Image                Hostname            Purpose
─────────────────────────────────────────────────────────────────────
nginx-proxy          jwilder/nginx-proxy  —                   Reverse proxy (ports 80, 443)
letsencrypt          jrcs/letsencrypt     —                   Auto SSL companion
mysql-global         mysql:8.4            mysql-global        MySQL database
postgres-global      postgres:16-alpine   postgres-global     PostgreSQL database
redis-global         redis:7-alpine       redis-global        Redis (if enabled)
phpmyadmin           phpmyadmin:5-apache  —                   MySQL admin UI (port 8082)
pgadmin              dpage/pgadmin4       —                   Postgres admin UI (port 8083)

All database/Redis containers are reachable from the app container by hostname (mysql-global:3306, redis-global:6379, etc.) via the infra network.

Dev mode (Docker Desktop)

If you don't have MySQL, PostgreSQL, or Redis installed locally, use this workflow to run all infrastructure in Docker Desktop while developing on your host machine.

Generate dev server config

This generates server infra files with Redis port exposed to the host:

npmpnpmyarnbun

bash

npm run maker deploy:init -- --server-only --dev --force

bash

pnpm maker deploy:init --server-only --dev --force

bash

yarn maker deploy:init --server-only --dev --force

bash

bun maker deploy:init --server-only --dev --force

The --dev flag exposes these ports to your host:

Container	Host Port	Default	Purpose
`mysql-global`	3306	`0.0.0.0:3306`	Connect via any MySQL client
`postgres-global`	5432	`0.0.0.0:5432`	Connect via any Postgres client
`redis-global`	6379	`0.0.0.0:6379`	Connect via RedisInsight, redis-cli, etc.

Start server infra

npmpnpmyarnbun

bash

npm run maker deploy:workflow -- --server-only

bash

pnpm maker deploy:workflow --server-only

bash

yarn maker deploy:workflow --server-only

bash

bun maker deploy:workflow --server-only

Configure your local `.env`

Point your local .env to localhost so your dev server connects to Docker containers:

bash

DATABASE_URL=mysql://root:password@localhost:3306/nexgen
REDIS=true
REDIS_URL=redis://localhost:6379

Or for PostgreSQL:

bash

DATABASE_URL=postgres://postgres:password@localhost:5432/nexgen

Develop normally

Now run maker dev as usual — your local API server connects to the Docker-hosted database and Redis:

Your Machine (host)                Docker Desktop
     │                                   │
     │  maker dev                        │
     │  ├─ serve (port 3000) ──┐         │
     │  ├─ queue:work          │         │
      │  └─ ui:dev        │         │
     │                         │         │
     │  localhost:3306 ────────┼────────>│ mysql-global
     │  localhost:6379 ────────┼────────>│ redis-global
     │  localhost:5432 ────────┼────────>│ postgres-global
     │                         │         │
     │  RedisInsight ──────────┼────────>│ redis-global
     │  TablePlus / DBeaver ───┼────────>│ mysql-global / postgres-global

This way you don't need to install or manage databases on your host — Docker handles everything, and you still get hot-reload and local debugging from your IDE.

Step 3 — Build and Start the App

npmpnpmyarnbun

bash

npm run maker deploy:workflow -- --app-only

bash

pnpm maker deploy:workflow --app-only

bash

yarn maker deploy:workflow --app-only

bash

bun maker deploy:workflow --app-only

This:

Syncs DATABASE_URL — reads the database name from deploy/server/.env and writes it into deploy/.env so the app connects to the correct database.
Ensures MySQL database exists — if using MySQL, creates the target database inside mysql-global if it doesn't exist yet.
Builds the Docker image — runs docker compose -f deploy/docker-compose.yml build using the multi-stage Dockerfile (install deps → schema gen → build → production image).
Starts the container — runs docker compose -f deploy/docker-compose.yml up -d --force-recreate

What happens inside

Container starts →
  supervisord reads deploy/supervisor/supervisord.conf →
    ├─ auto-migrate.sh (one-shot)
    │   └─ Reads AUTO_MIGRATE=true from .env
    │   └─ Runs: node maker-cli db:migrate --seed
    ├─ maker serve --prod
    │   └─ Starts HTTP server on port 3000
    ├─ maker queue:work (only if Redis enabled)
    │   └─ Processes default, mail and maintenance queues
    └─ maker schedule:work
        └─ Runs cron scheduler

Step 4 — Import Database (Optional)

If you have an existing SQL dump:

npmpnpmyarnbun

bash

npm run maker deploy:db:import -- --file=deploy/nexgen.sql --database=nexgen

bash

pnpm maker deploy:db:import --file=deploy/nexgen.sql --database=nexgen

bash

yarn maker deploy:db:import --file=deploy/nexgen.sql --database=nexgen

bash

bun maker deploy:db:import --file=deploy/nexgen.sql --database=nexgen

The command auto-detects the database dialect (MySQL or PostgreSQL) from deploy/server/.env and streams the SQL into the right container:

bash

# MySQL
docker exec -i mysql-global mysql -u root -p<password> -e "CREATE DATABASE IF NOT EXISTS nexgen"
docker exec -i mysql-global mysql -u root -p<password> nexgen < deploy/nexgen.sql

# PostgreSQL (defaults to a clean restore — drops & recreates the database)
docker exec -i postgres-global psql -U postgres -d postgres -v ON_ERROR_STOP=1 ...
docker exec -i postgres-global psql -U postgres -d nexgen < deploy/nexgen.sql

For PostgreSQL, pass --no-drop to keep the existing database instead of dropping it for a clean restore.

One-Shot Workflow

For convenience, a single command runs steps 2 + 3 sequentially:

npmpnpmyarnbun

bash

npm run maker deploy:workflow

bash

pnpm maker deploy:workflow

bash

yarn maker deploy:workflow

bash

bun maker deploy:workflow

You can customize the steps by editing deploy/workflow.local.json:

json

{
  "steps": [
    { "name": "Generate deploy files", "run": "deploy:init --force", "enabled": false },
    { "name": "Start shared infra", "run": "deploy:workflow --server-only", "enabled": true },
    { "name": "Import database dump (optional)", "run": "deploy:db:import --file=deploy/nexgen.sql --database=nexgen", "enabled": false },
    { "name": "Start app stack", "run": "deploy:workflow --app-only", "enabled": true }
  ]
}

Set "enabled": false to skip steps. Preview what a workflow would run without executing it:

npmpnpmyarnbun

bash

npm run maker deploy:workflow -- --config=deploy/workflow.local.json --dry-run

bash

pnpm maker deploy:workflow --config=deploy/workflow.local.json --dry-run

bash

yarn maker deploy:workflow --config=deploy/workflow.local.json --dry-run

bash

bun maker deploy:workflow --config=deploy/workflow.local.json --dry-run

The workflow config is created automatically by deploy:init.

Environment Variables

App (`deploy/.env`)

Variable	Auto-detected	Purpose
`APP_ENV`	—	Set to `production` in deploy
`APP_NAME`	—	Container name prefix
`APP_HOST`	—	Bind address (default `localhost`)
`APP_PORT`	—	Port exposed (default `3000`)
`APP_URL`	—	Public URL of your app (links, redirects, CORS)
`DATABASE_URL`	Yes	Database connection string (synced with server)
`AUTO_MIGRATE`	—	`true` to auto-run `db:migrate --seed` on container start
`VIRTUAL_HOST`	—	Domain routed by nginx-proxy (remote only)
`VIRTUAL_PORT`	—	Port nginx-proxy forwards to (default `3000`)
`LETSENCRYPT_HOST`	—	Domain for auto SSL (remote only)
`LETSENCRYPT_EMAIL`	—	Email for SSL certificate notifications
`JWT_ACCESS_SECRET`	—	JWT access token secret (must set before production)
`JWT_REFRESH_SECRET`	—	JWT refresh token secret (must set before production)
`COOKIE_SECRET`	—	Cookie signing secret (must set before production)
`STORAGE_ACCESS_KEY_ID`	—	Object storage key (S3/MinIO)
`STORAGE_SECRET_ACCESS_KEY`	—	Object storage secret (S3/MinIO)
`MAIL_USERNAME`	—	SMTP username
`MAIL_PASSWORD`	—	SMTP password
`REDIS`	Yes	Enable Redis (true/false)
`REDIS_URL`	Yes	Set to `redis://redis-global:6379` when Redis enabled
`REDIS_PREFIX`	—	Key prefix for Redis (multi-tenant isolation)
`UI`	Yes	Enable UI build (true/false, default `true`)
`OPEN_API`	Yes	Enable OpenAPI docs at `/api-docs` (true/false)
`SOCKET`	Yes	Enable Socket.IO realtime (true/false)

Server (`deploy/server/.env`)

Variable	Purpose
`LETSENCRYPT_EMAIL`	Email for SSL certificate notifications
`PROXY_HTTP_PORT`	nginx-proxy HTTP port (default `80`)
`PROXY_HTTPS_PORT`	nginx-proxy HTTPS port (default `443`)
`MYSQL_ROOT_PASSWORD`	MySQL root password
`MYSQL_DATABASE`	Default MySQL database name
`MYSQL_PORT`	MySQL host port (default `4000`)
`POSTGRES_USER`	Postgres superuser
`POSTGRES_PASSWORD`	Postgres password
`POSTGRES_DB`	Default Postgres database name
`POSTGRES_PORT`	Postgres host port (default `4001`)
`REDIS`	Enable Redis service in server infra
`PHPMYADMIN_DOMAIN`	phpMyAdmin virtual host domain
`PHPMYADMIN_LOCAL_PORT`	phpMyAdmin local port (default `127.0.0.1:8082`)
`PGADMIN_DOMAIN`	pgAdmin virtual host domain
`PGADMIN_DEFAULT_EMAIL`	pgAdmin login email
`PGADMIN_DEFAULT_PASSWORD`	pgAdmin login password
`PGADMIN_LOCAL_PORT`	pgAdmin local port (default `127.0.0.1:8083`)

Troubleshooting

View app logs

bash

docker compose -f deploy/docker-compose.yml logs -f app

View server infra logs

bash

docker compose -f deploy/server/docker-compose.yml logs -f mysql-global

Rebuild without cache

bash

docker compose -f deploy/docker-compose.yml build --no-cache app
docker compose -f deploy/docker-compose.yml up -d --force-recreate app

Enter the app container

bash

docker exec -it <app-container-name> sh

Local Deploy ​

Prerequisites ​

Step 1 — Generate Deploy Scaffolding ​

Step 2 — Start Server Infrastructure ​

What starts ​

Dev mode (Docker Desktop) ​

Generate dev server config ​

Start server infra ​

Configure your local .env ​

Develop normally ​

Step 3 — Build and Start the App ​

What happens inside ​

Step 4 — Import Database (Optional) ​

One-Shot Workflow ​

Environment Variables ​

App (deploy/.env) ​

Server (deploy/server/.env) ​

Troubleshooting ​

View app logs ​

View server infra logs ​

Rebuild without cache ​

Enter the app container ​

Local Deploy

Prerequisites

Step 1 — Generate Deploy Scaffolding

Step 2 — Start Server Infrastructure

What starts

Dev mode (Docker Desktop)

Generate dev server config

Start server infra

Configure your local `.env`

Develop normally

Step 3 — Build and Start the App

What happens inside

Step 4 — Import Database (Optional)

One-Shot Workflow

Environment Variables

App (`deploy/.env`)

Server (`deploy/server/.env`)

Troubleshooting

View app logs

View server infra logs

Rebuild without cache

Enter the app container