Skip to main content
Docker Compose is the supported way to run asobeast. Three commands take you from a clone to a running instance, because the API applies its own database migrations and seeds the default workspace when it boots.

​
Install asobeast

1

Clone the repository

2

Generate the two required secrets

Both values are URL safe and stay in the ignored root .env. Compose refuses to start when either one is missing or empty, so a half configured instance never boots. chmod 600 keeps the file readable only by its owner.
3

Start the stack

--wait returns only once every health check passes, so a successful exit means the stack is actually serving.
4

Create the owner account

Open http://localhost:3000. A fresh installation redirects to registration. The first account becomes the owner, and registration closes automatically afterwards unless you set AUTH_ALLOW_REGISTRATION=true.

​
What does each service do?

There is no manual migration step. The API waits for PostgreSQL and Redis to report healthy, applies every pending forward migration, seeds the default workspace and then listens.

​
What is exposed?

Only port 3000, published by the web container. The API, PostgreSQL and Redis stay on Docker networks that are not reachable from the host, and the backend network is marked internal. The browser never talks to the API directly. It calls /api/backend/* on the web origin, and the Next.js proxy forwards those requests to API_INTERNAL_URL, which Compose sets to http://api:4000. The web image reads that value at runtime, so pointing it at a different API needs no rebuild. Every service has a health check and a restart policy, and the application containers run as non root users.

​
Verify the installation

/admin/queues and /docs answer 404 to anyone who is not a signed in owner. That is deliberate. A 403 would confirm the surface exists, so the gate answers as though it does not.

​
Customize the installation

The root .env carries only POSTGRES_PASSWORD and AUTH_SECRET. Everything else has a working default. Copy apps/api/.env.example to apps/api/.env only when you want an optional feature such as email alerts, the AI assisted audit, a different collection schedule or different retention windows. Compose loads that file when it exists and ignores it when it does not. See Configuration reference. Values set directly in docker-compose.yml, including DATABASE_URL, REDIS_HOST and REDIS_PORT, override anything an older apps/api/.env sets for the same keys. Run docker compose config to inspect the resolved topology.

​
Common operations

Never paste resolved Compose configuration into an issue, because it contains the database password.

​
Next steps

Import an app

Paste a store URL and start tracking.

Authentication and accounts

The owner bootstrap, sessions and registration.

Back up PostgreSQL

The only thing in the stack that needs backing up.

Upgrade and roll back

Forward migrations, pinned tags and what a rollback really means.
Last modified on July 31, 2026