Operations grimoire/Add a service to Docker PaaS

To add a service to Docker PaaS, it needs to be configured in the Operations repository. Salt will then deploy the needed files and instruct Docker to run the containers.

Standard procedure

To deploy a service to the Docker PaaS, 3 things are needed:

• an image
• a container deployment
  • the properties of the container
  • the configuration files, volumes needed by the container
• a nginx configuration

Docker image

Services can use an image published on a public registry like hub.docker.com or quay.io.

In several cases, the already published image isn't suitable to our needs. In such case, a custom Docker image is needed.

For each custom image, or group of images, create a repository docker-<name of the service> with Dockerfile. Follows DevCentral new-repo documentation with Docker images tag.

As of 2023-05-22, Dwellers is the Docker development server suitable to prepare and test the image.

Docker container

In rOPS: roles/paas-docker/containers, you can create a new .sls file with the name of the service.

This file will usually contains:

• the directories to create for the service volumes
• the files to copy in those directories
• the configuration of the container itself -> this part will be sent to the Docker Engine HTTP API by Salt

If any file or config needs a credentials, they are stored in Vault under ops/secret path.

The states in this file are usually in a loop, so we can run several instances of the service.

In parallel, you need to add your instance in a file under rOPS: pillar/paas/docker: the main.sls files are artifacts from our old unified configuration, the other files are the modern way to divide configuration in unit logic, a little bit like service "stacks". It's recommended to create a new <service>.sls file for new deployments.

nginx

If you need a nginx configuration, add it, again using service name, in rOPS: roles/­paa­s-d­ock­er/­ngi­nx/­fil­es/­vhosts.

If you don't need to configure anything, just add this in your file: {% include 'roles/paas-docker/nginx/files/vhosts/_default.conf' %}

To deploy your change, use one of the following:

• salt docker-002 state_sls roles/paas-docker/nginx/config
• salt docker-002 state.sls_id /etc/nginx/vhosts/phabricator/devcentral.conf roles/paas-docker/nginx/config if you need to pinpoint only your change

Replace docker-002 by the server to target.

Special considerations

Databases

If an application needs a database, 3 possibilities can occur:

• a database server, like db-A or db-B, recommended for data shared with Nasqueron applications
• a specific database container, when data doesn't need to be shared
• for MySQL on docker-002, Phabricator instances use the container `acquisitariat`

Wrapper scripts

A wrapper script allows to interact with a service from command line. Such wrapper allows usually to write "<service> <instance> <command> [args]", which can run the command in <instance> container, or spawn a new <service> container attached to the first or in the same network.

Wrappers are located in {Ops file|roles/paas-docker/wrappers}}.

• Deploy dependencies services like databases
• When you need to interact from the command line with the container, prepare a wrapper script
• Configure the service in rOPS: pillar/paas/docker.sls
• Create a new service sls file in rOPS: roles/paas-docker/containers. The name must match the service name in the pillar.

Kernel

Some applications require or suggest a kernel change.

If so, the kernel for the Docker Engine server is configured through sysctl and tuned in rOPS: roles/paas-docker/kernel.

Cheat sheet

A cheat sheet is available at https://www.cheatography.com/dereckson/cheat-sheets/docker-paas/ with the following content: