Widemesh Builds with Dockerfile

Formula: Dockerfile

The dockerfile formula allows you to use Docker images to deploy your app specifying build steps and dependencies using a Dockerfile.

Widemesh takes care of building a Docker image, push it to a private repository, secure it, and deploy it to the Services in your Stack.

If you don’t have a Dockerfile, start by creating one, the following dockerfile uses bithavoc/hello-world-env as a base image and customizes its CMD:

FROM bithavoc/hello-world-env
CMD ["/root/app"]

Deploy the source code with: --dockerfile as follows:

mesh deploy --dockerfile

Default command and service overrides

Widemesh starts the container with the command specified in CMD when the service has no explicit command set.

Assuming the default image specifies the CMD "/root/app" that starts the Web Service and your stack has two services web and worker, you can override CMD for the worker service as follows:

mesh svc update worker --command "/root/app worker"

We highly recommend not using ENTRYPOINT in your Dockerfile. The default is /bin/sh -c and allows expansion of environment variables you set via mesh config to be used in CMD in the Service Command.

For example, given the following setup:

mesh config set MESSAGE="hi"
mesh service update worker --command "/root/app -message \$MESSAGE"

Then Widemesh would launch a service with the following command: /root/app -message hi.

Release command

Every Stack could specify a release command to run on every new deployment, which can be useful for tasks such as:

  • Running database schema migrations
  • Uploading artifacts compiled in the build process to an external system

If a stack release command fails, the new build is not applied to its services, leaving your current workloads unaffected.

To set the release command from the CLI:

mesh stack set-release-command -- rails db:migrate

Environment Variables

If you need a configuration variable set via mesh config to be available in the commands of your Dockerfile you need to use ARG explicitly, example:

Config var:

mesh config set RAILS_ENV="production"




The next section highlights some limitations and possible walkarounds when using Docker images to deploy apps on Widemesh.

Base Image

Any image you reference in the FROM clause needs to be from a base image.


  • Distro-less docker images are not supported, must be a distro-based image such as ubuntu, alpine, go:alpine, etc
  • Must be a public image; private registries are not supported.

Local Builds

It’s not possible to build the docker image using the docker build command from your personal computer. Instead, push the source code to the stack using mesh deploy and Widemesh builds the image for you using a private temporary Docker builder.


EXPOSE in Dockerfile is not respected, but can be used for local testing. The web process must listen for HTTP traffic on $PORT, which is set by Widemesh.


VOLUME in Dockerfile is not respected; all containers in Widemesh are ephemeral, and file changes are lost when new deployments occur.

Each container’s file system is also private, and files written to the file system are not reflected in the file system of other containers, not even in the same Rack.

We recommend keeping the data in an external database such as Postgres or MySQL and file uploads in a persistent block-storage service such as AWS S3 or Backblaze B2.