Galpi

Install and set up

Run Galpi on one server with Docker Compose, become the first administrator with the setup token from the log, and finish with the wizard.

What you need

  • A Linux server (2 vCPU, 4 GB of memory and 20 GB of disk are enough to start) with Docker and Compose. Without Docker: curl -fsSL https://get.docker.com | sh.
  • A domain name whose DNS points at the server's public IP (for example galpi.example.com).
  • Ports 80 and 443 open from outside (Let's Encrypt). Also 9443 if nodes use the bundled S3.
  • Somewhere to run chat VMs: a Fly Sprites token, or servers to join as nodes (E2B needs KVM; Sysbox does not). You can decide later. → Where VMs run

Three steps

bash
cd deploy
cp .env.example .env && chmod 600 .env     # 1. fill in GALPI_DOMAIN, SECRETS_KEY …
./build.sh                                  # 2. build the image (a few minutes)
docker compose up -d                        # 3. start it

In .env you must set GALPI_DOMAIN and SECRETS_KEY (openssl rand -base64 32), and FORGEJO_ADMIN_PASSWORD (openssl rand -hex 24) if you use Galpi's built-in repositories. Everything else can be set in the first-run screens; a value saved there wins over the environment.

Keep SECRETS_KEY somewhere safe

Secrets saved in the app (tokens, passwords) are sealed with this key. Lose it and you must enter them again; restoring from a backup needs the same key too.

COMPOSE_PROFILES in .env chooses what runs alongside. The default is https,git.

Profile Starts When
(always) galpi The Galpi server and web app
https caddy Automatic HTTPS. Leave it out behind another proxy
git forgejo, forgejo-restore, forgejo-backup Built-in repositories ("start from an empty repository") and their backup
s3 s3, s3-bucket Bundled S3 (versitygw) for small installs. Larger ones put an external S3 in S3_*

First visit

  1. After a few seconds open https://<GALPI_DOMAIN>. You get a screen asking for a setup token. Caddy fetches the certificate on that first request.

  2. The token is in the log and in DATA_DIR/setup-token (mode 600).

    bash
    docker compose logs galpi | grep '\[setup\]'
    
  3. Enter the token and your email. You become the first system administrator (signed in at once, no mail needed) and the wizard continues. The token works once.

A server that people already use (someone has signed in or a project exists) counts as set up, so upgrading an existing install never shows the wizard.

Wizard steps

Step What you set Check
Server address PUBLIC_URL, and VM_CALLBACK_URL, the address VMs call Galpi on (node with nodes)
Mail SMTP_URL, MAIL_FROM. Empty: mail goes to the server log only Send me a test mail
Sign-in Email code, OIDC, or both Reads the issuer and shows the redirect URI to register
VMs Sprites, E2B nodes or Sysbox nodes; for nodes, the join command and VM sizes Sprites: lists with the token
File storage S3 endpoint, bucket, keys. Empty: the server's disk. Database replication (Litestream) goes here too Writes, reads and deletes a test file
LLM Default model (Anthropic or OpenAI-compatible), per-tier models (Fast, Smart, Deep), free model, daily limit, agent instructions for every chat Sends a short question
Policy and budgets Sign-up domains, guests, who creates projects, project-less chats, ChatGPT, chat retention, how long and how much the store keeps deleted things, question limits, budgets
Preview GeoDNS, CDN or later; the preview domain
Built-in repositories On or off, Forgejo address and admin account Signs in to the Forgejo API
Finish Summary, restart, first project

Moving between steps saves what you changed first. If it can't be saved (a wrong value, or a confirmation is needed), you stay on the step and see why. Everything can be changed later in System admin → Settings.

System admin → Settings. The wizard's values live here afterwards.System admin → Settings. The wizard's values live here afterwards.
System admin → Settings. The wizard's values live here afterwards.

Ports and volumes

What Port Volume Note
galpi 127.0.0.1:8080 (GALPI_HTTP_BIND) galpi-data:/data Database and saved settings, replicated by Litestream when S3 is set
caddy 80, 443/tcp, 443/udp, 9443 caddy-data, caddy-config Certificates live in caddy-data
forgejo none (only Galpi, on an internal network) forgejo-data Repositories and database
s3 127.0.0.1:7070 (outside via Caddy's 9443) s3-data Buckets are folders

Behind another proxy

  • Remove https from COMPOSE_PROFILES and point GALPI_HTTP_BIND where the proxy reaches. The image runs in production mode, so the sign-in cookie is Secure: signing in over http:// does not work.
  • The proxy terminates TLS and must not buffer streams (nginx: proxy_buffering off). Rewrite X-Forwarded-For to the client's address (proxy_set_header X-Forwarded-For $remote_addr).
  • What is counted per address (such as the sign-in code request limit) uses the client address in X-Forwarded-For only when the connecting side is a trusted proxy. Proxies on the same host or a private network (loopback, private addresses) are always trusted. List proxies on public addresses (cloud load balancers, a proxy on another host) in GALPI_TRUSTED_PROXIES, addresses or networks separated by commas (34.120.0.0/16,2001:db8::1). Otherwise everyone behind it counts as the proxy's one address, and many people opening the sign-in page at once can be turned away. Never list an address clients can reach directly.
  • Galpi speaks HTTP/1.1 only; don't turn on h2c from the proxy to Galpi.
  • Galpi keeps idle connections for 130 seconds (GALPI_KEEPALIVE_MS); the proxy must close first. In nginx keep keepalive_timeout under 130 seconds and add proxy_http_version 1.1 and proxy_set_header Connection "".
  • Match the bundled Caddy's body limits: in nginx client_max_body_size 600m, client_header_timeout 30s, client_body_timeout 60s, and proxy_read_timeout 1h so answer streams aren't cut.
A test install without a public name

With CADDY_TLS=internal in .env, Caddy serves HTTPS with its own certificate (browsers warn). Node VMs don't trust it, so use VM_CALLBACK_URL=node. Not for production.

Restart policy

Keep restart: unless-stopped. Restart in the app ends the server with exit code 75 and this policy starts it again.

Next

Esc