GitHubGet started
ProductHow it worksDocsCloudsoonGitHubGet started

/self-host

Your servers. Your data.

Plat5 runs as one Docker Compose stack on a single machine. Bring an identity provider, a TLS edge, and your services. The runtime is Apache-2.0.

/what-runs

What you run.

Published images from GitHub's container registry, pinned to one release. Only the gateway faces the internet.

  • gatewayPublished on :5001, behind your TLS edge
  • identityPrivate
  • auditPrivate
  • route-registryPrivate. Admin token required
  • Postgres, etcd, ValkeyPrivate
  • Your servicesPrivate, on the same network

/steps

Four steps to production.

  1. 01

    Choose an identity provider.

    Run Plat5 Auth from its own compose file, with your SMTP server for sign-in emails, or point Plat5 at the provider you already use.

  2. 02

    Configure and start Plat5.

    Pin a release, set four secrets and your provider. Edit roles.yml before first boot. One command brings up the stack.

    compose/.env
    PLAT5_VERSION=v0.6.0
POSTGRES_PASSWORD=<hex>
ADMIN_TOKEN=<random>
INTERNAL_AUTH_TOKEN=<random>

AUTH_ISSUER=https://auth.acme.com
AUTH_JWKS_URI=https://auth.acme.com/.well-known/jwks.json
AUTH_ALLOWED_AUDIENCES=plat5
AUTH_USER_ID_CLAIM=properties.user_id   # sub for most providers
# APIKEY_BRAND=acme                     # keys look like acme-k-2-…
    terminal
    git clone https://github.com/plat5dev/plat5.git
cd plat5/compose
cp .env.template .env        # fill it in
docker compose -f docker-compose.prod.yml --env-file .env up -d
  3. 03

    Put TLS in front.

    The gateway speaks HTTP. Terminate TLS with Caddy, nginx or a Cloudflare tunnel, and send your API hostname to the gateway.

  4. 04

    Attach your services and publish routes.

    Run your services on Plat5's Docker network, under the names your routes use. Apply the identity and audit route catalogs and your own routes to the registry.

    terminal
    # From a container on the plat5_plat5 network.
# The registry is never public.
curl -X POST http://route-registry:5002/apply \
  -H "Authorization: Bearer $ADMIN_TOKEN" \
  -H "Content-Type: application/yaml" \
  --data-binary @services/identity/routes.yml

curl ... --data-binary @services/audit/routes.yml
curl ... --data-binary @your-api/routes.yml

The full self-hosting guide →

/good-to-know

Good to know.

  • Pin a release.

    Set PLAT5_VERSION to a released tag. Every runtime image comes from that one pin.

  • Keep services private.

    Your services trust the path the gateway wrote, so only the gateway should reach them.

  • The issuer must match exactly.

    The token's iss, the gateway's AUTH_ISSUER and your app's sign-in URL are the same string.

  • Audit is on by default.

    Set AUDIT_ENABLED=false to turn it off for the whole deployment.

  • Bring your own telemetry.

    Every component logs JSON and serves Prometheus metrics. Set an OTLP endpoint to export traces and metrics.

  • Your brand on keys.

    Set APIKEY_BRAND before customers create keys. Changing it later invalidates existing ones.

Rather not run it yourself?

Plat5 Cloud is coming soon: your own isolated Plat5, run for you.

About Cloudplat5 on GitHub