Nixpacks supports specifying build configuration in a
nixpacks.json file. The config will automatically be used if one of these files is found in the app root. Otherwise, the file can be specified with the
--config <file> flag or with the
NIXPACKS_CONFIG_FILE environment variable.
The contents of this file can contain a full build plan, which means that every aspect of the build can be customized. An example config looks something like:
# nixpacks.toml [phases.setup] nixPkgs = ['...', 'cowsay'] [phases.build] cmds = ['yarn run server:build'] [start] cmd = 'yarn run server:start'
The file-based build plan is merged with the build plan generated by the provider, as well as the configuration from the environment variables and CLI flags. By default values are overridden when merged if they are not null. The configuration priority is
- Provider (lowest)
The default behaviour when merging build plans is for a non-null value of higher priority to override a lower priority value. However, you can use the
"..." special syntax to extend the values in an array. For example:
# Build plan from the provider [phases.setup] nixPkgs = ['nodejs', 'yarn'] # nixpacks.toml [phases.setup] nixPkgs = ['...', 'cowsay'] # Merged plan [phases.setup] nixPkgs = ['nodejs', 'yarn', 'cowsay']
"..." represents a hole that will be populated by the values from plan that is merged into.
Specify the providers that you want to run on the build.
providers = ['...', 'python']
The image to use as the base when building the application.
buildImage = 'ghcr.io/railwayapp/nixpacks:latest'
Key-value pairs of variables to include in the final image.
[variables] NODE_ENV = 'production' HELLO = 'world'
Files that are copied into the
/assets directory of the image.
[staticAssets] myFile = ''' asdfasdfasdf '''
The phases specify exactly how the application is built and packaged into an image. Each phase can depend on a list of other phases and the ordering is resolved when the
Dockerfile is automatically generated and run. The phases are typically defined as
setup: Install the Nix/Apt packages (e.g. NodeJS, Yarn)
install: Install the language/framework dependencies (e.g. Yarn install)
build: Build the application (e.g. Yarn build)
However, there is no restriction on the names of phases or what they are named.
[phases.setup] # ... [phases.install] # ... [phases.build] # ...
Array of commands to run.
[phase.name] cmds = ['cmd1', 'cmd2']
Nix packages to install. Available packages can be found at search.nixos.org.
[phase.name] nixPkgs = ['cowsay']
Nix packages to be made available through the
LD_LIBRARY_PATH environment variables. The paths to each packages library files are appended.
[phase.name] nixLibs = ['zlib']
Nix overlays to use as alternate package sources.
[phase.name] nixOverlays = ['https://github.com/oxalica/rust-overlay/archive/master.tar.gz']
Specific version of the Nixpkgs archive to use. By default all builds are built using the version defined here. But this value can be overridden to install Nix packages from an older archive.
[phase.name] nixpkgsArchive = '21de2b973f9fee595a7a1ac4693efff791245c34'
List of packages to install with
[phase.name] aptPkgs = ['wget']
List of phases that this phase must run after.
[phase.name] dependsOn = ['install']
Directories to cache for this phase. Cached directories do not appear in the final build. See /caching for more information.
[phase.name] cacheDirectories = ['node_modules/.cache']
Files to only make available when running this phase. If no array is specified, then all files are copied into the image before running the commands. This can be useful when optimizing the Docker layer cache.
[phase.name] onlyIncludeFiles = ['package.json']
Note: Files included from previous phases will also be available.
Paths to append to the
PATH environment variable.
[phase.name] paths = ['/app/node_modules/.bin']
This configures how a container created from the image will start.
The command to run when starting the container.
[start] cmd = "yarn run start"
The runtime image to use. If not specified, the same build image will be used.
[start] runImage = 'debian:bullseye-slim'
Must be used in combination with
runImage. The only files that should be copied over to the run image. If no value is specified, the entire app directory is copied over.
[start] onlyIncludeFiles = ['./bin/rust-custom-version']