hakobu.toml
What a project's server runs, at the root of its repository. It's strict: an unknown key, a typo or a reference to nothing is an error, so a mistake stops the deploy instead of quietly turning something off. hakobu validate checks it, and CI runs it before each build.
project = "crm"
server = "nova-1"
[apps.web]
domain = "crm.example.com"
release = "bin/rails db:migrate"
worker = "bin/jobs"
uses = ["main", "cache"]
volumes = { uploads = "/rails/storage" }
env = { RAILS_LOG_LEVEL = "info" }
[apps.admin]
path = "admin"
domain = "admin.crm.example.com"
uses = ["main"]
[databases.main]
[caches.cache]
memory = "128mb"
Names (the project's, apps', databases', caches', volumes') are lowercase letters, digits and -, starting with a letter, up to 31 characters.
The project
| Key | |
|---|---|
project |
the project's name, unique on its server |
server |
the server it deploys to; any other server refuses the release |
One repository is one project.
Apps: [apps.NAME]
An app is one image serving HTTP, and optionally a worker from the same image.
| Key | |
|---|---|
path |
its directory in the repository, default the root; the app is built from the Dockerfile there |
image |
a ready image to run instead, evoapicloud/evolution-api:v2.3.7 say: nothing is built. It names a version; the build pins the digest that version names then, which the server runs until the file names another |
domain |
where it's served on the web; without one, only the project's other apps reach it. One project's on the server: another's deploy with it is refused |
health |
a path that answers 2xx once the app takes requests; default /up. A deploy goes live only once it does |
port |
the port it listens on; default the image's EXPOSE, else 8080. It's in $PORT too |
release |
a command run once per deploy in the new image before it takes traffic, for migrations: if it fails, the running version stays. See Deploys |
worker |
the command of a background process from the same image |
memory |
its limit, 512mb or 1gb; at least 64mb |
cpus |
its CPU limit, 0.5 or 2 |
volumes |
name → mount path. Survives deploys and is backed up |
env |
variables, plain values only: secrets go in hakobu.secrets.toml. A value may name one hakobu gives the app as ${NAME}: see below |
uses |
the databases and caches it uses: a list, or a map of name → prefix |
The app must listen on all interfaces (not only 127.0.0.1). release and worker run with /bin/sh -c in its image, which therefore needs a shell.
Each app also gets HAKOBU_REVISION, the commit it was deployed from: what to give an error tracker as the release, for one. An app whose image a commit didn't change keeps running, with the commit it was deployed from.
uses
A database gives the app DATABASE_URL, POSTGRES_HOST, POSTGRES_PORT, POSTGRES_DB, POSTGRES_USER and POSTGRES_PASSWORD; a cache REDIS_URL, VALKEY_URL, REDIS_HOST, REDIS_PORT and REDIS_PASSWORD. Two of a kind would set the same variables, so give one a prefix:
uses = { main = "", jobs = "JOBS" } # JOBS_REDIS_URL, JOBS_REDIS_HOST, …
One app to another
The project's apps reach each other by name: http://web:8000 from another app of the project, or its worker, is web's live version, whichever that is during a deploy. The port is the one the app listens on. Nothing outside the project reaches it so.
Variables from variables
A ready image often wants what hakobu gives under a name of its own. ${NAME} in a value is a variable hakobu gives the app: one from uses, PORT or HAKOBU_REVISION.
[apps.wa]
image = "evoapicloud/evolution-api:v2.3.7"
uses = ["gateway"]
env = { DATABASE_CONNECTION_URI = "${DATABASE_URL}?schema=evolution" }
Volumes
An app with volumes is stopped before its new version starts, so two versions never write the same files: a few seconds down on each deploy. The worker shares them.
Databases: [databases.NAME]
A database and its own user on the server's PostgreSQL, which all its projects share; its version is the server's. It has no keys. See Databases.
Caches: [caches.NAME]
A Valkey server of the project's own, with its own password.
| Key | |
|---|---|
memory |
its memory, default 256mb, at least 16mb |
What a change does
- Adding an app, database, cache or volume makes it on the next deploy.
- Removing one doesn't delete it: a database, cache or volume is kept, orphaned, and only
hakobu destroy(a person's, as root on the server, after a last backup) deletes it. - Renaming is removing and adding: the new one starts empty and the old one is orphaned. For a database, the deploy stops instead and says so: deploy the new one, move the data, then take the old one out.