View source for 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 <code>docker-<name of the service></code> with Dockerfile. Follows [https://devcentral.nasqueron.org/w/new-repo/ DevCentral new-repo documentation] with <code>Docker images</code> tag.

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

=== Docker container ===

In {{Ops file|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 {{Ops file|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 {{Ops file|roles/paas-docker/nginx/files/vhosts}}.

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

To deploy your change, use one of the following:

* <code>salt docker-002 state_sls roles/paas-docker/nginx/config</code>
* <code>salt docker-002 state.sls_id /etc/nginx/vhosts/phabricator/devcentral.conf roles/paas-docker/nginx/config</code> 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 {{Ops file|pillar/paas/docker.sls}}
* Create a new service sls file in {{Ops file|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 {{Ops file|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:

[[File:Cheat sheet for PaaS Docker.PNG|1024px]]