Deploy with Docker

Use the official Superinterface Docker image when you want a sealed artifact that already contains the production Next.js build and the admin CLI. The container expects a managed Postgres instance such as Neon/Vercel Postgres or Supabase—no bundled database is included.

Image overview

Image name: supercorp/superinterface-server

Default port: 3000

Entry point: node bin/index.cjs run server

CLI access: override the entrypoint or use docker exec to run any command (for example node bin/index.cjs prisma deploy)

1. Pull the image

docker pull supercorp/superinterface-server:latest

The latest tag tracks the most recent release. Pin to the semantic version you are deploying—e.g. 1.1.7—so you can roll forward or back deliberately.

2. Provide environment variables

The container only reads configuration from environment variables. At minimum you need the Postgres URLs and the public base URL.

Variable	Required	Notes
`DATABASE_URL`	Yes	Pooled connection string (Neon/Vercel Postgres, Supabase, or another Prisma-supported host).
`DIRECT_URL`	Yes (Neon)	Direct connection string used by migrations. If your provider does not supply one (for example Supabase), reuse `DATABASE_URL`.
`NEXT_PUBLIC_SUPERINTERFACE_BASE_URL`	Yes	The externally reachable base URL, e.g. `https://api.example.com`.
`DATABASE_ADAPTER`	Optional	Set to `direct` for Supabase or any non-Neon Postgres. Defaults to `neon`.
`QSTASH_TOKEN`	Optional	Required for scheduled tasks and Upstash Workflow.
`QSTASH_CURRENT_SIGNING_KEY`	Optional	Enables QStash signature verification.

You can pass these values individually with -e flags or load them from a file using --env-file.

3. Run database migrations

Apply Prisma migrations once before serving traffic. You can do this from your workstation or via the container. The example below uses the container with an env file:

docker run \ --rm \ --env-file ./self-host.env \ supercorp/superinterface-server:1.1.7 \ node bin/index.cjs prisma deploy

Prefer running migrations from your workstation? Use the same environment variables with npx @superinterface/server prisma deploy.

Repeat the command whenever you upgrade to a version that ships new migrations.

4. Start the container

docker run \ --name superinterface \ -p 3000:3000 \ --env-file ./self-host.env \ supercorp/superinterface-server:1.1.7

Override PORT if you want to expose the server on a different port, and add -e DATABASE_ADAPTER=direct in your env file when you are not using Neon/Vercel Postgres.

5. Seed organizations and API keys

Use the bundled CLI inside the running container to create organizations and keys:

docker exec -it superinterface node bin/index.cjs organizations create docker exec -it superinterface node bin/index.cjs organizations api-keys create

Running commands from your workstation works too—just use npx @superinterface/server organizations ... with the same environment variables.

The commands inherit the environment variables you supplied to docker run, so they operate on the same database. If you need to script provisioning, you can also run these commands in a one-off container by adding --rm as in the migration step.

6. Upgrades and tagging

When a new server version ships, pull the updated tag, rerun the migrations, and restart your workload. The entrypoint leaves migrations to you, which makes blue/green or rolling deployments straightforward across Kubernetes, ECS, Fly.io, Azure Container Apps, and other orchestrators.

Docker Compose examples

The @superinterface/server package includes ready-to-use Docker Compose configurations for common deployment scenarios:

Local development with PostgreSQL

Use docker-compose.yml to run Superinterface with a local PostgreSQL database in Docker:

# Download the compose file curl -O https://raw.githubusercontent.com/supercorp-ai/superinterface/main/packages/server/docker-compose.yml # Start all services (database, migrations, server) docker compose up

This configuration includes:

PostgreSQL 16 database with persistent storage

Automatic database migrations

Server running on port 3000

Supabase deployment

Use docker-compose.supabase.yml to connect to a Supabase PostgreSQL instance:

# Download the compose file curl -O https://raw.githubusercontent.com/supercorp-ai/superinterface/main/packages/server/docker-compose.supabase.yml # Set your Supabase connection strings (optional - defaults are provided) export SUPABASE_DATABASE_URL="postgresql://postgres.xxx:[email protected]:6543/postgres?pgbouncer=true" export SUPABASE_DIRECT_URL="postgresql://postgres.xxx:[email protected]:5432/postgres" # Start the server docker compose -f docker-compose.supabase.yml up

This configuration:

Uses Supabase pooled connections for the application

Uses direct connections for migrations

Sets DATABASE_ADAPTER=supabase automatically

Both examples are production-ready and can be customized for your specific needs. View the complete files on GitHub.