Nixpacks Builder

Introduced in v1.9.0

Nixpacks is an open source tool developped by railway that automatically detects your stack, language or framework and produce a Dockerfile for building your application.

With this, when you want to deploy a new service, no need to specify a Dockerfile when deploying a service from a git repository, whether it is a next.js web application, a Svelte SPA or a Django backend API, it will automatically detect it for you.

How to create a service with nixpacks

You can specify the nixpacks builder when creating your service or modify the builder at any moment in the service’s settings.

Create a service with Nixpacks builder

You need to specify a build directory, where nixpacks will detect and build your application, relative to the root of your repository
You can specify custom install, build and start commands to configure nixpacks and override the auto-generated commands by nixpacks

Static websites

The nixpacks builder support deploying static websites, when deploying a static website with ZaneOps, it will be built as a service using a caddy on alpine image, with your build assets copied exposed as a file server. For that you need to check the static website checkbox and specify a publish directory relative to the build directory.

You can also specify the path for a custom not found page, relative to the published directory, used for handling all 404 errors.
If your app is a Single Page Application (SPA), you can check the box and specify the location of index.html page to redirect requests to, the Not found page is ignored as all requests will be sent to the index.html page instead.

Overriding the default Caddyfile

When updating your options in the UI, ZaneOps will show you a preview of the generated Caddyfile that will be used to expose the static assets generated by your app. Nixpacks static settings

You can override the generated file by providing a Caddyfile at the root of your build directory. When specifying this, ZaneOps use it over the default generated one. With this you can add things like caching or simple HTTP basic authentication to your static websites.

When specifying a custom Caddyfile, you can use :

the environment variable $PUBLIC_ROOT as the root for static files
the environment variable $PORT as the port for exposing your app

Here is A fully working example of a custom Caddyfile :

# expose your app to $PORT and use 80 if undefined
:{$PORT:80} {
    # Set the root directory for static files
    root * {$PUBLIC_ROOT}
    # Serve static files
    file_server
    # Add `cache-control` header to static assets, images and videos
    @assets {
        path_regexp assets \.(css|js|png|jpg|jpeg|gif|svg|woff|woff2|eot|ttf|otf|mp4)$
    }
    header @assets Cache-Control "public, max-age=31536000, immutable"
    # For all 404 errors, show a custom page
    handle_errors {
        @404 {
            expression {http.error.status_code} == 404
        }
        rewrite @404 ./404/index.html
        file_server
    }
}

Configuring nixpacks

To configure nixpacks, you can :

Alongside the custom install/build/start commands, you can customize nixpacks by passing all environment variables supported by nixpacks, they all starts with NIXPACKS_.

You can find the common Nixpacks environment variables here : https://nixpacks.com/docs/configuration/environment

For specific environment variables related to the provider detected by Nixpacks, you will need to refer to the docs for that provider. For ex, you can override the node version with NIXPACKS_NODE_VERSION for the Node provider : https://nixpacks.com/docs/providers/node

Here is an example of environment variables you can add :
Terminal window
```
NIXPACKS_APT_PACKAGES="wget,git" # install wget & git with apt-get
NIXPACKS_NODE_VERSION="22.x" # install node `22`
```
You can add a custom nixpacks.toml configuration file, at the root of your build directory :

With this you can add more steps to the build process, customize the different commands, and even change the auto-detected provider by nixpacks.

Here’s an example of a nixpacks configuration that :
- adds a new step
- customize the build command
- and install custom apt packages
./nixpacks.toml
```
[phases.setup]
 aptPkgs = ["...", "wget", "git"]   # Install git & wget packages with apt-get

[phases.lint] # add new `lint` step
 cmds = ["yarn run lint"]
 dependsOn = ["install"]

[phases.build]
 dependsOn = ["...", "lint"] # build should come after `lint`
 cmds = ["pnpm run db:generate && pnpm run build"]
```
See here for more info about how to customize the config file : https://nixpacks.com/docs/guides/configuring-builds

Default Environment variables

when building with nixpacks, we will pass a default environment variable FORCE_COLOR=true for coloring build outputs.

Built with Astro & deployed on ZaneOps