Constructive Deployment

How to deploy the Constructive platform — local development with Docker Compose, database migrations with pgpm, and production container builds.

When to Apply

Use this skill when:

• Setting up the Constructive monorepo for local development
• Running Docker Compose services (Postgres, MinIO, API servers)
• Building the Constructive Docker image
• Deploying database migrations to local or remote Postgres
• Understanding the Makefile targets and service architecture

Local Development Setup

Prerequisites

• Docker and Docker Compose
• Node.js 22+ with pnpm
• pgpm CLI (available from the constructive monorepo)

Quick Start

# 1. Start Postgres and MinIO containers
make up
# OR: docker-compose up -d

# 2. Bootstrap database roles (ensure PG env vars are loaded — see pgpm skill, references/env.md)
pgpm admin-users bootstrap --yes

# 3. Deploy all database modules
pgpm deploy --createdb --workspace --all --yes

Stopping

# Stop and remove containers + volumes
make down
# OR: docker-compose down -v

Docker Compose Services

Core Services (docker-compose.yml)

| Service | Container | Image | Port | Purpose | |---------|-----------|-------|------|---------| | postgres | postgres | ghcr.io/constructive-io/docker/postgres-plus:17 | 5432 | PostgreSQL database | | minio | minio | minio/minio | 9000 | S3-compatible object storage |

Postgres credentials: postgres / password (local dev only)

Application Services (docker-compose.jobs.yml)

| Service | Container | Port | Purpose | |---------|-----------|------|---------| | constructive-admin-server | constructive-admin-server | 3002 | Internal admin GraphQL API (header-based routing) | | constructive-server | constructive-server | 3000 | Public GraphQL API (domain-based routing) | | send-email-link | send-email-link | — | Email function (invite, password reset, verification) |

Running Application Services

The application services require a built Docker image:

# Build the constructive image
docker-compose -f docker-compose.jobs.yml build

# Start all application services
docker-compose -f docker-compose.jobs.yml up -d

Postgres Images

| Image | Use Case | |-------|----------| | ghcr.io/constructive-io/docker/postgres-plus:17 | Recommended — includes all extensions needed by constructive | | pyramation/postgres:17 | Lightweight alternative with common extensions |

PostgreSQL 17+ is required for security_invoker views. Older images will fail with "unrecognized parameter security_invoker" errors.

Database Deployment

Deploy to Local Database

Prerequisite: Ensure PostgreSQL is running and PG env vars are loaded. See pgpm skill (references/docker.md) and pgpm skill (references/env.md).

pgpm deploy --createdb --workspace --all --yes

Deploy to Remote Database

Point pgpm at a remote Postgres instance via environment variables:

export PGHOST=remote-host.example.com
export PGPORT=5432
export PGUSER=postgres
export PGPASSWORD=secure-password
export PGDATABASE=constructive

pgpm deploy --workspace --all --yes

Verify Deployment

pgpm verify

Revert (Rollback)

# Revert last change
pgpm revert --yes

# Revert to a tagged release
pgpm revert --to @v1.0.0 --yes

# Revert everything
pgpm revert --all --yes

Docker Image Build

The Constructive monorepo builds a multi-stage Docker image:

Build Stages

1. build stage — Node.js 22, installs pnpm, runs pnpm install --frozen-lockfile and pnpm run build
2. constructive stage — Runtime image with built artifacts, PostgreSQL client, and CLI shims

CLI Shims

The Docker image exposes three CLI commands:

| Command | Maps To | |---------|---------| | constructive | node /app/packages/cli/dist/index.js | | cnc | node /app/packages/cli/dist/index.js | | pgpm | node /app/pgpm/pgpm/dist/index.js |

Building Locally

docker build -t constructive:dev .

Makefile Targets

| Target | Command | Purpose | |--------|---------|---------| | make up | docker-compose up -d | Start Postgres + MinIO | | make down | docker-compose down -v | Stop and clean up | | make ssh | docker exec -it postgres /bin/bash | Shell into Postgres container | | make roles | pgpm admin-users bootstrap/add | Bootstrap database roles | | make install | docker exec postgres /sql-bin/install.sh | Run install script in container |

Environment Variables

Server Configuration

| Variable | Description | Example | |----------|-------------|---------| | API_IS_PUBLIC | true for public API, false for admin (header-based) | true | | API_EXPOSED_SCHEMAS | Comma-separated schemas to expose via GraphQL | metaschema_public,services_public | | API_ANON_ROLE | PostgreSQL role for unauthenticated requests | anonymous | | API_ROLE_NAME | PostgreSQL role for authenticated requests | authenticated | | API_ENABLE_SERVICES | Enable services schema (admin only) | true | | API_META_SCHEMAS | Meta schemas for validation and routing | metaschema_public,services_public | | SERVER_HOST | Server bind address | 0.0.0.0 | | SERVER_ORIGIN | CORS origin | * | | SERVER_TRUST_PROXY | Trust reverse proxy headers | true | | SERVER_STRICT_AUTH | Enforce strict authentication | false |

Database Connection

| Variable | Description | Default | |----------|-------------|---------| | PGHOST | PostgreSQL host | localhost | | PGPORT | PostgreSQL port | 5432 | | PGUSER | PostgreSQL user | postgres | | PGPASSWORD | PostgreSQL password | password | | PGDATABASE | Target database name | — |

Admin vs Public API

The Constructive platform runs two API servers:

• Admin server (API_IS_PUBLIC=false, port 3002) — uses header-based routing (X-Api-Name, X-Database-Id, X-Meta-Schema). Used internally by the Constructive admin UI.
• Public server (API_IS_PUBLIC=true, port 3000) — uses domain-based routing. Serves external client applications.

Networking

All Docker Compose services share the constructive-net network, allowing inter-service communication by container name (e.g., postgres:5432 from within the constructive-server container).

Troubleshooting

| Issue | Cause | Fix | |-------|-------|-----| | Port 5432 in use | Another Postgres instance running | Stop it or change the port in docker-compose.yml | | security_invoker error | Postgres version < 17 | Use postgres-plus:17 or pyramation/postgres:17 image | | role "authenticated" does not exist | Missing bootstrap | Run pgpm admin-users bootstrap --yes | | Container not on network | Network mismatch | Check docker network ls for constructive-net | | Build fails at pnpm install | Lockfile mismatch | Run pnpm install locally first to update lockfile |