Every deploy starts with a build: Hangar clones your repository at the commit being deployed and produces a container image from it. The Settings → Source section of a service decides how.
Build time is not billed. Only the resources your running services use count toward your usage.
Builders#
| Builder | Use it when | What it does |
|---|---|---|
| Automatic (default) | Your repository is a standard app in a common language | Detects the language and framework, installs dependencies, builds and picks a start command |
| Dockerfile | You already have a Dockerfile, or need full control of the image | Builds the Dockerfile in your repository |
| Static site | The repository is plain HTML, CSS and JavaScript | Serves the files as they are |
Three more builders are available for apps that already depend on them: Nixpacks, Heroku buildpacks and Paketo buildpacks.
Automatic#
The automatic builder is Railpack, an open source builder. It reads your repository, recognises the stack (Node.js, Python, Go, PHP, Ruby, Java, Rust, Elixir, Deno, Bun and more) and builds an image without any configuration file.
The Railpack version is pinned per service, so a build today and a build in six months behave the same. You can change the pinned version in the builder's advanced settings.
Dockerfile#
Choose Dockerfile and set the path to the file, relative to the service's root directory. Two optional settings cover less common layouts:
- Build context: the directory sent to the build, when it is not the root.
- Target stage: the stage to stop at in a multi-stage Dockerfile. By default the last stage is built.
Static site#
The files in the repository are served directly. Turn on Single-page app to send unknown routes to index.html, which client-side routers need.
Monorepos#
A service has a root directory. Point two services at the same repository with different root directories to deploy, for example, an API and a web app from one monorepo. Watch paths limit which changes trigger a deploy of each service.
Start command#
The builder picks how to start your app. To override it, set a start command in the service's Settings → Runtime. This is the place for commands such as gunicorn app.wsgi --bind 0.0.0.0:8000.
Write it as you would in a terminal. A command that uses $VARIABLES, &&, pipes or quotes runs through /bin/sh, so uvicorn main:app --host 0.0.0.0 --port $PORT and npm run warm-cache && node server.js work as written. A plain command runs as it is, which also works in images without a shell.
To pass values exactly, without a shell, add arguments: each one is passed as one value, spaces included, and the command is then split on spaces.
Pre-deploy command#
A pre-deploy command runs once before each deployment goes live, in the image that was just built. It is the place for database migrations, such as python manage.py migrate or npx prisma migrate deploy. Set it in Settings → Runtime.
- It runs with
sh, so&&, pipes and$VARIABLESwork. - It sees the service's variables and reaches other services over the private network, but the service's volume is not mounted and it gets no domain.
- If it fails, or does not finish within 15 minutes, the deployment stops and the running version stays. Its output is in the deployment's log.
- It runs on every deploy and rebuild, but not on a rollback, a restart or a preview deployment, so migrations should be safe to run more than once.
Deploys on push#
Once a repository is connected through GitHub, GitLab, Bitbucket or Gitea, every push to the selected branch deploys the service. Each deploy keeps its build log, and you can cancel a build that is still running.
Docker images#
A service can also run a prebuilt image from a registry instead of building from source. In that case there is no build step: Hangar pulls the image and runs it. See Deploy a Docker image.