|
| 1 | +--- |
| 2 | +title: Nixpacks Builder |
| 3 | +description: Overview of nixpacks builder |
| 4 | +--- |
| 5 | +import {Aside} from '@astrojs/starlight/components'; |
| 6 | + |
| 7 | +> Introduced in [**v1.9.0**](/changelog/v19) |
| 8 | +
|
| 9 | +<Aside type="caution" title='Docker build resource usage'> |
| 10 | +The Docker build process can consume up to 100% of your server's resources, potentially slowing it to a crawl. |
| 11 | +Make sure your server is powerful enough to handle it. |
| 12 | +</Aside> |
| 13 | + |
| 14 | +<Aside type="tip" title='Network access'> |
| 15 | + When building your application, the build process will happen inside of the same network as your service, |
| 16 | + allowing you to access services inside of the same network. |
| 17 | +</Aside> |
| 18 | + |
| 19 | +[Nixpacks](https://nixpacks.com) is an open source tool developped by [railway](https://railway.app) that automatically detects your stack, language or framework |
| 20 | +and produce a Dockerfile for building your application. |
| 21 | + |
| 22 | +With this, when you want to deploy a new service, no need to specify a `Dockerfile` when deploying a service from a git repository, |
| 23 | +whether it is a next.js web application, a Svelte SPA or a Django backend API, it will automatically detect it for you. |
| 24 | + |
| 25 | + |
| 26 | +## How to create a service with nixpacks |
| 27 | + |
| 28 | +You can specify the nixpacks builder when creating your service or modify the builder at any moment in the service's settings. |
| 29 | + |
| 30 | + |
| 31 | + |
| 32 | + |
| 33 | +- You need to specify a **build directory**, where nixpacks will detect and build your application, relative to the root of your repository |
| 34 | +- You can specify custom **install**, **build** and **start** commands to configure nixpacks and override the auto-generated |
| 35 | + commands by nixpacks |
| 36 | +  |
| 37 | + |
| 38 | + |
| 39 | +## Static websites |
| 40 | + |
| 41 | +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](https://hub.docker.com/_/caddy) image, |
| 42 | +with your build assets copied exposed as a file server. |
| 43 | +For that you need to check the static website checkbox and specify a publish directory relative to the build directory. |
| 44 | + |
| 45 | +- You can also specify the path for a custom not found page, relative to the **published directory**, used for handling all 404 errors. |
| 46 | +- 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, |
| 47 | + the Not found page is ignored as all requests will be sent to the **index.html** page instead. |
| 48 | + |
| 49 | +### Overriding the default Caddyfile |
| 50 | + |
| 51 | +When updating your options in the UI, ZaneOps will show you a preview of the generated [Caddyfile](https://caddyserver.com/docs/caddyfile) that will be used to expose the static |
| 52 | +assets generated by your app. |
| 53 | + |
| 54 | + |
| 55 | +You can override the generated file by providing a Caddyfile at the root of your **build directory**. |
| 56 | +When specifying this, ZaneOps use it over the default generated one. |
| 57 | +With this you can add things like caching or simple HTTP basic authentication to your static websites. |
| 58 | + |
| 59 | +When specifying a custom Caddyfile, you can use : |
| 60 | +- the environment variable **`$PUBLIC_ROOT`** as the root for static files |
| 61 | +- the environment variable **`$PORT`** as the port for exposing your app |
| 62 | + |
| 63 | +Here is A fully working example of a custom Caddyfile : |
| 64 | +```ini |
| 65 | +# ./Caddyfile |
| 66 | +# expose your app to $PORT and use 80 if undefined |
| 67 | +:{$PORT:80} { |
| 68 | + # Set the root directory for static files |
| 69 | + root * {$PUBLIC_ROOT} |
| 70 | + # Serve static files |
| 71 | + file_server |
| 72 | + # Add `cache-control` header to static assets, images and videos |
| 73 | + @assets { |
| 74 | + path_regexp assets \.(css|js|png|jpg|jpeg|gif|svg|woff|woff2|eot|ttf|otf|mp4)$ |
| 75 | + } |
| 76 | + header @assets Cache-Control "public, max-age=31536000, immutable" |
| 77 | + # For all 404 errors, show a custom page |
| 78 | + handle_errors { |
| 79 | + @404 { |
| 80 | + expression {http.error.status_code} == 404 |
| 81 | + } |
| 82 | + rewrite @404 ./404/index.html |
| 83 | + file_server |
| 84 | + } |
| 85 | +} |
| 86 | +``` |
| 87 | + |
| 88 | + |
| 89 | +## Configuring nixpacks |
| 90 | + |
| 91 | +To configure nixpacks, you can : |
| 92 | + |
| 93 | +1. Alongside the custom **install/build/start** commands, you can customize nixpacks by passing all environment |
| 94 | + variables supported by nixpacks, they all starts with `NIXPACKS_`. |
| 95 | + |
| 96 | + |
| 97 | + You can find the common Nixpacks environment variables here : https://nixpacks.com/docs/configuration/environment |
| 98 | + |
| 99 | + For specific environment variables related to the provider detected by Nixpacks, you will need to refer to the docs for that provider. |
| 100 | + For ex, you can override the node version with `NIXPACKS_NODE_VERSION` for the `Node` provider : https://nixpacks.com/docs/providers/node |
| 101 | + |
| 102 | + Here is an example of environment variables you can add : |
| 103 | + ```shell |
| 104 | + NIXPACKS_APT_PACKAGES="wget,git" # install wget & git with apt-get |
| 105 | + NIXPACKS_NODE_VERSION="22.x" # install node `22` |
| 106 | + ``` |
| 107 | +2. You can add a custom [nixpacks.toml](https://nixpacks.com/docs/configuration/file) configuration file, at the root of your **build directory** : |
| 108 | + |
| 109 | + With this you can add more steps to the build process, customize the different commands, and even change the auto-detected provider by nixpacks. |
| 110 | + |
| 111 | + Here's an example of a nixpacks configuration that : |
| 112 | + - adds a new step |
| 113 | + - customize the build command |
| 114 | + - and install custom apt packages |
| 115 | + ```toml |
| 116 | + # ./nixpacks.toml |
| 117 | + [phases.setup] |
| 118 | + aptPkgs = ["...", "wget", "git"] # Install git & wget packages with apt-get |
| 119 | + |
| 120 | + [phases.lint] # add new `lint` step |
| 121 | + cmds = ["yarn run lint"] |
| 122 | + dependsOn = ["install"] |
| 123 | + |
| 124 | + [phases.build] |
| 125 | + dependsOn = ["...", "lint"] # build should come after `lint` |
| 126 | + cmds = ["pnpm run db:generate && pnpm run build"] |
| 127 | + ``` |
| 128 | + |
| 129 | + <Aside type="note" title='How to customize nixpacks.toml'> |
| 130 | + See here for more info about how to customize the config file : https://nixpacks.com/docs/guides/configuring-builds |
| 131 | + </Aside> |
| 132 | + |
| 133 | +## Default Environment variables |
| 134 | + |
| 135 | +when building with nixpacks, we will pass a default environment variable `FORCE_COLOR=true` for coloring build outputs. |
0 commit comments