Skip to main content

Railpack

Railpack is a tool for building container images from source code with minimal configuration. It is the successor to Nixpacks and incorporates several lessons learned from running Nixpacks in production at Railway over the years.

In Defang deployments, one of the most common issues faced by users is a missing or invalid Dockerfile that can’t produce OCI-compliant images. This is especially common when Dockerfile are generated by LLMs or created by users with limited Docker experience. Since integrating Railpack into Defang, if no Dockerfile is provided, we now automatically build a working image for you using Railpack.

How to trigger a Defang Railpack deployment​

When you run a Defang Railpack deployment, you need 2 components:

  1. A working application
  2. A valid Compose file

Your Compose file should not mention a Dockerfile.

For example,

services:
  app:
    restart: unless-stopped
    build:
      context: .
    deploy:
      resources:
        reservations:
          cpus: "1.0"
          memory: 512M
    ports:
      - mode: ingress
        target: 3000
        published: 3000

Troubleshooting and tips​

If the deployment fails, here are some things you can try.

Railpack Detection​

To allow Railpack to generate a build plan for your project, please restructure or rename your existing project files to be Railpack-compatible, as described for each framework below.

Node​

Your project will be detected as a Node.js application if a package.json file exists in the root directory.

Here is an example of:

Python​

Your project will be detected as a Python application if any of these conditions are met:

  • A main.py file exists in the root directory (If your main.py is named anything else)
  • A requirements.txt file exists
  • A pyproject.toml file exists
  • A Pipfile exists

Here is an example of:

Go​

Your project will be detected as a Go application if any of these conditions are met:

  • A go.mod file exists in the root directory
  • A go.work file exists in the root directory (Go workspaces)
  • A main.go file exists in the root directory

Here is an example of:

PHP​

Your project will be detected as a PHP application if any of these conditions are met:

  • An index.php file exists in the root directory
  • A composer.json file exists in the root directory

Java​

Your project will be detected as a Java application if any of these conditions are met:

  • A gradlew (Gradle wrapper) file exists in the root directory (to create this, if you don’t have one, run gradle wrapper)
  • A pom.{xml,atom,clj,groovy,rb,scala,yaml,yml} file exists in the root directory

Ruby​

Your project will be detected as a Ruby application if any of these conditions are met:

  • A Gemfile file is present

Rust​

Your project will be detected as a Rust application if any of these conditions are met:

  • A Cargo.toml file is present

Elixir​

Your project will be detected as a Elixir application if any of these conditions are met:

  • A mix.exs file exists in the root directory

Static Sites​

Railpack can automatically build and setup a server for static sites that require no build steps. The Caddy server is used as the underlying web server.

Your project will be automatically detected as a static site if any of these conditions are met:

  • A Staticfile configuration file exists in the root directory
  • An index.html file exists in the root directory
  • A public directory exists
  • The RAILPACK_STATIC_FILE_ROOT environment variable is set

Static sites are served using the Caddy web server and you need to have the environment variable PORT exposed like this in the Compose file to map to the correct port:

services:
  app:
    restart: "unless-stopped"
    build:
      context: ./app
    # This is the port you need to add
    environment:
      PORT: 5173 # <--- PORT
    ports:
      - target: 5173
        published: 5173
        mode: ingress
    deploy:
      resources:
        reservations:
          memory: 512M