OnePlatform Deployment Guide¶

This guide covers production deployment, configuration, and operations for OnePlatform — a self-hosted data integration and low-code application platform.

Prerequisites¶

Quick Start¶

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

# 2. Copy the example environment file and fill in secrets
cp .env.example .env
$EDITOR .env

# 3. Start all services
docker compose -f docker/docker-compose.yml up -d

# 4. Follow the first-run wizard in your browser
open http://localhost:8080

Note: The UI is served on port 8080. The API gateway listens on port 3000.

The setup wizard (bootstrap) runs automatically on first launch. It guides you through creating the first admin user and generates the master encryption key. Save the master key before the timer expires — it cannot be recovered.

Configuration¶

All configuration is done through environment variables. Copy .env.example to .env and customise the values below.

Core settings¶

Database¶

Object storage (MinIO)¶

Email (SMTP)¶

Email is optional. When unset, password reset and email verification are disabled.

Rate limiting¶

Ingestion¶

Ontology¶

Execution / Plugin sandbox¶

Security¶

Production Checklist¶

Work through this list before going live.

TLS¶

• Put a TLS-terminating reverse proxy (Nginx, Caddy, or a cloud load balancer) in front of the gateway.
• Set OP_BASE_URL to https://your-domain.com.
• Set OP_ALLOWED_ORIGINS to https://your-domain.com.
• Redirect all HTTP to HTTPS at the proxy level.
• Set OP_WEBHOOK_ALLOW_HTTP=false (default).

Secrets¶

• Replace ALL default passwords: POSTGRES_PASSWORD, OP_MINIO_PASSWORD.
• Generate a strong OP_SERVICE_TOKEN_SECRET (openssl rand -hex 32).
• Store the master encryption key (shown during first-run wizard) in a password manager or secrets vault. It cannot be recovered if lost.
• Rotate secrets annually or immediately after a suspected breach.

Backups¶

• Enable PostgreSQL continuous archiving (WAL) or automated snapshots.
• Configure MinIO bucket replication or scheduled backups for object storage.
• Test restore procedures before going live.
• Store backups in a separate region/account from the primary deployment.

Monitoring¶

• Export container metrics to a monitoring system (Prometheus/Grafana or cloud-native).
• Set up alerts on: high error rate, disk > 80%, memory > 85%, failed sync jobs.
• Subscribe to the /v1/health endpoint for uptime monitoring.
• Enable log shipping to a log aggregation system (Loki, Datadog, CloudWatch, etc.).

Access control¶

• Create dedicated admin accounts (do not use the bootstrap admin in day-to-day operations).
• Assign least-privilege roles to each team member.
• Enable email verification (OP_REQUIRE_EMAIL_VERIFICATION=true) if open sign-up is allowed.

Scaling Guide¶

OnePlatform's services are stateless (except PostgreSQL and Redis) and can be scaled horizontally.

Stateless services (scale out freely)¶

# Example: scale gateway to 3 replicas
docker compose -f docker/docker-compose.yml up -d --scale gateway=3

Stateful services (do not scale without care)¶

Minimum production topology¶

                         [Load Balancer / TLS terminator]
                                    |
                   ┌────────────────┼────────────────┐
                   |                |                |
              [gateway]        [gateway]        [gateway]
                   |                |                |
          ┌────────┴────────────────┴────────────────┘
          |        |         |         |        |      |      |     |
       [auth] [ingestion] [ontology] [pipeline] [app] [plugin] [logging] [execution]
          |                                                               |
          └──────────────────────[postgres] [redis] [minio]──────────────┘

Troubleshooting¶

"Could not connect to OnePlatform" on the setup page¶

The browser cannot reach the API gateway.

1. Check that Docker is running: docker ps
2. Check all containers are up: docker compose -f docker/docker-compose.yml ps
3. Check the gateway port: curl http://localhost:3000/healthz
4. Check gateway logs: docker compose -f docker/docker-compose.yml logs gateway

Services fail to start¶

Common causes:

• Missing .env file: cp .env.example .env and fill in required values.
• Port conflict: Another service is using port 3000 (API gateway) or 8080 (UI). Free the conflicting port or adjust docker-compose port mappings.
• Database connection error: Check POSTGRES_PASSWORD matches in all services.
• Insufficient memory: Increase Docker's memory limit to at least 4 GB.

Plugin sandbox errors¶

• Check OP_SANDBOX_POOL_SIZE is not 0.
• Check container has sufficient CPU (sandbox processes are CPU-bound).
• Review plugin logs: docker compose -f docker/docker-compose.yml logs plugin.

Sync jobs stuck in "running"¶

• Check the ingestion service is running: docker compose -f docker/docker-compose.yml ps ingestion.
• Check Redis is reachable (BullMQ queue): docker compose -f docker/docker-compose.yml logs redis.
• Manually cancel stuck jobs via op connector trigger <id> or the connector detail page.

Migrations failing¶

• Check OP_MIGRATION_TIMEOUT is long enough for your data volume.
• Review ontology logs: docker compose -f docker/docker-compose.yml logs ontology.
• Migrations can be rolled back from the Ontology > Migrations page.

Updating OnePlatform¶

# 1. Pull the latest images
docker compose -f docker/docker-compose.yml pull

# 2. Restart services with zero-downtime rolling update (requires a load balancer)
docker compose -f docker/docker-compose.yml up -d --no-deps --build

# 3. Run database migrations (auto-applied on service startup)
# Watch the logs to confirm migration success
docker compose -f docker/docker-compose.yml logs --follow ontology ingestion

Always take a database snapshot before updating.