Configure a service from its repository
Add a nebula.toml to a service's build context so each build reads its processes, variables and build settings from Git, and see the console follow it.
A nebula.toml in a Git service's build context configures the service from its repository: build settings, processes, mounts, a release command and plain variables. The console shows what the file sets as read-only, and each release applies it. The service file reference lists every key.
Before you begin
- A service built from a
gitorpublic-gitsource. See Deploy from Git. - The file belongs to one service. To declare a whole project's services and databases in one file, see Describe a project in Git.
Add the file
- Commit a
nebula.tomlin the service's build context. That is the repository root unless you set a Build context for the service. - Put in it only what you want the repository to own. This file sets a web process, a worker and one variable:
[processes.web]
cmd = "bin/rails server -b 0.0.0.0 -p 3000"
port = 3000
[processes.worker]
cmd = "bin/jobs"
kind = "worker"
[env]
RAILS_LOG_LEVEL = "info"- Check it before you push. The command needs no control plane:
nebula config validate./nebula.toml: ok (2 processes (web: http :3000, worker: worker), 1 variable)A problem prints as FILE:LINE: followed by the problem's PATH: MESSAGE, and the exit status is 1. With no argument, FILE is ./nebula.toml. Fix every problem listed before you push.
See the file detected
Pick a Git connection and a repository in Add to canvas or in the Custom service form. NebulaCtrl reads the nebula.toml at the repository's default branch and shows a card. A file that parses reads nebula.toml found with a summary such as 2 processes (web: http :3000, worker: worker), 1 variable. Select Show details to see the processes, the release command and the variable keys, never their values.
Creating the service from there creates the processes from the file, so they appear on the canvas at once. A file with problems shows a warning, nebula.toml has problems, with each problem and its line, and the first build fails until you fix them.
Build and deploy
Push the commit, or deploy by hand. See Deploy from Git. The build reads nebula.toml at the exact commit it builds, before it compiles the image. The build log's config step names what it found:
nebula.toml: 2 processes (web: http :3000, worker: worker), 1 variable[build] settings apply to this very build. A build whose file fails to parse fails before any image is built, and the log lists each problem. A build whose provider cannot deliver the file also fails and says to retry it.
A successful build creates a release the way a manual deploy does. That release writes [env] as service variables, attaches the [[mounts]], applies the processes, and runs a [deploy] release command before any process starts. Editing the file in Git changes nothing in the console until a build of that commit is deployed.
Verify
Open the service's Settings tab. Active release names the commit of your file. In the Variables tab, RAILS_LOG_LEVEL carries a nebula.toml badge.
See what the file owns
Try to edit something the file sets, such as RAILS_LOG_LEVEL or the port of process web. The variable shows a nebula.toml badge, its value cannot be edited, and its reveal and remove buttons are hidden. The process field is read-only with the same badge, and names the commit it came from. This is expected: the file owns what it names, for as long as it names it. A replicas or size change on a process whose file sets those fields is refused with a 409 that names the file and commit.
The file also owns the Deploy after list when it sets depends_on. The release command locks only when the file sets one, and the command saved in the console runs again if the file drops it.
Edit in the console again
Delete the key or table from nebula.toml and push. Once the next build is deployed, the field is an ordinary console setting again. The variable keeps the value the file last set, and the process field keeps the release's last resolved value. Nothing is deleted. The file stopped naming them.
Removing the whole file works the same way. The next build reports No nebula.toml, and every field or variable it managed becomes editable once a release is made from that build.
Set a release command or mount files without a file
A release command does not need a nebula.toml, and the file has no key for files from variables, because a secret's value must not come from Git. Set both in the console. See Release commands and files.
A file at the root of a project
A nebula.toml with a top-level [services] or [databases] table is a project file, not a service's file. A service that the project file declares takes its own [services.SLUG] block from it. A service with build context . that the file does not declare builds without a file, and the build log says so.
Next steps
nebula.tomlservice file lists every table and key.- Release commands and files covers the console settings.
- Build without a Dockerfile covers
builder = "railpack".
Install and share templates
Install a built-in, community or organization template into a project, save a project as a template, and share or contribute one.
Describe a project in Git
Declare a project's services, databases and connections in a root nebula.toml, point the project at the repository, and review the plan each push stages.