Self-hosted Encore deployments

Deploy your Encore application to your own infrastructure, using Encore's open-source tooling.

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 for when Encore's cloud 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 eject 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 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.

Configuring your Docker image

The built Docker image relies on runtime configuration, in the form of environment variables, to provide information about the application's environment.

This includes configuring things like:

  • How to access infrastructure resources (what provider to use, what credentials to use, etc.)
  • How to call other services over the network ("service discovery"), most notably their base URLs.
  • Observability configuration (where to export metrics, etc.)
  • Metadata about the environment the application is running in, to power Encore's metadata APIs.
  • The values for any application-defined secrets.

This configuration is necessary for the application to behave correctly.

Exactly how to configure these depends on whether you're using Go or TypeScript.

Select language below for specific instructions.

The TypeScript runtime uses two environment variables: ENCORE_RUNTIME_CONFIG and ENCORE_RUNTIME_SECRETS, for configuring the runtime environment and its secret values, respectively.

The ENCORE_RUNTIME_CONFIG environment variable is a base64-encoded Protobuf message. You can find the schema here.

Generating the runtime configuration

To generate the runtime configuration, we recommend using buf convert to express the configuration in JSON format and then converting it to binary format.

To do so, install buf, then clone https://github.com/encoredev/encore and run:

$ cd encore/proto
$ echo '{"environment": {"app_id": "test"}}' | buf convert --type encore.runtime.v1.RuntimeConfig --from -#format=json | base64
CgYKBHRlc3Q=

You should see something like the above.

The below examples will show the configuration in JSON format for readability, but when setting the ENCORE_RUNTIME_CONFIG value it must first be converted to the base64-encoded binary format according to the above instructions.

Example

The Encore runtime configuration is designed so that most of the configuration can safely be left out. The only thing that's truly required is to configure which services and gateways are hosted by the container.

A minimal example configuration looks like this:

{
  "deployment": {
    "hosted_services": [{ "name": "foo" }, { "name": "bar" }],
    "hosted_gateways": ["api-gateway"]
  }
}

More instructions coming soon.

Edit this file on GitHub