Skip to content
excalibase
single-host
Self-hostingbeta

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> and files.<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 optionDoes
--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
--appscontainer apps, at <app>-<project>.apps.<domain>
--app-domain <domain>another parent domain for apps
--app-sandbox noneapps without gVisor (trusted code only)
--documentdbDocumentDB projects (MongoDB-compatible)
--manual-unsealthe vault key is never stored on the server (see Configuration)
--studio-allow "<cidrs>"who may open Studio, e.g. your office range
--engine podmanrootless 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.

KubernetesSingle host
SandboxgVisorgVisor on Docker; none on rootless Podman
Between projectsNetworkPolicyone internal network per project
Internet from an appallowed, private ranges deniednone, unless APP_EGRESS=internet in .env
Diska volume of the size askeda volume on the host's disk; the size is recorded, not enforced
Copiesup to the plan'sone

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 none and 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-allow and per-client rate limits cannot tell clients apart: restrict Studio with the host firewall.
  • On SELinux hosts init.sh lets 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.