CCP Docker images guide

This guide covers CCP specific requirements for defining Docker images.

Docker files location

All docker files should be located in docker/<component_name> directory, for example:


The docker directory may contain multiple components.

Docker directory structure

Each docker directory should contain a Dockerfile.j2 file. Dockerfile.j2 is a file which contains Docker build instructions in a Jinja2 template format. You can add additional files, which will be used in Dockerfile.j2, but only Dockerfile.j2 can be a Jinja2 template in this directory.

Dockerfile format

Please refer to the official Docker documentation which covers the Dockerfile format. CCP has some additional requirements, which is:

  1. Use as few layers as possible. Each command in Dockerfile creates a layer, so make sure you’re grouping multiple RUN commands into one.
  2. If it’s possible, please run container from the non-root user.
  3. If you need to copy some scripts into the image, please place them into the /opt/ccp/bin directory.
  4. Only one process should be started inside container. Do not use runit, supervisord or any other init systems, which will allow to spawn multiple processes in container.
  5. Do not use CMD and ENTRYPOINT commands in Dockerfile.j2.
  6. All OpenStack services should use openstack-base parent image in FROM section. All non-OpenStack services should use base-tools parent image in FROM section.

Here is an example of valid Dockerfile.j2: Keystone Dockerfile

Supported Jinja2 variables

Only specific variables can actually be used in Dockerfile.j2:

  1. namespace - Used in the FROM section, renders into image namespace, by default into ccp.
  2. tag - Used in the FROM section, renders into image tag, by default into latest.
  3. maintainer - Used in the MAINTAINER section, renders into maintainer email, by default into “MOS Microservices <>”
  4. copy_sources - Used anywhere in the Dockerfile. please refer to corresponding documentation section below.
  5. Additionaly, you could use variables with software versions, please refer to Application definition contribution guide for details.


The CCP CLI provides additional feature for Docker images creation, which will help to use git repositories inside Dockerfile, it’s called copy_sources.

This feature uses configuration from service/files/defaults.yaml from the same repository or from global config, please refer to Application definition contribution guide for details.


After making any changes in docker directory, you should test it via build and deploy.

To test building, please run:

ccp build -c <component_name>

For example:

ccp build -c keystone

Make sure that image is built without errors.

To test the deployment, please build new images using the steps above and after run:

ccp deploy

Please refer to Quick Start for additional information.