Build Docker Images

Encore supports building Docker images directly from the CLI, which can then be self-hosted on your own infrastructure of choice.

This can be a good choice if the Encore platform isn't a good fit for your use case, or if you want to migrate away.

Building your own Docker image

To build your own Docker image, use encore build docker MY-IMAGE:TAG from the CLI.

This will compile your application using the host machine and then produce a Docker image containing the compiled application. The base image defaults to scratch for GO apps and node:slim for TS, but can be customized with --base.

This is exactly the same code path that Encore's CI system uses to build Docker images, ensuring compatibility.

By default, all your services are included and started by the Docker image. If you want to specify specific services and gateways to include, you can use the --services and --gateways flags.

encore build docker --services=service1,service2 --gateways=api-gateway MY-IMAGE:TAG

You can target a specific architecture with --arch (useful when your build machine differs from your deploy target):

encore build docker --arch=arm64 MY-IMAGE:TAG

To provide an infrastructure configuration file at build time, use --config. This is required if your app uses databases, caches, Pub/Sub, object storage, or secrets, otherwise the build fails with an incomplete configuration error:

encore build docker --config=infra-config.json MY-IMAGE:TAG

The image runs your services, but it doesn't run database migrations or trigger cron jobs:

  • Database migrations: Apply your migrations to each database before starting a new image, for example with golang-migrate, which uses the same migration file naming as Encore.
  • Cron jobs: Call each cron job's endpoint on its schedule from your own scheduler. encore build docker prints the endpoint path and schedule of each cron job. Private endpoints can't be called from outside your app, so the endpoint must be public and require authentication; ensure that your scheduler sends the required authentication data.

The image will default to run on port 8080, but you can customize it by setting the PORT environment variable when starting your image.

docker run -e PORT=8081 -p 8081:8081 MY-IMAGE:TAG

Congratulations, you've built your own Docker image! 🎉 Continue to learn how to configure infrastructure.