Single host: Docker or Podman
The whole platform on one Linux server, from the compose bundle in
deploy/single-host.
Docker and rootless Podman run the same bundle. Read what differs from Kubernetes
first: one machine has no high availability.
What runs
Only the edge (Caddy) is published, on ports 80 and 443. Everything else sits on internal networks:
Studio, the control plane, auth, the API engine, the platform Postgres, NATS and the bundled object
store. Each project's database is a container of its own (excalibase-<projectId>-postgres) with
its tier's memory and CPU, reachable on the host's 127.0.0.1 only.
The control plane never holds the engine socket: a small proxy does, and creates only project-shaped containers (no privileged mode, host paths, host namespaces or extra capabilities).
Before you start
- A Linux server with 4 CPU and 8 GiB RAM and Docker Engine 24+ with the Compose plugin, or Podman 4.9+ (see Rootless Podman).
- DNS:
studio.<domain>,api.<domain>andfiles.<domain>pointing at the server (a wildcard*.<domain>works), and*.apps.<domain>for container apps. - Ports 80 and 443 reachable from the internet: the edge gets Let's Encrypt certificates for you.
Install with Docker
git clone --depth 1 --branch v1.5.1 https://github.com/excalibase/excalibase.git
cd excalibase/deploy/single-host
./init.sh --domain example.com --admin-email you@example.com
docker compose up -d
docker compose logs bootstrap # prints the first admin's password, once
Open https://studio.example.com and sign in as admin with that password. Your projects' APIs
are at https://api.example.com/<projectId>/graphql and https://api.example.com/<projectId>/api/v1/<table>.
init.sh writes .env (mode 600) with random secrets, your domain and the engine socket. Keep
.env with the volumes: the database was created with those secrets, and init.sh refuses to
overwrite it. A weak or reused secret stops the stack at its preflight step.
init.sh option | Does |
|---|---|
--domain <domain> | serves studio., api. and files.<domain>; localhost uses the edge's own CA |
--admin-email <email> | the first admin's address and the Let's Encrypt account |
--apps | container apps, at <app>-<project>.apps.<domain> |
--app-domain <domain> | another parent domain for apps |
--app-sandbox none | apps without gVisor (trusted code only) |
--documentdb | DocumentDB projects (MongoDB-compatible) |
--manual-unseal | the vault key is never stored on the server (see Configuration) |
--studio-allow "<cidrs>" | who may open Studio, e.g. your office range |
--engine podman | rootless Podman instead of Docker |
New sign-ups are invite-only by default; add REGISTRATION_MODE=open to .env to let anyone sign up. Email for
invitations, verification and password resets is off until you configure it: see
Configuration.
Container apps
Apps run on the same host, each in its own container with the plan's memory and CPU, no published port and no host path, behind the edge with a certificate per hostname.
On Docker, run them under gVisor, a user-space kernel, so app code does not share the host's kernel directly:
# Debian / Ubuntu (other systems: https://gvisor.dev/docs/user_guide/install/)
curl -fsSL https://gvisor.dev/archive.key | sudo gpg --dearmor -o /usr/share/keyrings/gvisor-archive-keyring.gpg
echo "deb [arch=$(dpkg --print-architecture) signed-by=/usr/share/keyrings/gvisor-archive-keyring.gpg] https://storage.googleapis.com/gvisor/releases release main" \
| sudo tee /etc/apt/sources.list.d/gvisor.list
sudo apt-get update && sudo apt-get install -y runsc
sudo runsc install -- --network=host && sudo systemctl restart docker
docker info | grep runsc
Then install with --apps (or add APP_HOSTING_ENABLED=true to .env and run
docker compose up -d again). Without gVisor the control plane refuses to start with apps on, unless
you choose --app-sandbox none: apps then run with every capability dropped except
NET_BIND_SERVICE, but on the host's kernel. Choose it only for code you trust.
| Kubernetes | Single host | |
|---|---|---|
| Sandbox | gVisor | gVisor on Docker; none on rootless Podman |
| Between projects | NetworkPolicy | one internal network per project |
| Internet from an app | allowed, private ranges denied | none, unless APP_EGRESS=internet in .env |
| Disk | a volume of the size asked | a volume on the host's disk; the size is recorded, not enforced |
| Copies | up to the plan's | one |
Image references need an explicit tag or digest (traefik/whoami:v1.11.0, not traefik/whoami).
DocumentDB projects
./init.sh --domain example.com --admin-email you@example.com --documentdb
A project with DocumentDB gets a gateway container beside its database. Its MongoDB port is
published on the host's 127.0.0.1 only; Studio's Connect card shows the port, the user and the
gateway's CA. From another machine, forward the port over SSH:
ssh -N -L <port>:127.0.0.1:<port> you@your-server.
Rootless Podman
Nothing runs as root: the engine is your user's own Podman.
You need Podman 4.9+ and podman compose backed by Docker Compose v2 (Fedora:
dnf install podman docker-compose; Debian/Ubuntu: apt install podman docker-compose-v2).
podman-compose is not supported. Then, once:
systemctl --user enable --now podman.socket
sudo loginctl enable-linger "$USER" # the stack keeps running after you log out
# as root, if init.sh reports a missing cgroup controller (Ubuntu 22.04 delegates only memory):
sudo mkdir -p /etc/systemd/system/user@.service.d
printf '[Service]\nDelegate=cpu cpuset io memory pids\n' | sudo tee /etc/systemd/system/user@.service.d/delegate.conf
sudo systemctl daemon-reload # then log in again
# for Let's Encrypt on ports 80 and 443:
echo 'net.ipv4.ip_unprivileged_port_start=80' | sudo tee /etc/sysctl.d/90-excalibase.conf && sudo sysctl --system
git clone --depth 1 --branch v1.5.1 https://github.com/excalibase/excalibase.git
cd excalibase/deploy/single-host
./init.sh --engine podman --domain example.com --admin-email you@example.com
podman compose up -d
podman compose logs bootstrap
What differs from Docker:
- No app sandbox. Rootless Podman cannot run gVisor with the plan's limits, so apps need
--apps --app-sandbox noneand share the host's kernel: trusted code only. Use Docker with gVisor, or Kubernetes, for code you do not control. - On
localhost, without the sysctl above, the edge listens on 8080 and 8443 (https://studio.localhost:8443). - The edge sees Podman's port forwarder, not the client, so
--studio-allowand per-client rate limits cannot tell clients apart: restrict Studio with the host firewall. - On SELinux hosts
init.shlets the engine proxy alone run unconfined, so it can reach the socket.
Operations
docker compose ps # health (podman compose ps)
docker compose logs -f provisioning
docker ps --filter label=excalibase.managed=true # project databases and apps
Project databases publish their port on 127.0.0.1; reach them from elsewhere with an SSH tunnel.
Removing an install
docker compose down -v removes the platform's own containers and volumes, but not what the
platform created for projects. Remove project containers and volumes first, then the stack, then
the project networks (the edge stays attached to them until the stack is down):
docker ps -aq --filter label=excalibase.managed=true --filter name=-documentdb | xargs -r docker rm -f
docker ps -aq --filter label=excalibase.managed=true | xargs -r docker rm -f -v
docker volume ls -q --filter label=excalibase.managed=true | xargs -r docker volume rm
docker compose down -v
docker network ls -q --filter label=excalibase.managed=true | xargs -r docker network rm
With Podman, use podman and podman compose. Delete .env only together with the volumes.