Project conventions

There is no pipeline DSL. The pipeline is always fetch → build → (test) → deploy, and a project’s deploy mode decides where the compose file comes from.

Deploy modes

Pick one when you create the project:

Mode Source What it deploys
Compose (default) git repo or ZIP the repo’s docker-compose.yml (path configurable)
Dockerfile git repo or ZIP a single service built from a Dockerfile; the agent synthesizes a one-service compose file around it, publishing container_port on the registered HTTP port
Image none a prebuilt image you name directly (e.g. mariadb:11), with optional volumes; no fetch, no build
Inline compose none a docker-compose.yml you paste into the UI; no fetch, no build

Compose and Dockerfile are source modes: they fetch from git or a ZIP and rebuild every run, so webhooks and manual git/ZIP runs apply. Image and Inline compose are sourceless: there is nothing to clone or build. Deploy them with the Deploy now button in the Trigger a run card on the project’s Deployments tab (trigger manual_deploy). Use them for off-the-shelf images (databases, caches) or a hand-written stack you don’t keep in git.

The Webhooks card on the Deployments tab shows the webhook URLs for every mode. A sourceless project with no Git URL does not need them: a call to its /git webhook is answered with 422 and the message no git_url in payload and project has none.

The conventions below describe Compose mode in full; Dockerfile and Image modes follow the same env/port/volume rules through the compose file the agent synthesizes for them.

One-click app catalog

Instead of writing a compose file by hand, Projects → Browse app catalog offers a searchable grid of ready-made app templates (Redis, Postgres, …). Pick one, fill a short form (project name, port, and any app variables such as a password — generated ones are pre-filled), and the agent creates an Inline compose project from the template with your values substituted.

Leave the port blank for an internal-only app: the agent strips the `` mappings so nothing is published to the host and no nginx vhost is created. This is the right choice for databases and caches that only other containers reach over the shared Docker network.

The catalog is populated from catalog sources holding apps/*.toml templates, managed under Browse app catalog → Manage sources. A source is one of two kinds:

Apps from every enabled source — of either kind — are merged into one list. Each source can hold up to 500 apps, and each template file can be up to 256 KB; anything beyond that is skipped.

Catalog apps reference public images (e.g. redis:7-alpine). Every deploy tries to pull images first (see Images and pulling below), so an internet-connected host fetches them by itself. On an air-gapped host the pull fails quietly, so pre-load the images first (see Troubleshooting). Generated passwords live inside the project’s compose file — copy them from the configure form before creating.

A source template (apps/redis.toml) looks like:

slug = "redis"
name = "Redis"
category = "Database"
description = "In-memory key-value store, cache and message broker."
keywords = ["cache", "kv", "queue"]
http_port = 6379
compose = '''
services:
  redis:
    image: redis:7-alpine
    restart: unless-stopped
    command: ["redis-server", "--requirepass", ""]
    ports: [":6379"]
    volumes: ["redis_data:/data"]
volumes:
  redis_data:
'''

# All top-level keys (including `compose`) must come BEFORE the variables
# blocks — TOML absorbs anything after `[[variables]]` into that table.
[[variables]]
key = "REDIS_PASSWORD"
label = "Redis password"
generate = true            # form field pre-filled with a generated secret

is replaced by the chosen port; every other must be declared in a [[variables]] block (validated on sync).

A [[variables]] block has these fields:

Field Required Meaning
key yes the `` placeholder it fills
label yes the form field’s label
default no a value pre-filled in the form
generate no true pre-fills a freshly generated secret (passwords, tokens)
description no help text for the field

App actions in a template

A template can also ship ready-made actions — for example a database backup and restore. They are copied onto the project when you create it, and you can run or edit them later on the project’s Actions page — open it with the Actions button at the top of the project page (see the Admin UI guide). Add them as [[actions]] blocks. Like [[variables]], they must come after all the top-level keys:

[[actions]]
key = "backup"
label = "Backup (SQL dump)"
kind = "backup"            # run | backup | restore
service = "db"             # compose service the command runs in
command = "mariadb-dump -uroot -p\"$MARIADB_ROOT_PASSWORD\" --all-databases"
filename = "mariadb-.sql"

[[actions]]
key = "restore"
label = "Restore from SQL dump"
kind = "restore"
service = "db"
upload_path = "/tmp/restore.sql"
load_command = "mariadb -uroot -p\"$MARIADB_ROOT_PASSWORD\" < "

The compose file

What the agent adds to your compose file

The agent never edits your file. It adds a small extra file (an override) on top of it at deploy time. For every service the override:

Images and pulling

Before every deploy and every redeploy the agent runs docker compose pull --ignore-buildable. This fetches a newer copy of each image: service (for example a moving :latest tag). Services with build: are skipped here.

If the pull fails — always the case on an air-gapped box — the run log shows a warning and the deploy carries on with the images already on the server.

The pull_policy config key only changes the build step: always adds --pull to docker compose build, so base images in your Dockerfiles are refreshed. never and missing do the same thing (no --pull). See Configuration.

What this means. On a server with internet access, images update themselves on each deploy. On an offline server nothing breaks — the agent just uses what you loaded with docker load.

Editing the compose file in the UI

In Compose mode the compose file normally comes from the repo, but the project’s Settings tab has an optional Edit compose file box where you can paste an inline override. When set, that text is deployed instead of the file at the compose path — the repo is still cloned and the deploy runs in the checkout, so Dockerfiles and relative build contexts still resolve. Leave it blank to deploy the committed file as-is.

Two buttons pre-fill the editor so you don’t start from scratch:

(In Inline compose mode the same box holds the full docker-compose.yml that is deployed verbatim — there is no repo to load from.)

Monorepos

Set a working directory on the project to build from a subdirectory of the repo. When set, the compose-file path, the Dockerfile path, the synthesized override, and the Docker build context all resolve under it; leave it blank to use the repo root. The path is validated (no .. escapes outside the checkout).

Web exposure

Host nginx proxies your-domain → 127.0.0.1:<port>, where <port> is the project’s registered HTTP port. Your app only has to publish that port on the host.

In Compose mode you can write the mapping yourself. Bind it to loopback so only nginx on this server can reach it:

services:
  web:
    build: .
    ports:
      - "127.0.0.1:8101:80"

Ports the agent writes for you are open on every network interface. This covers:

These are written as host:container (for example 8101:80), not 127.0.0.1:8101:80. So other machines can reach the app on that port directly, not only through nginx. If your compose file already publishes a port, the agent does not add it a second time — so a loopback mapping you write yourself wins.

To keep such a port private, block it in front of the server (a network or cloud firewall), or leave the port blank for an internal-only app (see Categories & networking below). Note that Docker writes its own firewall rules for published ports, so a UFW rule on the Firewall page does not block them by default — see Security.

What this means. A loopback address (127.0.0.1) is reachable only from the server itself. A port published on every interface is reachable from any machine that can reach the server’s IP.

The project’s nginx page generates the server block from the domains + port you registered and can apply it in one click (write → nginx -t → reload) when the sudo allowlist is installed; otherwise it shows the equivalent copy-paste commands. A project can serve several domains (one Primary domain; the others 301-redirect to it) and opt each one into HTTPS — see Domains & TLS.

The agent warns in the run log (without blocking) when no service publishes the registered port (project http_port … not published by any service), or when another project claims the same port (http_port … also claimed by: …).

A project can also expose extra ports (on the Ports card of the Settings tab) when it runs more than one service — each extra port gets its own domains (attached on the Domains tab) and default URL. See Domains & TLS.

Categories & networking

Each project can have one or more categories. A category is a private Docker network: the project joins the network of every category it lists, and any two projects that share at least one category can reach each other by hostname (handy when an app needs to talk to a database you run as a separate project). Projects with no category in common are network-isolated and cannot see each other.

Service names must be unique within a category

Projects in the same category share one network, and Docker registers every service name on it. If a multi-service project (say, web + db) shares a category with another project that also has a service called db, the name db can point to the other project’s container — so your app could talk to the wrong database.

The agent guards against this:

Two single-service projects with the same service name (two apps, for example) are fine — neither looks up the bare name.

The full hostnames must be unique too. Because slugs and service names can contain -, two projects can end up with the same one: project db with a service main, and a single-service project db-main, are both ci-agent--db-main. Other projects connecting to that name could reach either container. A deploy that newly brings in such a clash fails with shared-network hostname collision: hostname “ci-agent–db-main” is already claimed on … by project …. As with service names, a clash that already existed only logs a warning.

Fix: rename the service in one of the compose files, or move one project to a different category.

What this means. A Docker network is a private network that only the containers on it can use. Giving two projects a category in common is how you let them connect — for example, a web app in category shop can reach a database also in category shop, with nothing exposed to the outside.

Example. Run Postgres as one project and your web app as another, both in category shop. The web app connects to the database at its hostname over the shared network — you never publish the database port to the host. Put a shared cache in categories shop, blog and both apps can reach it while staying isolated from each other.

Tests (optional)

Add a service named exactly ci-test with the ci profile:

  ci-test:
    build: .            # or image: ...
    profiles: ["ci"]
    command: ["./run-tests.sh"]

It runs after build, before deploy, as docker compose --profile ci run --rm --no-deps ci-test. A non-zero exit aborts the run — nothing gets deployed. The profile keeps it out of the deployed stack.

--no-deps means no other service is started for the test. If your tests need a database, start one inside the test command, or use a database that is already running (for example another project in the same category).

Environment

Data

Use named volumes for anything that must survive a redeploy (databases, uploads, and so on). The checkout/workspace is wiped after every run, so bind mounts into the source tree will not survive.

Note: a named volume is Docker storage with a name (e.g. db-data:/var/lib/mysql) that lives outside the container, so it stays put when the container is rebuilt. A bind mount into the cloned source (e.g. ./data:/data) does not survive, because the clone is deleted after each run.

You can also attach storage from the UI: the Volumes card on the project’s Settings tab adds a named volume or a host-path bind mount. It works in every mode. For Image and Dockerfile projects it is the only way, because you don’t write their compose file. For Compose and Inline compose projects, pick the Service the volume belongs to, and the agent adds it to that service for you. See the Admin UI guide. An admin API key can do the same with POST and DELETE /api/v1/projects/{slug}/volumes… (see API & AI agents).

Resource limits & GPU

Each project’s Settings tab has a Resource limits card with one row per discovered service:

Both apply on the next deploy. For Image / Dockerfile projects a Redeploy or Recreate also applies them (the agent regenerates the compose override from the current settings).

An operator API key can set them too: PATCH /api/v1/projects/{slug}/limits/{service} with cpus, memory_mb and gpu (see API & AI agents).

GPU prerequisite: a detected GPU only proves the driver is installed. Docker also needs the NVIDIA Container Toolkit registered as a runtime. ci-agent pre-checks for it: if it’s missing, the Resource limits card warns “GPU toolkit not configured” and a GPU deploy fails early with the setup guidance — rather than the opaque could not select device driver "nvidia" error mid-deploy. One time on the host:

sudo apt-get install -y nvidia-container-toolkit
sudo nvidia-ctk runtime configure --runtime=docker
sudo systemctl restart docker

Verify with docker run --rm --gpus all nvidia/cuda:12.4.0-base-ubuntu22.04 nvidia-smi. The Resource limits card surfaces these same commands when you tick a GPU box. On an air-gapped box, side-load the nvidia-container-toolkit package first.

Git access