Understanding Nixpacks

Nixpacks are Flightcontrol’s preferred way to build and deploy your applications from source code. The Nixpacks project is open source, and was started by Railway.

Similar to build packs on other providers, Nixpacks provide a repeatable way to build and deploy your applications. Using the same Nixpacks version for your application across all environments ensures that your application is built and deployed in the same way.

For most application deployments, you won’t need to worry about Nixpacks. Flightcontrol will automatically select the correct Nixpack provider for your application, and use it to build and deploy your application.

What are Nixpacks?

When Nixpacks runs, the Nixpacks process starts by analyzing your source code. Nixpacks takes a specific list of Nix packages and Apt packages based on what type of application Nixpacks detects in your source code, and installs them into a Nix environment. The Nix environment is then used to build your application into a Docker image.

The base Docker image can either be Ubuntu or Debian, which you can configure using the instructions in the Choosing a Base Image section of this page.

This Docker image is then deployed on the AWS ECS Fargate service by the Flightcontrol application.

When you use Nixpacks, the Docker part of the process is behind the scenes, and should not affect your deployment process.

Setting a Base Path

Nixpacks needs to know where your application’s source code is located. By default, Nixpacks will look for your application’s source code in the root directory of your GitHub project.

If, for instance, the project you deploy is in a subdirectory, you will need to specify the base path for Flightcontrol to use. In the dashboard, the default base path will be ., and you can edit this path for each service. When using code for configuration, set the basePath attribute on a service, like the following example:

flightcontrol.json

"services": [
    {
        "id": "api",
        "name": "Backend API",
        "type": "web",
        "target": {"type": "fargate"},
        "buildType": "nixpacks",
        "basePath": "./packages/api",
        "healthCheckPath": "/graphql/health",
        "installCommand": "pnpm i",
        "buildCommand": "pnpm build",
        "startCommand": "pnpm start"
    }
]

Using a base path with Nixpacks is quite common in a Monorepo setup.

Specifying a Nixpacks Version

If you need a particular Nixpacks version for Flightcontrol, you can specify that number as an environment variable in your Flightcontrol environment named NIXPACKS_VERSION. An example:

NIXPACKS_VERSION=1.7.0

This could be useful if you find errors in your build logs, and want to try a different version of Nixpacks to see if that fixes the problem.

Find the list of available Nixpacks versions on the Nixpacks releases page.

Choosing a Base Image

The default base image for Nixpacks uses the Ubuntu Linux operating system. You may wish to use the Debian operating system instead, especially if you are having problems with OpenSSL. The version of Debian used by Nixpacks includes OpenSSL version 1.1, while the Nixpacks Ubuntu base image does not.

To use Debian, set the NIXPACKS_DEBIAN environment variable in Flightcontrol:

NIXPACKS_DEBIAN=1

If your builds work fine with the default Ubuntu base image, there isn’t any reason to switch to Debian.

Trying Nixpacks Locally

You can run Nixpacks on your own computer. This can be a very useful way to debug any problems locally, before deploying with Flightcontrol. It’s not essential that you do this step, so don’t feel like you need to install Nixpacks locally.

After installing Nixpacks (and Docker), run nixpacks build . in your application’s source directory. This command builds a Docker image from your application’s source code, using the appropriate Nixpacks provider.

If you just want to see what Nixpacks will do, run nixpacks plan . in the same directory to see the steps Nixpacks will take to build the image.

Adding Additional Packages

Default packages come with every Nixpacks provider, but it you may need to add additional packages to your Nixpacks. For example, if you need to install a database client, or a video transcoding package. These can be used during any phase of your build, or during your application’s runtime.

With Nixpacks, you can install Nix packages or Apt packages (or both). You’ll need to specify these packages in a nixpacks.toml or a nixpacks.json file in your application’s source directory. To find the configuration options from nixpacks, see the Nixpacks configuration file documentation.

Build Types Autoscaling