Builds
How Teral turns a repository into an image.
For apps with a GitHub source, every deployment starts with a build. The build machine fetches the commit straight from GitHub and builds an image. The log streams on the deployment page while it runs.
Without a Dockerfile
By default Teral builds without a Dockerfile, using Railpack. It looks at your files, such as package.json, go.mod or pyproject.toml, and works out the language, the versions, how to install dependencies, how to build and how to start.
To steer it:
- Versions: pin them where your ecosystem expects them, such as
enginesinpackage.json,.nvmrc,.python-versionorgo.mod. - Build command: set Settings → Source & build → Build command to replace the detected one, for example
pnpm build --filter api. - Start command: set Settings → Runtime → Command to replace the detected one.
If detection gets it wrong, or you need system packages, use a Dockerfile.
Settings that affect the build
| Setting | What it does |
|---|---|
| Root directory | The folder Teral builds from. Use it when the app isn't at the repository root, such as services/api. |
| Dockerfile | Automatic builds without one. Otherwise, the Dockerfile to build with. |
| Build command | Replaces the detected build command. Only used without a Dockerfile. |
| Watch paths | Skips pushes that change none of the matching files. See GitHub. |
The root directory is a relative path such as ., api or services/api: no leading / or ./, no trailing /, and no ...
Variables during the build
The environment's variables are available to the build as secrets. They aren't written into the image or its history. For Dockerfile builds you mount them yourself, see Dockerfile builds.
Limits
- One build at a time per workspace. Other deployments wait as Pending until the build before them finishes.
- 30 minutes per build. A build that runs longer fails.
- Newer pushes win. If you push to a branch again while an older deployment is still waiting for its build, the waiting one is marked Superseded. Builds that already started run to the end.
What your app needs
Whichever way it's built, the image has to:
- Listen on the port from the
PORTvariable. It matches the Port setting,8080by default. - Exit cleanly on
SIGTERM. Teral sends it when it replaces or scales down an instance. - Keep local files small. Everything an instance writes to its own filesystem,
/tmpincluded, shares a 128 MiB limit. For more, add storage, which is mounted at/data.