Skip to content

Railpack and Dockerfiles

Ployz builds your app with Railpack, so you don't need a Dockerfile. Railpack reads your repository, works out the language and framework, and builds an image that installs, builds and starts your app. If you'd rather use your own Dockerfile, you can.

Every service you add from GitHub starts on Railpack, even when the repository has a Dockerfile. Railpack detects Node, Python, Ruby, PHP, Go, Rust, Java, Elixir and more; its docs list the files it looks for. Build settings are under the service's Settings → Build, and changes to them are staged until you deploy, except Preferred Builder, which applies at once.

Settings → Build: Build method, Build command and Preferred Builder

When Railpack picks the wrong build step:

  1. Open the service and go to Settings → Build.
  2. Click Build command and enter the command, like pnpm run build.
  3. Deploy.

Railpack still works out the rest, like installing dependencies. To change how your app starts, set Start command under Settings → Deploy, like node server.js. It runs in a shell, so $PORT and && work.

For anything else, like extra system packages, add a railpack.json to the root directory or set Railpack's own RAILPACK_* variables on the service.

Use your Dockerfile when you already have one that works, or when your app needs more than Railpack can work out.

The build starts in the service's root directory: COPY . . copies that folder, and Dockerfile path is relative to it. To build one app of a monorepo, set its root directory first; see Deploy a monorepo.

  1. Open the service and go to Settings → Build.
  2. Set Build method to Dockerfile.
  3. If your Dockerfile isn't Dockerfile in the root directory, enter its path in Dockerfile path.
  4. Deploy.

Dockerfile path suggests paths from the top of the repository, so with a root directory set, shorten them to start from it.

A Start command on a Dockerfile build replaces the Dockerfile's ENTRYPOINT and CMD and runs without a shell, as on an image service. See Override the start command.

Every variable of the service reaches its build, secrets included, with references to other services filled in. Changing one rebuilds the service.

  • Railpack gives them to every build step and keeps their values out of the image's metadata.

  • A Dockerfile gets them as build arguments. Declare each one a step needs with ARG:

    ARG NEXT_PUBLIC_API_URL
    RUN npm run build

Builds on GitHub Actions get your variables too.

Railpack builds see a sealed value as they see any other variable, on your servers and on GitHub Actions. A sealed RAILPACK_* setting builds only on GitHub Actions: your servers refuse it. A Build command replaces a sealed RAILPACK_BUILD_CMD, so that build runs on your servers too. A Dockerfile reads a sealed value with ARG:

ARG NPM_TOKEN
RUN npm ci

A secret mount keeps the value out of the image's history:

RUN --mount=type=secret,id=NPM_TOKEN,env=NPM_TOKEN npm ci

On GitHub Actions, a build that reads a sealed value with ARG, or sets a RAILPACK_* variable to a sealed value, saves no build cache. A secret mount keeps it.

A Dockerfile with no secret mount gets only the sealed values it declares with ARG. Other sealed values, like a runtime-only database password, stay out of the build. A Dockerfile with any secret mount, or one built by a custom frontend (a # syntax= line or a BUILDKIT_SYNTAX variable), gets every sealed value. A sealed GIT_AUTH_TOKEN or GIT_AUTH_HEADER always reaches the build, for an ADD of a private Git repository.

Your servers open a sealed value for a build only from Ployz 0.3.5. A build that gets one needs a server on 0.3.5 or later, and it won't start until you upgrade one. The refusal names the sealed values the build reads, so you can instead stop reading them in the build.

Railpack gives the build every variable, so a Railpack build reads every sealed value, even one only your app uses at runtime. A Railpack service with any sealed value needs a server on 0.3.5 or later to build. To build one on older servers, switch it to a Dockerfile with no secret mount, no custom frontend, and no ARG for the value.

A changed sealed value doesn't rerun a cached secret mount step. To rerun it, add ARG PLOYZ_SEALED_HASH right above it.

Builds have no SSH keys or registry logins of their own. Give the build a token through a secret variable instead. For a private npm package, add a variable NPM_TOKEN and an .npmrc next to your package.json:

//registry.npmjs.org/:_authToken=${NPM_TOKEN}

Railpack builds see NPM_TOKEN as it is. A Dockerfile needs ARG NPM_TOKEN before the install step, so give it a short-lived token. Private Git dependencies work the same way, over HTTPS with a token in the URL.

A token can't get a Dockerfile FROM a private image: use a public base image.

Build steps reach the internet over IPv4, so package registries and Git hosts work. They can't reach the server running the build, the private network Ployz runs between your servers, or your services on it. Fetch what a build needs from the internet, and talk to your services after deploy.

A build step can still reach any port your services publish on a public address, like a web address on 80 and 443, and your other servers' public addresses. Don't leave anything on those addresses open without a login. It can't reach the build server's local network, like a cloud VPC or office LAN, any other private address, or the cloud's metadata service, even through a port published there. Its DNS keeps working, so port 53 stays open to any address, private ones too.

A Dockerfile ADD of a URL or Git repository, and every FROM image pull, reach the internet and nothing on the server running the build or your servers' private network, except the image servers Ployz uses to share build images between your servers. Like a build step, they can't reach a private address on the build server's local network, like a cloud VPC or office LAN, except for DNS. So a base image won't pull from a registry or mirror on your LAN, or from any registry whose name your network resolves to a private address, like a cloud registry or storage endpoint with private DNS in your VPC. Pull from an address that resolves publicly instead, for example by turning off private DNS for that endpoint. A LAN reached over public IPv6 addresses isn't fenced off. If Ployz can't put these limits in place, the build fails instead of running without them.

  • With Railpack, there's nothing to do: Ployz builds the service for both.
  • With a Dockerfile, the image only runs on the kind of CPU of the server that built it. A deploy that would start it on the other kind fails before it changes anything.

To deploy a Dockerfile service, switch it to Railpack, or run it on one kind of server:

  1. Turn off services on the servers of the other kind: on each one's page, under Services, turn off Run services here. This applies to every service on that server, and your next deploy moves this one off it.

  2. Build on the kind that's left: make a server of that kind the service's Preferred Builder, or build on GitHub Actions.

  • Keep files out of the build with a .dockerignore in the root directory. It works with Railpack and with Dockerfiles.
  • Keep secrets on your computer by listing them in .gitignore. A .dockerignore keeps a file out of your image, but ployz up still uploads it. In a Git checkout, ployz up leaves out every file Git ignores, so add .env to .gitignore. If you committed .env before, Git still keeps it, so also run git rm --cached .env. Outside a Git checkout it uploads every file, so move .env out of the directory first. See Deploy a directory.