Dockerflow

Dockerflow is a specification for automated building, testing and publishing of docker web application images that comply to a common set of behaviours. Compliant images are simpler to deploy, monitor and manage in production.

The specification is this README.md file. This repo contains a reference application that will change with the specification. See the Contribution document for details on suggesting changes and providing feedback.

Automated Creation Pipeline

  +-(1)--+         +-(2)-------------+        +-(3)-------+        +-(4)--------+
  | Code |         |  CI builds and  |        |   Docker  |        | Container  |
  | Push | ------> | tests container | -----> |    Hub    | -----> | Deployment |
  +------+         +-----------------+        +-----------+        +------------+

1. A Code push triggers automated image building
2. CI builds and tests the image
3. Tested images are published to Docker Hub.
4. Images are pulled from Docker Hub to be used

Specification

The specification has requirements that a container must comply with. Recommendations are optional but encouraged if they are suitable for the application.

Building and Testing

Dockerflow requires an automated build and test tool that meets these requirements:

1. Able to trigger a build from a code change like a pull request or a merge.
2. Able to run tests on the code and the application in the container.
3. Able to manually trigger a previous build and test.
4. Able to publish container to Docker Hub or Google Artifact Registry.
5. Able to provide a build and test log.
6. Secure and keeps secrets from being exposed.

Within Mozilla, we support the use of CircleCI, Taskcluster, or Github Actions.

Containerized App Requirements

When the application is ran in the container it must:

1. Accept its configuration through environment variables.
2. Listen on environment variable $PORT for HTTP requests.
3. Must have a JSON version object at /app/version.json.
4. Respond to /__version__ with the contents of /app/version.json.
5. Respond to /__heartbeat__ with a HTTP 200 or 5xx on error. This should check backing services like a database for connectivity and may respond with the status of backing services and application components as a JSON payload.
6. Respond to /__lbheartbeat__ with an HTTP 200. This is for load balancer checks and should not check backing services.
7. Send text logs to stdout or stderr.
8. Serve its own static content.

Dockerfile requirements

1. Sources should be copied to the /app directory in the container.
2. Create an app group with a GID of 10001.
3. Create an app user with a UID of 10001 and is a member of the app group.
4. Have both ENTRYPOINT and CMD instructions to start the service.
5. Have a USER app instruction to set the default user.

Optional Recommendations

1. Each instance of a container should only run one process. If you need to run two processes, just create another instance of the container & run a different command.
2. Log to stdout in the mozlog json schema.
3. Containers should be optimized for production use.
4. Listen on port 8000.

Docker Hub Credentials

Internal processes for managing DOCKER_USER and DOCKER_PASS per-project are documented in hiera-sops/misc/dockerhub/.

Contributing

• Contribution Guidelines