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 |
+------+ +-----------------+ +-----------+ +------------+
- A Code push triggers automated image building
- CI builds and tests the image
- Tested images are published to Docker Hub.
- 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 allows any automated build and test tool that meets these requirements:
- Able to trigger a build from a code change like a pull request or a merge.
- Able to run tests on the code and the application in the container.
- Able to manually trigger a previous build and test.
- Able to publish container to Docker Hub.
- Able to provide a build and test log.
- Secure and keeps secrets from being exposed.
Containerized App Requirements
When the application is ran in the container it must:
- Accept its configuration through environment variables.
- Listen on environment variable
$PORT
for HTTP requests. - Must have a JSON version object at
/app/version.json
. - Respond to
/__version__
with the contents of/app/version.json
. - 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. - Respond to
/__lbheartbeat__
with an HTTP 200. This is for load balancer checks and should not check backing services. - Send text logs to
stdout
orstderr
. - Serve its own static content.
Dockerfile requirements
- Sources should be copied to the
/app
directory in the container. - Create an
app
group with a GID of10001
. - Create an
app
user with a UID of10001
and is a member of theapp
group. - Have both
ENTRYPOINT
andCMD
instructions to start the service. - Have a
USER app
instruction to set the default user.
Optional Recommendations
- 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.
- Log to
stdout
in the mozlog json schema. - Containers should be optimized for production use.
- Listen on port 8000.