Running the Archestack images

Archestack is two container images and a PostgreSQL database. Every way of running it, from a laptop to a Kubernetes cluster, starts the same two images with different settings. This page says what they are, what any setup has to give them, and which way of running them fits where. Every setting the images take is on Image settings.

The images

Every release is tagged with its version, such as 1.0.42, and the newest one is also latest. Run a version number in production, so you know what runs and can take that same version from test to production. The API and the web image of one release belong together.

What every setup gives them

1. PostgreSQL 16, with a user that may create databases. The API makes its own databases on the first start and one pair for every workspace after that, so there is nothing to prepare. Give PostgreSQL 1 GB of shared memory (--shm-size 1g in Docker): its statistics grow with every database, and the default runs out at about a thousand workspaces.
2. Two folders that survive a restart, /files for uploads and /backups for backups. Without them, uploads disappear at the next update.
3. A route to each image. The browser loads the web image and calls the API under /api, with live updates over a WebSocket under /hubs. Both can share one address, which the starter kits do, or the API gets an address of its own:

   One address (the kits do this)          Two addresses
   
   https://apps.example.com                https://editor.example.com  ->  omnicore-web
     /api/...   ->  omnicore-api :8080     https://api.example.com     ->  omnicore-api
     /hubs/...  ->  omnicore-api :8080
     /...       ->  omnicore-web :80       VITE_API_URL=https://api.example.com
   
   VITE_API_URL empty

   Under a path of a hostname, such as https://apps.example.com/archestack/, both images are told the path (BASE_PATH and Http__PathBase).
4. A first admin. Either set Identity__InitialAdminEmail and Identity__InitialAdminPassword, or open the builder right after the first start and create the admin there. Until somebody does, whoever reaches the builder first becomes the admin, so do not leave a fresh installation open on the internet.
5. Time to start. The API answers /health with {"status":"ok"} only once every database is migrated. A first start takes a minute or two, and longer with many workspaces, so check readiness on /health and give the start enough time.

The ways to run them

Whichever you choose, your applications reach it the same way: from the repository, through a pipeline.

Trying it with docker run

Three containers on one Docker network: PostgreSQL, the API on port 8080 and the builder on port 8081. Pick a password of your own instead of change-me.

# Archestack on this machine with plain docker run: the builder on http://localhost:8081
docker network create archestack
docker volume create archestack-postgres

docker run -d --name archestack-postgres --network archestack --shm-size 1g \
  -e POSTGRES_USER=archestack -e POSTGRES_PASSWORD=change-me -e POSTGRES_DB=postgres \
  -v archestack-postgres:/var/lib/postgresql/data postgres:16

docker run -d --name archestack-api --network archestack -p 8080:8080 \
  -e ASPNETCORE_URLS=http://+:8080 \
  -e "ConnectionStrings__DefaultConnection=Host=archestack-postgres;Database=omnicore-db;Username=archestack;Password=change-me" \
  -e "ConnectionStrings__Core=Host=archestack-postgres;Database=omnicore-core;Username=archestack;Password=change-me" \
  -e "ConnectionStrings__Identity=Host=archestack-postgres;Database=omnicore-identity;Username=archestack;Password=change-me" \
  -e ConnectionStrings__Keycloak= \
  -e Database__CreateMissing=true \
  -e Identity__Provider=Builtin -e Identity__AppBaseUrl=http://localhost:8081 \
  -e Files__Directory=/files -e Backup__Directory=/backups \
  -v archestack-files:/files -v archestack-backups:/backups \
  nickpeelman/omnicore-api:latest

docker run -d --name archestack-web --network archestack -p 8081:80 \
  -e VITE_API_URL=http://localhost:8080 -e VITE_UI_MODE=dashboard \
  -e API_INTERNAL_URL=http://archestack-api:8080 \
  nickpeelman/omnicore-web:latest

Open http://localhost:8081 once http://localhost:8080/health answers, and create the first admin. The builder and the published app (/app) are both on that port, and the API on 8080 answers the browser directly. To remove it again:

docker rm -f archestack-web archestack-api archestack-postgres
docker network rm archestack
# Everything you made is in the volumes; this deletes it:
docker volume rm archestack-postgres archestack-files archestack-backups

This is for trying. A server needs restarts, updates, certificates and backups taken off the machine, which Hosting with Docker sets up.

Other container platforms

Azure Container Apps, Amazon ECS, Google Cloud Run and similar platforms run the same images. Check these before you choose one:

• The database. Use the platform's managed PostgreSQL 16 (Azure Database for PostgreSQL, Amazon RDS, Cloud SQL), with a user that may create databases. Do not run PostgreSQL itself on a network file share.
• A volume for /files and /backups, such as Azure Files, Amazon EFS or Filestore. With more than one API instance, every instance mounts the same one.
• At least one API instance always running. Scheduled events, the mail outbox and backups run inside the API, so a platform that scales to zero stops them. Set the minimum to one instance, and on Cloud Run keep the CPU allocated outside requests.
• WebSockets to /hubs for live updates. A connection the platform cuts is opened again, but a very short idle timeout makes updates arrive late.
• Large requests. Package imports and file uploads can be large: allow request bodies of at least 100 MB and requests that take a few minutes.
• More than one API instance works without sticky sessions: they share their state through PostgreSQL. Each needs a direct connection to it for that, so with a connection pooler such as PgBouncer in between, set ConnectionStrings__Cluster to PostgreSQL itself.

Where this goes next

Image settings lists every setting of both images. Capacity and sizing says how much one installation serves, and Workspaces and hosting how workspaces share it.