Services catalog

Every service ox provisions from one [[services]] block in ox.toml. Each entry carries its tested_on matrix: the Ubuntu releases a real verification run covered on a disposable VPS, running the exact script linked from the entry. Deploys target Debian-based hosts, tailored to Ubuntu LTS; a host release outside an entry's tested_on still deploys, with a loud warning naming the verified releases.

19 entries · 19 verified on at least one Ubuntu release. Local listing: ox catalog list; one entry: ox catalog show postgres@17.

[[services]]
id = "postgres@17"          # pinned variant; the bare name picks the default

[services.args]
extensions = ["vector"]

[[services]]
id = "celery@5"
[services.args]
app = "myproj"
workers = 4
queues = ["default", "mail"]

tested_on: ubuntu-24.04 · verify.sh

Celery beat scheduler rendered from the app's runtime: one project unit running the periodic-task schedule, with its schedule file under the service data dir. Pair with celery@5 for the workers.

arg	type	description
app	string	the celery app module; empty runs bare `celery` from the release directory

tested_on: ubuntu-24.04 · verify.sh

Celery worker rendered from the app's runtime: one project unit consuming the declared queues at the declared concurrency. The broker is whatever the app's env carries (declare redis or rabbitmq as a service to get CELERY_BROKER_URL).

arg	type	description
app	string	the celery app module (e.g. "myproj.celery" or "myproj"); empty runs bare `celery` from the release directory
workers	int	worker concurrency (--concurrency)
queues	strings	queues to consume (--queues); the default is celery's own default queue name, which is where a vanilla celery app publishes

tested_on: ubuntu-24.04 · verify.sh

ClickHouse server from the official repository. Default user, no password, 127.0.0.1 only (single-operator host); the project's database is created by the recipe.

provides: CLICKHOUSE_URL, CLICKHOUSE_HOST, CLICKHOUSE_PORT

tested_on: ubuntu-24.04 · verify.sh

Flower, the Celery monitoring UI, as a project unit reading the same broker the workers use. The app needs `flower` in its dependencies.

provides: FLOWER_URL

requires: celery

arg	type	description
app	string	the celery app module; empty runs bare `celery` from the release directory

tested_on: ubuntu-24.04 · verify.sh

LiveKit media server (pinned release binary) as a project unit with generated API credentials (LIVEKIT_API_KEY / LIVEKIT_API_SECRET). Binds the allocated TCP port on 127.0.0.1; WebRTC media needs the host's UDP range reachable when clients connect from outside.

provides: LIVEKIT_URL, LIVEKIT_API_KEY, LIVEKIT_API_SECRET

tested_on: ubuntu-24.04 · verify.sh

Mailpit (pinned release binary) as a project unit: SMTP on the allocated port, the web UI on the next one. Point the app's SMTP at SMTP_URL and read mail in the browser at MAILPIT_URL.

provides: SMTP_URL, MAILPIT_URL

tested_on: ubuntu-24.04 · verify.sh

Meilisearch (pinned release binary) running as a project unit with a generated master key (MEILI_MASTER_KEY); production mode on the allocated port.

provides: MEILISEARCH_URL, MEILI_MASTER_KEY

tested_on: ubuntu-24.04 · verify.sh

Memcached (the Ubuntu package) on 127.0.0.1:11211; every project shares the one cache.

provides: MEMCACHED_URL

tested_on: ubuntu-24.04 · verify.sh

MongoDB 8.0 Community from the official repository (7.0 has no ubuntu-24.04 repository, so the first verified variant is 8.0). Binds 127.0.0.1:27017 with no auth (single-operator host; auth lands with a later entry version); the project's database is created on first use.

provides: MONGODB_URI, MONGODB_DB

tested_on: ubuntu-24.04 · verify.sh

MySQL 8 (the Ubuntu mysql-server package). Per-project user and database named after the project, converged from MYSQL_PASSWORD on every deploy.

provides: MYSQL_URL, MYSQL_HOST, MYSQL_PORT, MYSQL_USER, MYSQL_PASSWORD, MYSQL_DATABASE

tested_on: ubuntu-24.04 · verify.sh

NATS server (pinned release binary) running as a project unit: one instance per project, so subject namespaces stay private; no auth inside the sandbox (127.0.0.1 bind).

provides: NATS_URL

tested_on: ubuntu-24.04 · verify.sh

Neo4j 5 from the official Debian repository. The admin password is generated into NEO4J_PASSWORD and converged on every deploy (probe, reset, re-probe); NEO4J_URI points at the local Bolt endpoint.

provides: NEO4J_URI, NEO4J_PASSWORD

tested_on: ubuntu-24.04 · verify.sh

PostgreSQL 16 from PGDG. Per-project role/database/credentials are driven by the app's DATABASE_URL env (autowire fills a local one); extensions land on that database.

provides: DATABASE_URL

arg	type	description
extensions	strings	extensions to CREATE EXTENSION on the app's database (vector, postgis, pg_trgm, uuid-ossp, ...); the apt package for the installed major is inferred
databases	strings	database names to ensure beside the env-driven one; the env's database and its extensions stay the source of truth

tested_on: ubuntu-24.04 · verify.sh

PostgreSQL 17 from PGDG. Per-project role/database/credentials are driven by the app's DATABASE_URL env (autowire fills a local one); extensions land on that database.

provides: DATABASE_URL

arg	type	description
extensions	strings	extensions to CREATE EXTENSION on the app's database (vector, postgis, pg_trgm, uuid-ossp, ...); the apt package for the installed major is inferred
databases	strings	database names to ensure beside the env-driven one; the env's database and its extensions stay the source of truth

tested_on: ubuntu-24.04 · verify.sh

Prometheus (the Ubuntu package) on 127.0.0.1:9090, ready to scrape this host's exporters; add scrape config through /etc/prometheus.

provides: PROMETHEUS_URL

tested_on: ubuntu-24.04 · verify.sh

Qdrant vector database (pinned release binary) running as a project unit: one instance per project, data under the project's service dir, port allocated by ox.

provides: QDRANT_URL

tested_on: ubuntu-24.04 · verify.sh

RabbitMQ (the Ubuntu rabbitmq-server package). One shared broker; every project gets its own vhost and user, converged from AMQP_PASSWORD on every deploy.

provides: AMQP_URL, CELERY_BROKER_URL

tested_on: ubuntu-24.04 · verify.sh

Redis 7 (the Ubuntu redis-server package). One shared instance; every project gets its own database index so queues and result keys never collide.

provides: REDIS_URL, REDIS_CONNECTION_URL

tested_on: ubuntu-24.04 · verify.sh

SQLite: ensures the sqlite3 CLI for migrations, inspection, and backups. No daemon and no port; the database file lives wherever the app puts it (keep it under a writable path or the project's service data dir).

How testing works

Every entry ships with its verification (S-15): a disposable Ubuntu VPS runs the entry's rendered recipe per variant and configuration, and the run records two artifacts — verify.sh, the exact flattened command script that ran, and the host facts (release, arch, installed versions, probes). tested_on derives from the green runs; a variant without a green run on a release never claims it. Provisioning renders the same command sequence with the project's parameters, so what ships is what was tested. Runs repeat on every entry version bump and every new Ubuntu LTS.

So far 19 of 19 entries carry a green run. The rest deploy with a warning until their run lands.