Deploy an app
apps runs everything that isn't a static site: web services, APIs, workers, Telegram bots, cron jobs
and databases, as containers on the instance's nodes.
apps needs at least one node. If xvii apps nodes shows none, ask your admin, or add one yourself:
Nodes.
Create a project
Apps, databases and secrets belong to a project in a team. Projects start with two environments,
production and preview.
xvii projects create shop --team acme
xvii projects list
Create the app
xvii apps create api --project shop --port 3000 --health /healthz
--port is what the app listens on inside its container; --health is a path that answers 200 when
it is ready. A production app answers at https://api.apps.xvii.network; other environments get
https://api-<env>.apps.xvii.network, and the project's slug is added when the name is taken. Web apps
also get PORT in their environment.
Deploy your code
From the repository:
xvii apps deploy api --project shop --dir .
The folder (the files git doesn't ignore) is uploaded and built on the node: with your Dockerfile
if there is one, otherwise Railpack detects the language and builds an image. The CLI follows the build
output and waits until the release is live, then prints the app's address.
A release goes live only after its health check passes. If it fails, the app keeps serving its last live
release and the CLI exits with an error and the build or health log.
Already have an image?
xvii apps deploy api --project shop --image ghcr.io/acme/api:1.3
Add a database
In the apps panel, open the project's environment and add a PostgreSQL database (MariaDB, Valkey,
Redis and MongoDB are there too). apps writes its connection string into the environment's variables as
DATABASE_URL, so the app picks it up on its next deploy. The password is generated and sealed; you
never copy it into code. See Databases.
Secrets
xvii env set --project shop --env production STRIPE_KEY=sk_live_…
xvii env set --project shop --env production LOG_LEVEL=info --plain
Variables from env reach the app at its next deploy. Values are secret unless --plain.
Logs, rollbacks, previews
xvii apps logs api -f # follow the log
xvii apps rollback api # deploy the release before again
xvii apps deploy api --dir . --preview mr-12 --ttl 7d # a disposable preview
Templates
xvii apps templates
xvii apps install n8n --project ops
A template installs an application with its databases in one step (n8n, Gitea, Grafana, Nextcloud,
Directus, Umami and about fifty more).
Next