Dockerfiles

Use a Dockerfile to instruct Railway how to build a service.

How it works

When building a service, Railway will look for and use a Dockerfile at the root of the source directory.

Note: For the automatic Dockerfile detection to work, the Dockerfile must be named Dockerfile with a capital D, otherwise Railway will not use it by default.

Railway notifies you when it's using the Dockerfile in the build process with the following message in the logs:

Custom Dockerfile path

By default, we look for a file named Dockerfile in the root directory. If you want to use a custom filename or path, you can set a variable defining the path.

In your service variables, set a variable named RAILWAY_DOCKERFILE_PATH to specify the path to the file.

For example, if your Dockerfile was called Dockerfile.origin, you would specify it like this:

If your Dockerfile is in another directory, specify it like this:

Use config as Code

You can also set your custom Dockerfile path using config as code.

Using variables at build time

If you need to use the environment variables that Railway injects at build time, which include variables that you define and Railway-provided variables, you must specify them in the Dockerfile using the ARG command.

For example:

Be sure to declare your environment variables in the stage they are required in:

Cache mounts

Railway supports cache mounts in your Dockerfile in the following format:

Replace <service id> with the id of the service.

Target path

Unsure of what your target path should be? Refer to the Nixpacks source code. Within the providers directory, find the file that aligns with your respective language or runtime, and check for the variable that indicates the CACHE_DIR.

Example

As an example, within the python provider definition, you can see the PIP_CACHE_DIR is /root/.cache/pip.

So the mount command is specified like this:

Docker compose

You can import services straight from your Docker Compose file! Just drag and drop your Compose file onto your project canvas, and your services (and any mounted volumes) will be auto-imported as staged changes. It's like magic, but with YAML instead of wands. 🪄

A quick heads-up: we don't support every possible Compose config just yet (because Rome wasn't built in a day). But don't worry, we're on it!