In this post, I will go over how you can use docker-compose and Gitlab CI. In this example, we will be running playwright tests directly on the Gitlab runner. The tests will start a SvelteKit server also running on the Gitlab runner. The SvelteKit server will connect to PocketBase (backend) running in docker-compose.

So essentially we need a way for something running locally to connect to something running in docker in Gitlab CI (on a runner). This is a pattern I am using in my new app Bookmarkey ¹.

Let’s pretend we have a docker-compose.yml file which looks something like this:

services:
  pocketbase:
    image: ghcr.io/muchobien/pocketbase:latest
    ports:
      - '9090:8090'
    volumes:
      - ./pb_data:/pb_data
      - /pb_public

and our package.json scripts section looks like this:

{
    "scripts": {
        "test": "playwright test",
    },
}

Finally the most important file let’s look at the gitlab ci file .gitlab-ci.yml:

stages:
  - test

tests:e2e:
  stage: test
  only:
    - merge_request
  image: mcr.microsoft.com/playwright:v1.29.0-jammy
  services:
    - docker:dind
  variables:
    DOCKER_DRIVER: overlay2
    DOCKER_HOST: tcp://docker:2375
    VITE_POCKET_BASE_URL: 'http://docker:9090'
  script:
    - # ... Installing docker and docker compose
    - docker compose up -d
    - npm run test

Since all Gitlab CI jobs run in Docker. If we want to run docker-compose inside a job we need to use the dind service ². We can then use docker normally i.e. using docker compose to start PocketBase. The most important line here is normally to connect to PocketBase I would use http://localhost:8090. However, since we are using the dind service we need to use docker instead of localhost. Hence this VITE_POCKET_BASE_URL: 'http://docker:9090', passed to my SvelteKit app.

I spent about two days debugging this issue, even though I’d solved this problem before 🤦‍♂️. So I decided to make a quick post so hopefully you can avoid wasting your time.

In this article, we will go over how you can personalise your dev containers. Devcontainers allow us to create consistent development environments. One of the main advantages of dev containers is we can provide a “one button” setup for new developers. We do this by using a container (Docker), and we end up developing inside a container. Much like if we used docker exec -it ubuntu /bin/bash. Except it provides a few nice conveniences such as copying (into the container) over the project files and our ssh keys.

However one of the issues that can arise from this is how you get your dev tools/programs in the dev container. For example, I use fish shell but lots of Docker containers default to using bash. I also don’t want to pollute the Docker file with a bunch of my specific dev tools. If every developer does that you could end up with a very large Docker file. This will also mean it takes longer for the dev container to build.

One way we can do this is by using DotBot and a dotfiles repo. I will assume you are familiar with everything we’ve covered up to this point. You have a dotfiles repo which uses DotBot, has profiles and has plugins installed. In this example, we will be using the dotbot-apt plugin.

Dotfiles

Let’s go to our dotfiles repo which we will assume looks like:

├── ....
├── bashrc
├── fish
│   └── fish.config
├── .gitconfig
├── install-profile
├── install-standalone
├── meta
│   ├── configs
│   │   └── git.yaml
│   ├── dotbot
│   ├── dotbot-apt
│   ├── base.yaml
│   └── profiles
│       └── linux
└── vscode

configs

It may look something like the above. Let’s create some new configs specific to our dev container. In this case, we will assume all the dev containers we will use will be Debian based. So let’s create a file meta/configs/packages.debian.yaml which may look like this:

- apt:
    - jq
    - fzf
    - vim
    - make
    - zoxide
    - exa
    - fish

This will be used to install the specific dev tools I need such as jq and fzf. Next, I want to make sure my fish shell config also gets set up correctly so we will create another file called meta/configs/shell.yaml which looks like this:

- link:
    ~/.config/fish:
      path: fish/**
      glob: true
      create: true

profiles

This will copy (symlink) all of my fish config files to ~/.config/fish/ directory in the dev container from the dotfiles repo. Next, let us create a new profile meta/profiles/devcontainer which will look like:

packages.debian-sudo
shell

Remember by appending -sudo to packages.debian we will run those directives as root i.e. apt.

Install Script

So what we have done is create a new profile which will install some of the dev tools we need and copy over our fish config. Now we have to do one final thing create a new file at the root called install.devcontainer.sh (you can call this whatever you want, just remember the name). This file looks like:

#!/usr/bin/env bash

./install-profile devcontainer

The reason we need this we need to provide an executable file in our VS Code config. We couldn’t just run specify this ./install-profile devcontainer. We will see this a bit later.

Structure

Our repo structure now looks like

├── ....
├── bashrc
├── fish
│   └── fish.config
├── .gitconfig
├── install-profile
├── install-standalone
├── meta
│   ├── configs
│   │   ├── shell.yaml
│   │   ├── packages.debian.yaml
│   │   └── git.yaml
│   ├── dotbot
│   ├── dotbot-apt
│   ├── base.yaml
│   └── profiles
│       └── linux
└── vscode

Now let’s move on to the repository that is using dev containers. We are going to use a super simple example, just to demonstrate. Let’s create a new file .devcontainer/devcontainer.json which looks like this:

{
 "name": "Go",
  "image": "mcr.microsoft.com/devcontainers/go:0-1.18",
  "features": {
    "ghcr.io/devcontainers/features/node:1": {
      "version": "lts"
    }
  },

  // Configure tool-specific properties.
  "customizations": {
    // Configure properties specific to VS Code.
    "vscode": {
      // Set *default* container specific settings.json values on container create.
      "settings": {
        "go.toolsManagement.checkForUpdates": "local",
        "go.useLanguageServer": true,
        "go.gopath": "/go"
      }
    }
  },

  // Use 'forwardPorts' to make a list of ports inside the container available locally.
  // "forwardPorts": [],

  // Use 'postCreateCommand' to run commands after the container is created.
  // "postCreateCommand": "go version",

  // Set `remoteUser` to `root` to connect as root instead. More info: https://aka.ms/vscode-remote/containers/non-root.
  "remoteUser": "vscode"
}

This is the default one generated by VS Code for Golang projects (when using the command palette). Normally we would have a custom Docker image we are using. Perhaps in a future post, I will go over how to use dev containers with an existing custom Docker image. But for this example, we will just use the Microsoft provided golang image mcr.microsoft.com/devcontainers/go:0-1.18.

This is enough to create a dev container, we can open the command palette on VS Code and run rebuild and reopen in container. However this is one final thing we need to do.

Open your settings.json file and add something like so:

{
  // ...
  "dotfiles.repository": "hmajid2301/dotfiles",
  "dotfiles.targetPath": "~/dotfiles",
  "dotfiles.installCommand": "~/dotfiles/install.devcontainer.sh",
  // ...
}

• dotfiles.repository: You will need to update the repo hmajid2301/dotfiles to point to your dotfiles repo and it must be accessible on github.
• dotfiles.targetPath: The targetPath is where in the devcontainer we will git clone our dotfiles repo.
• dotfiles.installCommand: The executable it will run after the devcontainer is set up. If you called it something else you will need to update that here as well.

That’s it, now we can have a common dev container set up and personalise with our dotfiles and specific dev tools we want using DotBot.

Appendix

• My Dotfiles
• My devcontainer DotBot profile

For most of my common dev tasks, I’ve started to rely on docker/docker compose to run commands locally. I have also started using vscode’s .devcontainers, to provide a consistent environment for all developers using a project.

The main reason for this is to avoid needing to install dependencies on my host machine. In theory, all I should need is a Docker daemon and a CLI (docker CLI) to interact with that Daemon. This also makes it far easier for any new developer to start working on my project and get set up.

What inspired me to do this change now (in my banter bus project) was I wanted to upgrade to python 3:10 to use some of the new typing features released. However when I tried to upgrade my CI pipeline started failing, after hours of trying to debug it. I ended up using Docker and everything ran smoothly.

Now to have a more consistent environment between my local environment and CI. So in theory, it means less chance of something passing locally but failing in CI.

Now we know why we want to do it. let’s look at how we do it.

Before

Let’s take a look at what a typical CI pipeline may look for a Python project (using banter bus). In this example, we will be using a FastAPI web service which uses Poetry to manage its dependencies.

image: python:3.10.5

variables:
  DOCKER_DRIVER: overlay2
  PIP_CACHE_DIR: "${CI_PROJECT_DIR}/.cache/pip"
  PIP_DOWNLOAD_DIR: ".pip"
  DOCKER_HOST: tcp://docker:2375

cache:
  key: "${CI_JOB_NAME}"
  paths:
    - .cache/pip
    - .venv

.test:
  services:
    - name: mongo:4.4.4
      alias: banter-bus-database
    - name: redis:6.2.4
      alias: banter-bus-message-queue
    - name: registry.gitlab.com/banter-bus/banter-bus-management-api:test
      alias: banter-bus-management-api
    - name: registry.gitlab.com/banter-bus/banter-bus-management-api/database-seed:latest
      alias: banter-bus-database-seed
  variables:
    MONGO_INITDB_ROOT_USERNAME: banterbus
    MONGO_INITDB_ROOT_PASSWORD: banterbus
    MONGO_INITDB_DATABASE: test
    BANTER_BUS_MANAGEMENT_API_DB_USERNAME: banterbus
    BANTER_BUS_MANAGEMENT_API_DB_PASSWORD: banterbus
    BANTER_BUS_MANAGEMENT_API_DB_HOST: banter-bus-database
    BANTER_BUS_MANAGEMENT_API_DB_PORT: 27017
    BANTER_BUS_MANAGEMENT_API_DB_NAME: test
    BANTER_BUS_MANAGEMENT_API_WEB_PORT: 8090
    BANTER_BUS_MANAGEMENT_API_CLIENT_ID: client_id
    BANTER_BUS_MANAGEMENT_API_USE_AUTH: "False"
    MONGO_HOSTNAME: banter-bus-database:27017
    BANTER_BUS_CORE_API_DB_USERNAME: banterbus
    BANTER_BUS_CORE_API_DB_PASSWORD: banterbus
    BANTER_BUS_CORE_API_DB_HOST: banter-bus-database
    BANTER_BUS_CORE_API_DB_PORT: 27017
    BANTER_BUS_CORE_API_DB_NAME: test
    BANTER_BUS_CORE_API_MANAGEMENT_API_URL: http://banter-bus-management-api
    BANTER_BUS_CORE_API_MANAGEMENT_API_PORT: 8090
    BANTER_BUS_CORE_API_CLIENT_ID: client_id
    BANTER_BUS_CORE_API_USE_AUTH: "False"
    BANTER_BUS_CORE_API_MESSAGE_QUEUE_HOST: banter-bus-message-queue
    BANTER_BUS_CORE_API_MESSAGE_QUEUE_PORT: 6379

stages:
  - test

before_script:
  - pip download --dest=${PIP_DOWNLOAD_DIR} poetry
  - pip install --find-links=${PIP_DOWNLOAD_DIR} poetry
  - poetry config virtualenvs.in-project true
  - poetry install -vv

test:lint:
  stage: test
  only:
    - merge_request
  script:
    - poetry run pre-commit run --all-files

test:unit-tests:
  stage: test
  only:
    - merge_request
  script:
    - poetry run pytest -v tests/unit

test:integration-tests:
  stage: test
  only:
    - merge_request
  extends:
    - .test
  script:
    - poetry run pytest -v tests/integration

The above looks quite complicated, but very simply we install our dependencies for each job the before_script section is used in all jobs. All jobs also use python:3.9.8 image, this is where our code is cloned into the CI pipeline.

Where our .pre-commit-config.yaml looks something like this:

repos:
  - repo: https://github.com/pre-commit/pre-commit-hooks
    rev: v3.3.0
    hooks:
      - id: check-yaml
        args: ["--allow-multiple-documents"]
  - repo: local
    hooks:
      - id: forbidden-files
        name: forbidden files
        entry: found copier update rejection files; review them and remove them
        language: fail
        files: "\\.rej$"
      - id: black
        name: black
        entry: poetry run black
        language: system
        types: [python]
      - id: flake8
        name: flake8
        entry: poetry run flake8
        language: system
        types: [python]
      - id: isort
        name: isort
        entry: poetry run isort --settings-path=.
        language: system
        types: [python]
      - id: pyupgrade
        name: pyupgrade
        entry: poetry run pyupgrade
        language: system
        types: [python]
        args: [--py310-plus]
      - id: mypy
        name: mypy
        description: Check python types.
        entry: poetry run mypy
        language: system
        types: [python]

pre-commit is a library we can use to add pre-commit hooks before we commit our code to git. Adding some checks that the code is consistent with the rules we defined. We can also just use it as a lint job, multiple linting tools together. Simplified. Hence here we are checking for code formatting, linting, import sorting etc. The details don’t matter but at the moment we need to have a virtualenv locally to run this.

Integration Tests

A slightly more interesting job is integration tests, it requires other docker containers, as our tests need Postgres and Redis to run. We can define these as services and then reference them in our job like so:

test:integration-tests:
  stage: test
  only:
    - merge_request
  extends:
    - .test
  script:
    - poetry run pytest -v tests/integration

Note the extends clause, which essentially merges the .test section with our job so it will look something like:

test:integration-tests:
  stage: test
  only:
    - merge_request
  services:
    - name: mongo:4.4.4
      alias: banter-bus-database
    - name: redis:6.2.4
      alias: banter-bus-message-queue
    - name: registry.gitlab.com/banter-bus/banter-bus-management-api:test
      alias: banter-bus-management-api
    - name: registry.gitlab.com/banter-bus/banter-bus-management-api/database-seed:latest
      alias: banter-bus-database-seed
  variables:
    MONGO_INITDB_ROOT_USERNAME: banterbus
    MONGO_INITDB_ROOT_PASSWORD: banterbus
    MONGO_INITDB_DATABASE: test
    BANTER_BUS_MANAGEMENT_API_DB_USERNAME: banterbus
    BANTER_BUS_MANAGEMENT_API_DB_PASSWORD: banterbus
    BANTER_BUS_MANAGEMENT_API_DB_HOST: banter-bus-database
    BANTER_BUS_MANAGEMENT_API_DB_PORT: 27017
    BANTER_BUS_MANAGEMENT_API_DB_NAME: test
    BANTER_BUS_MANAGEMENT_API_WEB_PORT: 8090
    BANTER_BUS_MANAGEMENT_API_CLIENT_ID: client_id
    BANTER_BUS_MANAGEMENT_API_USE_AUTH: "False"
    MONGO_HOSTNAME: banter-bus-database:27017
    BANTER_BUS_CORE_API_DB_USERNAME: banterbus
  	BANTER_BUS_CORE_API_DB_PASSWORD: banterbus
  	BANTER_BUS_CORE_API_DB_HOST: banter-bus-database
  	BANTER_BUS_CORE_API_DB_PORT: 27017
  	BANTER_BUS_CORE_API_DB_NAME: test
  	BANTER_BUS_CORE_API_MANAGEMENT_API_URL: http://banter-bus-management-api
  	BANTER_BUS_CORE_API_MANAGEMENT_API_PORT: 8090
  	BANTER_BUS_CORE_API_CLIENT_ID: client_id
  	BANTER_BUS_CORE_API_USE_AUTH: "False"
  	BANTER_BUS_CORE_API_MESSAGE_QUEUE_HOST: banter-bus-message-queue
  	BANTER_BUS_CORE_API_MESSAGE_QUEUE_PORT: 6379
  script:
    - poetry run pytest -v tests/integration

We also need to define a bunch of environment variables in this case so our containers can communicate with each other. Now, these are of course specific to my apps. But you can imagine a real-life project also needing a bunch of environment variables. As you can see this can get a bit messy and what is running locally may differ slightly from what is running in CI.

I have been caught out by these env variables in the past. Note variables like BANTER_BUS_CORE_API_MANAGEMENT_API_URL: http://banter-bus-management-api. The name of the container must match the URL we have provided

    - name: registry.gitlab.com/banter-bus/banter-bus-management-api:test
      alias: banter-bus-management-api

Docker DNS (link to DNS) is clever enough to work out the IP address. This is also different now to how we are running it locally.

After

Now we are running all our dev tasks in docker. We will use docker-compose to manage all of the containers, docker-compose makes managing multiple containers a lot easier. We define all of them in our docker-compose.yml file.

services:
  app:
    container_name: banter-bus-core-api
    build:
      context: .
      dockerfile: Dockerfile
      target: development
      cache_from:
        - registry.gitlab.com/banter-bus/banter-bus-core-api:development
    environment:
      XDG_DATA_HOME: /commandhistory/
      BANTER_BUS_CORE_API_DB_USERNAME: banterbus
      BANTER_BUS_CORE_API_DB_PASSWORD: banterbus
      BANTER_BUS_CORE_API_DB_HOST: banter-bus-database
      BANTER_BUS_CORE_API_DB_PORT: 27017
      BANTER_BUS_CORE_API_DB_NAME: test
      BANTER_BUS_CORE_API_MANAGEMENT_API_URL: http://banter-bus-management-api
      BANTER_BUS_CORE_API_MANAGEMENT_API_PORT: 8090
      BANTER_BUS_CORE_API_CLIENT_ID: client_id
      BANTER_BUS_CORE_API_USE_AUTH: "False"
      BANTER_BUS_CORE_API_MESSAGE_QUEUE_HOST: banter-bus-message-queue
      BANTER_BUS_CORE_API_MESSAGE_QUEUE_PORT: 6379
    ports:
      - 127.0.0.1:8080:8080
    volumes:
      - ./:/app
      - /app/.venv/ # This stops local .venv getting mounted
    depends_on:
      - database
      - management-api
      - message-queue
      - database-seed

  management-api:
    container_name: banter-bus-management-api
    image: registry.gitlab.com/banter-bus/banter-bus-management-api:test
    environment:
      BANTER_BUS_MANAGEMENT_API_DB_USERNAME: banterbus
      BANTER_BUS_MANAGEMENT_API_DB_PASSWORD: banterbus
      BANTER_BUS_MANAGEMENT_API_DB_HOST: banter-bus-database
      BANTER_BUS_MANAGEMENT_API_DB_NAME: banter_bus_management_api
      BANTER_BUS_MANAGEMENT_API_WEB_PORT: 8090
      BANTER_BUS_MANAGEMENT_API_CLIENT_ID: client_id
      BANTER_BUS_MANAGEMENT_API_USE_AUTH: "False"
    ports:
      - 127.0.0.1:8090:8090
    depends_on:
      - database

  database:
    container_name: banter-bus-database
    image: mongo:4.4.4
    environment:
      MONGO_INITDB_ROOT_USERNAME: banterbus
      MONGO_INITDB_ROOT_PASSWORD: banterbus
      MONGO_INITDB_DATABASE: banterbus
    volumes:
      - /data/db
    ports:
      - 27017:27017

  database-gui:
    container_name: banter-bus-database-gui
    image: mongoclient/mongoclient:4.0.1
    depends_on:
      - database
    environment:
      - MONGOCLIENT_DEFAULT_CONNECTION_URL=mongodb://banterbus:banterbus@banter-bus-database:27017
    volumes:
      - /data/db mongoclient/mongoclient
    ports:
      - 127.0.0.1:4000:3000

  database-seed:
    container_name: banter-bus-database-seed
    image: registry.gitlab.com/banter-bus/banter-bus-management-api/database-seed:latest
    environment:
      MONGO_INITDB_ROOT_USERNAME: banterbus
      MONGO_INITDB_ROOT_PASSWORD: banterbus
      MONGO_INITDB_DATABASE: banter_bus_management_api
      MONGO_HOSTNAME: banter-bus-database:27017
    depends_on:
      - database

  message-queue:
    container_name: banter-bus-message-queue
    image: redis:6.2.4
    volumes:
      - /data/datastore /data
    ports:
      - 127.0.0.1:6379:6379

Note: This file was already defined just not used in CI because I wanted to provide an easy way to start up my “tech stack”. So the file had gone unused.

How do run our dev tasks?

• lint: docker compose run app poetry run pre-commit run --all-files
• integration tests: docker compose run app poetry run pytest -v tests/integration

Then our CI pipelines could look simply like this:

image: docker

services:
  - docker:dind

variables:
  DOCKER_DRIVER: overlay2
  DOCKER_HOST: tcp://docker:2375

before_script:
  - docker compose build

stages:
  - test

test:lint:
  stage: test
  only:
    - merge_request
  script:
    - docker compose run app poetry run pre-commit run --all-files

test:unit-tests:
  stage: test
  only:
    - merge_request
  script:
    - docker compose run app poetry run pytest -v tests/unit

test:integration:
  stage: test
  only:
    - merge_request
  script:
    -  docker compose run app poetry run pytest -v tests/integration

Now before job we build our docker images, docker compose build. Then to run the dev task we do something like:

docker compose run app <command to run>

So to run unit tests we could do:

docker compose run app poetry run pytest -v tests/unit

Aside

We could simplify this if we use makefile and make the target be poetry run pytest -v tests/unit.

.PHONY: unit_tests
unit_tests: ## Run all the unit tests
	@poetry run pytest -v tests/unit

Then our ci job would look something like:

test:unit-tests:
  stage: test
  only:
    - merge_request
  script:
    - make unit_tests

Which I think is a lot more readable and a lot easier to type. We can also leverage auto-complete on the terminal and add help targets. So a user can see all the targets they can run.

DNS

You can think of DNS like a phonebook, except instead of people’s name and phone numbers, it stores domains names and IP addresses (this can be either IPv4 or IPv6). Where a domain name is used to identify resources i.e. google.com is a domain name. This is how DNS works:

google.com:     8.8.8.8
cloudflare.com: 1.1.1.1

Example

You can manually send a DNS request (and get a response) using the dig command. So for example, we can do something like this.

dig +short google.com
172.217.169.78

Records

Each DNS entry can be of varying types, some of the most common DNS types (referred to as records) are:

A: Points a domain name to an IPv4 address i.e. 8.8.8.8 AAAA: Same as an A record except points to an IPv6 address i.e. 2001:db8:0:1 CNAME: Canonical Name points one domain to another domain name, one common use case is to point www.example.com -> example.com. This way we only need to update the A record of example.com, not both domains.

AAAA Example

To specify a AAAA (quad A) record we can do something like:

dig +short google.com AAAA
2a00:1450:4009:810::200e

So that’s DNS in a nutshell! On to how it relates to Docker.

Docker

For the sake of this article, we will be using the following docker-compose file:

version: "3.5"

services:
  web_server:
    container_name: nginx
    build:
      context: .
      dockerfile: docker/nginx/Dockerfile
    ports:
      - 80:80
    depends_on:
      - app

  app:
    container_name: flask
    build:
      context: .
      dockerfile: docker/flask/Dockerfile
    env_file: docker/database.conf
    expose:
      - 8080
    depends_on:
      - database

  database:
    container_name: postgres
    image: postgres:latest
    env_file: docker/database.conf
    ports:
      - 5432:5432
    volumes:
      - db_volume:/var/lib/postgresql

volumes:
  db_volume:

It will create three containers, Nginx, a flask app and a Postgres database, when we run docker-compose up --build, in particular take note of the container_name(s): postgres, nginx, flask.

Nginx

Our nginx config file looks something like:

server {
  listen 80;
  server_name _;

  location / {
    try_files $uri @app;
  }

  location @app {
    include /etc/nginx/uwsgi_params;
    uwsgi_pass flask:8080;
  }
}

This Nginx configuration file tells Nginx to pass any requests sent on / path to the uwsgi server running in the flask docker container. Now taking a look at the location @app section you’ll notice for uwsgi_pass we don’t specify an IP address to send the requests to. Instead, we use the container name, this is because within Docker containers we don’t have to specify the other Docker container’s IP address to connect to it we can specify the container name. Docker’s DNS will resolve the name into an IP address for us.

Nginx Example

So if I open a shell on the nginx container:

docker exec -it nginx bash

Then we can do something like:

apt update && apt install dnsutils
dig flask +short
172.23.0.3

This is particularly useful because Docker containers get assigned an IP if you don’t specify one (in the docker-compose.yml) file. Taking a look at the IP assigned to the flask the container matches the IP address returned by the dig command.

docker inspect -f '{{range.NetworkSettings.Networks}}{{.IPAddress}}{{end}}' flask
172.23.0.3

Flask Example

Similarly in the flask container if we want to connect to the postgres database, we can just specify the host using the container name postgres rather than an IP in our connection URI. As shown in the example below:

DATABASE_CONNECTION_URI = f'postgresql+psycopg2://{user}:{password}@postgres:5432/{database}'

Deep Diver

Let’s take a slightly closer look into Docker’s architecture to understand what is going on here.

Docker Engine 🏭 Explained

Docker Engine is an open-source containerization technology for building and containerizing your applications. - https://docs.docker.com/engine/

It contains the following components:

• A server with a long-running daemon process dockerd
• APIs which specify interfaces that programs can use to talk to and instruct the Docker daemon
• A command-line interface (CLI) client docker

When we install Docker we are also installing the Docker Engine.

Briefly, how it works is we use the CLI i.e. docker run/docker-compose, which makes API requests (on our behalf) to the Docker daemon. The Docker daemon then interacts with containerd, which is responsible for the creation/deletion of our containers. Essentially containerd is a container supervisor.

Docker Engine and DNS

Now how does Docker Engine relate to DNS? As long as the two containers are on the same network we can use the container name and resolve it using DNS. Each Docker container has a DNS resolver that forwards DNS queries to Docker Engine, which acts as a DNS server. Docker Engine then checks if the DNS query belongs to a container on the network that the requested container belongs to. If it does, then Docker Engine looks up the IP address that matches a container name in its key-value store and returns that IP back to the requesting container.

Misc

Appendix

• What is DNS? by CloudFlare
• DNS Records Explained
• Docker Engine
• Docker in detail SO Post
• Docker Swarm Architecture (relevant to normal Docker)

The diagram above is a visualisation of what we are trying to achieve. We want to spawn Docker containers using docker-compose from within our job. The spawning and destruction of these Docker containers will be done via our Python code. We can achieve this by using dind (Docker in Docker). I have written a previous article on this topic which you can read more about here. This article assumes you already somewhat familiar with Docker, docker-compose and Pytest.

This compose file will be used to start our Docker containers.

version: "3"

services:
  service1:
    container_name: container1
    image: docker
    command: ["tail", "-f", "/dev/null"]

  service2:
    container_name: container2
    image: docker
    command: ["tail", "-f", "/dev/null"]

Gitlab CI

Next, we have our .gitlab-ci.yml file, this file is used to tell Gitlab CI what our CI jobs should do. In this example, we have one job called test:integration which will run our integration tests. But before we do that we need a way to access the Docker daemon from within Gitlab CI, this can be done by using the docker:dind service.

The docker:dind image automatically using its entry point starts a docker daemon. We need to use this daemon to start/stop our Docker images within CI. The docker:dind (dind = Docker in Docker) image is almost identical to the docker image. The difference being the dind image starts a Docker daemon. In this example, the job will use the docker image as the client and connect to the daemon running in this container.

services:
  - docker:dind

tests:integration:
  stage: test
  image: hmajid2301/dind-docker-compose
  script:
    - pip install pytest docker lovely-pytest-docker
    - pytest -s tests/test_integration.py

The job itself is very simple, it uses a container which already comes with docker and docker-compose. Next we install the dependencies we need for our tests. Then it runs our tests.

Tests

Now onto our actual tests file. It looks more complicated than it is:

import docker as docker_py
import pytest

docker_client = docker_py.from_env()
docker_compose = None


@pytest.fixture(scope="session", autouse=True)
def docker(docker_services):
    global docker_compose
    docker_compose = docker_services


@pytest.fixture(scope="session", autouse=True)
def setup():
    docker_compose.start()
    yield
    docker_compose.shutdown()


def kill_container(container_name):
    container = get_container(container_name)
    container.kill()
    container.remove()


def get_container(container_name):
    containers = docker_client.containers.list()
    for container in containers:
        if container.name == container_name:
            return container


def start_container(service_name):
    docker_compose.start(service_name)


def test_two_containers():
    containers = docker_client.containers.list()
    assert len(containers) == 2


def test_kill_container1():
    kill_container("container1")
    containers = docker_client.containers.list()
    container1 = get_container("container1")
    assert len(containers) == 1
    assert not container1

def test_start_container1():
    start_container("service1")
    containers = docker_client.containers.list()
    container1 = get_container("container1")
    assert len(containers) == 2
    assert container11

The first part is the setup, we will use the python Docker library,docker. Which allow us to use Python code to control our Docker daemon. The first @pytest-fixture called docker allows us to use the lovely-pytest-docker library. To give us a docker_compose object which will allow us to again use Python code to control our docker-compose.yml file (start-up/stop containers). The library also has some very nice features such as waiting for containers or executing commands within containers. You can find the available functions here. Now we can access the docker_compose object by using our docker_compose global variable.

The reason we have both a library for Docker and docker-compose is because at the moment there is no way to use lovely-pytest-docker (as far as I’m aware) to stop a single container. So we need to use the standard docker library to do that. We also use the standard docker library to find out if a container is running.

Next, we have the setup() fixture which we auto use, this means the fixture is run before our test, normally a fixture would only be called once it has been referred to within another function. In this function, we start both of our containers in our docker-compose file. This is the same as running docker-compose up --build -d. Next we yield, how exactly the yield command works I won’t go over in this article, all you have to know is that everything after the yield will only be run after all of our tests. In this case we teardown our containers (stop them). This is the same as running docker-compose down.

import docker as docker_py
import pytest

docker_client = docker_py.from_env()
docker_compose = None


@pytest.fixture(scope="session", autouse=True)
def docker(docker_services):
    global docker_compose
    docker_compose = docker_services


@pytest.fixture(scope="session", autouse=True)
def setup():
    docker_compose.start()
    yield
    docker_compose.shutdown()

The next part of our file contains some helper functions I’ve written. These functions can be used by multiple tests. This helps our tests file stay more DRY (do not repeat yourself). You may well want to make these part of a (helper) class that you expose as a fixture. If you wanted to structure these properly so they can be accessed by more than one file. Also whilst we are on this topic, we may want to move our fixture to conftest.py, again to allow other files to use the same fixture we have defined here. But to keep this example simpler we will leave it here.

def kill_container(container_name):
    container = get_container(container_name)
    container.kill()
    container.remove()


def get_container(container_name):
    containers = docker_client.containers.list()
    for container in containers:
        if container.name == container_name:
            return container


def start_container(service_name):
    docker_compose.start(service_name)

Finally, onto our actual tests, in reality, these tests are very boring and not super useful but they should give you an idea what you can do. Such as killing the database container and then check how your Python application responds. Then you can start the database container and again check how your Python application responds. You can read more about how you can test Python Flask applications with pytest here.

So what do our tests do? Well, the first one checks the number of containers running is equal to 2. The next one kills container1 and checks that only one container is running and it’s not container1. Our final test starts container1 and checks that it is running and the number of containers running is back to 2. After this final test has completed then the setup fixture will run its docker_compose.shutdown() command.

def test_two_containers():
    containers = docker_client.containers.list()
    assert len(containers) == 2


def test_kill_container1():
    kill_container("container1")
    containers = docker_client.containers.list()
    container1 = get_container("container1")
    assert len(containers) == 1
    assert not container1

def test_start_container1():
    start_container("service")
    containers = docker_client.containers.list()
    container1 = get_container("container1")
    assert len(containers) == 2
    assert container1

That’s it we’ve managed to start/stop Docker containers from within Gitlab CI, using DinD. In a future article I will explain how you could run your tests within a Docker container you’ve started. Say you had three containers nginx, flask and postgres and you wanted to run your tests within the flask container. But for now that’s it, thanks for reading!

Appendix

• Example source code

A quick aside on terminology related to Docker:

• container: An instance of an image is called a container (docker run)
• image: A set of immutable layers (docker build)
• hub: The official registry where you can get more Docker images from (docker pull)

Example

Here is an example .gitlab-ci.yml file which can be used to build and push your Docker images to the Gitlab registry.

variables:
  DOCKER_DRIVER: overlay2

services:
  - docker:dind

stages:
  - publish

publish-docker:
  stage: publish
  image: docker
  script:
    - export VERSION_TAG=v1.2.3
    - docker login ${CI_REGISTRY} -u gitlab-ci-token -p ${CI_BUILD_TOKEN}
    - docker build -t ${CI_REGISTRY_IMAGE}:latest -t ${CI_REGISTRY_IMAGE}:${VERSION_TAG}  .
    - docker push ${CI_REGISTRY_IMAGE}:latest
    - docker push ${CI_REGISTRY_IMAGE}:${VERSION_TAG}

Explained

The code above may be a bit confusing, it might be a lot to take in. So now we will break it down line by line.

variables:
  DOCKER_DRIVER: overlay2

In our first couple of lines, we define some variables which will be used by all our jobs (the variables are global). We define a variable DOCKER_DRIVER: overlay2, this helps speed our Docker containers a bit because by default it uses vfs which is slower learn more here.

random-job:
  stage: publish
  variables:
    DOCKER_DRIVER: overlay2
  script:
    - echo "HELLO"

Note we could just as easily define variables just within our job as well like you see in the example above.

services:
  - docker:dind

The next couple of lines define a service. A service is a Docker image which links during our job(s). Again in this example, it is defined globally and will link to all of our jobs. We could very easily define it within our job just like in the variables example. The docker:dind image automatically using its entrypoint starts a docker daemon. We need to use this daemon to build/push our Docker images within CI.

The docker:dind (dind = Docker in Docker) image is almost identical to the docker image. The difference being the dind image starts a Docker daemon. In this example, the job will use the docker image as the client and connect to the daemon running in this container.

We could also just use the dind image in our job and simply start dockerd (& = in the background) in the first line. The dockerd command starts the Docker daemon as a client, so we can then communicate with the other Docker daemon. It would achieve the same outcome. I think the service approach is a bit cleaner but as already stated either approach would work.

publish-docker:
  stage: publish
  image: docker:dind
  script:
    - dockerd &
    ...
    - docker push ${CI_REGISTRY_IMAGE}:${VERSION_TAG}

Info: One common use case of Gitlab CI services is to spin up databases like MySQL. We can then connect to it within our job, run our tests. It can simplify our jobs by quite a bit.

Note: There are several other ways we could also build/push our images. This is the recommended approach.

stages:
  - publish

Next, we define our stages and give them names. Each job must have a valid stage attached to it. Stages are used to determine when a job will be run in our CI pipeline. If two jobs have the same stage, then they will run in parallel. The stages defined earlier will run first so order does matter. However in this example, we only have one stage and one job so this isn’t super important, more just something to keep in mind.

publish-docker:
  stage: publish
  ...

Now we define our job, where publish-docker is the name of our job on Gitlab CI pipeline. We then define what stage the job should run in, in this case, this job will run during the publish stage.

publish-docker:
  ...
  image: docker
  ...

Then we define what Docker image to use in this job. In this job, we will use the docker image. This image has all the commands we need to build and push our Docker images. It will act as the client making requests to the dind daemon.

script:
  - export VERSION_TAG=v1.2.3
  - docker login ${CI_REGISTRY} -u gitlab-ci-token -p ${CI_BUILD_TOKEN}
  - docker build -t ${CI_REGISTRY_IMAGE}:latest -t ${CI_REGISTRY_IMAGE}:${VERSION_TAG}  .
  - docker push ${CI_REGISTRY_IMAGE}:latest
  - docker push ${CI_REGISTRY_IMAGE}:${VERSION_TAG}

Finally, we get to the real meat and potatoes of the CI file. The bit of code that builds and pushes are Docker images to the registry:

- export VERSION_TAG=v1.2.3

It is often a good idea to tag our images, in this case, I’m using a release name. You could get this from say your setup.py or package.json file as well. In my Python projects I usually use this command export VERSION_TAG=$(cat setup.py | grep version | head -1 | awk -F= '{ print $2 }' | sed 's/[",]//g' | tr -d "'"), to parse my setup.py for the version number. But this can be whatever you want it to be. Here we have just kept it static to make things simpler but in reality, you’ll probably want to retrieve it programmatically (the version number).

- docker login ${CI_REGISTRY} -u gitlab-ci-token -p ${CI_BUILD_TOKEN}

Then we log in to our Gitlab registry, the environment variables $CI_REGISTRY and CI_BUILD_TOKEN are predefined Gitlab variables that are injected into our environment. You can read more about them here. Since we are pushing to our Gitlab registry we can just use the credentials defined within environment i.e. username=gitlab-ci-token and password a throwaway token.

Note: You can only do this on protected branches/tags.

- docker build -t ${CI_REGISTRY_IMAGE}:latest -t ${CI_REGISTRY_IMAGE}:${VERSION_TAG}  .
- docker push ${CI_REGISTRY_IMAGE}:latest
- docker push ${CI_REGISTRY_IMAGE}:${VERSION_TAG}

Finally, we run our normal commands to build and push our images. The place where you can find your images will depend on the project name and your username but it should follow this format

registry.gitlab.com/<username>/<project_name>/<tag>

(Optional) Push to DockerHub

- docker login -u hmajid2301 -p ${DOCKER_PASSWORD}
- export IMAGE_NAME="hmajid2301/example_project"
- docker build -t ${IMAGE_NAME}:latest -t ${IMAGE_NAME}:${VERSION_TAG}  .
- docker push ${IMAGE_NAME}:latest
- docker push ${IMAGE_NAME}:${VERSION_TAG}

We can also push our images to DockerHub, with the code shown above. We need to first login to DockerHub. Then change the name of our image <username>/<project_name>.

Appendix

• A good Stackoverflow Post
• Gitlab CI Docs
• Gitlab Example

Docker 🐳 allows us to quickly bring up a database within a Docker container, this means we don’t have to set up and configure a database on our local machine. We can simply kill the Docker container when we are done with the database. In this article, I will show you how you can create a very simple RESTful API using Flask and SQLAlchemy, which will connect to a database running in a Docker container.

NOTE: Flask server will be running locally, not in a Docker container.

In this example, I will be using Postgres but it should be easy enough to use any other relational database, such as MySQL. I will also be using flask-sqlalchemy, which is a wrapper around SQLAlchemy, it simplifies our code and means we can use less boilerplate code.

Prerequisites

• Install Docker
• (optional) Install docker-compose
• Install Python3.6
• Install the following dependencies, using pip install -r requirements.txt (or pip3 instead of pip)

Where requirements.txt is:

flask==1.0.2
flask-sqlalchemy==2.3.0
psycopg2==2.7.6.1

from flask import Flask

from .models import db
from . import config


def create_app():
    flask_app = Flask(__name__)
    flask_app.config['SQLALCHEMY_DATABASE_URI'] = config.DATABASE_CONNECTION_URI
    flask_app.config['SQLALCHEMY_TRACK_MODIFICATIONS'] = False
    flask_app.app_context().push()
    db.init_app(flask_app)
    db.create_all()
    return flask_app

The init file has one function create_app(), which funnily enough creates our Flask app with this line Flask(__name__). It then assigns a URI, from the config.py file, to the Flask app’s configuration. This URI is used to connect to the Postgres database.

One important thing about this function is that we have to use Flask contexts. Since Flask can have multiple apps we have to specify which app we are using with SQLAlchemy, hence we push the context with our newly created app. Else we would see the following error, more information here.

No application found. Either work inside a view function or push an application context.

After pushing our context, we link our db to the Flask app with the following line db.init_app(flask_app). We then create all of our tables (in the database) if they don’t already exist, using db.create_all(). The tables are created using the classes defined in models.py.

import os

user = os.environ['POSTGRES_USER']
password = os.environ['POSTGRES_PASSWORD']
host = os.environ['POSTGRES_HOST']
database = os.environ['POSTGRES_DB']
port = os.environ['POSTGRES_PORT']

DATABASE_CONNECTION_URI = f'postgresql+psycopg2://{user}:{password}@{host}:{port}/{database}'

This module’s only job at the moment is to generate this URI, but could easily be extended to add extra configuration variables if required.

DATABASE_CONNECTION_URI = f'postgresql+psycopg2://{user}:{password}@{host}:{port}/{database}'

NOTE: F-strings used for formatting strings (as shown above) can only be used with Python3.6.

These are examples of the variables that need to get passed as environment variables to the Flask app.

POSTGRES_USER=test
POSTGRES_PASSWORD=password
POSTGRES_HOST=localhost
POSTGRES_PORT=5432
POSTGRES_DB=example

NOTE: If you’re running the Flask app in a Docker container you will need to change the variable POSTGRES_HOST=postgres, (from localhost) where postgres is the Docker container name we are connecting to.

WARNING: Make sure these are the same values passed to the Flask app and the Postgres database.

import flask_sqlalchemy

db = flask_sqlalchemy.SQLAlchemy()


class Cats(db.Model):
    __tablename__ = 'cats'
    id = db.Column(db.Integer, primary_key=True)
    name = db.Column(db.String(100))
    price = db.Column(db.Integer)
    breed = db.Column(db.String(100))

This module defines our classes which then become tables within our database. For example, the class Cats (cats) is the table name and each attribute becomes a column in that table. So the cats table with have four columns id, name, price and breed.

The db variable is imported from here by the __init__.py file, that’s how the db.create_all() function knows which classes/tables to create in the database.

import json

from flask import request

from . import create_app, database
from .models import Cats

app = create_app()


@app.route('/', methods=['GET'])
def fetch():
    cats = database.get_all(Cats)
    all_cats = []
    for cat in cats:
        new_cat = {
            "id": cat.id,
            "name": cat.name,
            "price": cat.price,
            "breed": cat.breed
        }

        all_cats.append(new_cat)
    return json.dumps(all_cats), 200


@app.route('/add', methods=['POST'])
def add():
    data = request.get_json()
    name = data['name']
    price = data['price']
    breed = data['breed']

    database.add_instance(Cats, name=name, price=price, breed=breed)
    return json.dumps("Added"), 200


@app.route('/remove/<cat_id>', methods=['DELETE'])
def remove(cat_id):
    database.delete_instance(Cats, id=cat_id)
    return json.dumps("Deleted"), 200


@app.route('/edit/<cat_id>', methods=['PATCH'])
def edit(cat_id):
    data = request.get_json()
    new_price = data['price']
    database.edit_instance(Cats, id=cat_id, price=new_price)
    return json.dumps("Edited"), 200

This is a simple Flask file, which creates our app by calling create_app() function from __init__.py module. Then it defines four functions for our four routes for the “RESTful” API:

• GET: Get information about all the cats
• POST: Add a new cat
• DELETE: Remove a cat
• PATCH: Edit a cat’s price

database.py

from .models import db


def get_all(model):
    data = model.query.all()
    return data


def add_instance(model, **kwargs):
    instance = model(**kwargs)
    db.session.add(instance)
    commit_changes()


def delete_instance(model, id):
    model.query.filter_by(id=id).delete()
    commit_changes()


def edit_instance(model, id, **kwargs):
    instance = model.query.filter_by(id=id).all()[0]
    for attr, new_value in kwargs.items():
        setattr(instance, attr, new_value)
    commit_changes()


def commit_changes():
    db.session.commit()

This module is created so we can abstract away how we interact with the database. We simply use the functions in this module to interact with the database. This means it’s easier to change the library we use to interact with the database. It also means that if for some reason we need to change how we interact with the database. We only have to change it in a single module (this one).

The app.py module calls functions in this file to interact with database.

• GET - get_all()
• POST - add_instance()
• DELETE - delete_instance()
• PUT - edit_instance()

Some functions use this special keyword called **kwargs, kwargs (keyword arguments) could be called anything but it’s best practice to call it kwargs. This allows the caller of the function to pass in an arbitrary number of keyword arguments.

Let’s take a look at the add_instance() function as an example. The function is called in app.py like so database.add_instance(Cats, name=name, price=price, breed=breed) the model=Cats and kwargs is the rest of the arguments which are passed onto the cats model so we can add our cat object to the database.

NOTE: The kwargs just stores the arguments as a dictionary, the ** operator unpacks our dictionary and passes them as keyword arguments.

Docker Compose

version: '3.5'
services:
  database:
    container_name: postgres
    image: postgres:latest
    env_file: database.conf
    ports:
      - 5432:5432  
    volumes:
      - db_volume:/var/lib/postgresql

volumes:
  db_volume:

For development, I like to use docker-compose. In docker compose we can specify Docker containers using YAML. It can help to simplify the commands we need to type when trying to build/run multiple Docker containers. In this example, we only define a single Docker container.

Taking a look at the file:

First, we define our version number version: '3.5', it is recommended by Docker that you use at least version 3. You can find more information here.

Then we give our a service name, in this case, database. I like to name my services with what they are used for generic names such as web server, database or message broker. This means I can change the underlying technology without changing the service name.

After this we name our container postgres, this is the name of the Docker container. It can be used to interact with the container (to kill it or exec onto it) without using an ID.

We use the official Postgres image on Docker Hub, we pull the image that is tagged with latest.

This image requires us to use some variables to set it up such as username, password and database. We pass these in the form of a file to make things a bit simpler (the same `database.conf as defined above).

We then map the host port 5432 to the guest Docker container port 5432, this is the port that Postgres listens on. You could change the host port if you wanted to something else like 9000 say, this means all traffic on the host on port 9000 will be sent to the Postgres container on port 5432. We would also need to update the environment variable the Flask app is using.

Finally, we mount a volume so that our data is persistent, without this when the database Docker container is killed you would lose all of your data. By mounting db_volume even when you kill the container, like when you want to update the Postgres image, your data will persist.

Running our application

To build and run our Docker container with docker-compose:

docker-compose up --build -d

The equivalent commands using just normal Docker would be

docker volume create --name db_volume
docker run -d --name postgres -p 5432:5432 \
           --env-file docker/database.conf \
           -v db_volume:/var/lib/postgresql postgres:latest

To start our Flask app

docker-compose up --build

# In a new terminal
virtualenv .venv
source .venv/bin/activate
pip install -r requirements.txt
# To load env variables
export $(xargs < database.conf)
export FLASK_APP=src/example/app.py
flask run
# Running on http://127.0.0.1:5000

You can send HTTP requests to your Flask server on 127.0.0.1:5000, you can either use a REST client like Postman or Insomnia. You can also use cURL on the cli.

curl -XPOST -H "Content-type: application/json" -d \
'{"name": "catty mcCatFace", "price": 5000, "breed": "bengal"}' \
'127.0.0.1:5000/add'

Appendix

• Example source code
• Postman
• Insomnia

• Docker Image: Is a file used to execute code in a Docker container, built from a set of instructions.
• Docker Container: Is a Docker image that is being executed or run.

Docker 🐳 is a relatively new and exciting technology, Docker is a containerisation tool. The main benefits of using Docker is that you can use the same environment for development, testing and production. Since Docker environments are consistent this means if the application works in the testing environment it will also work in production.

Another big advantage of Docker is that I don’t need to download all the dependencies on my own machine directly. To build an entire application and run it all I need is a Dockerfile so if I’m the go a lot and using lots of different machines, I can easily set up my own development environment simply by using Docker. All Docker does it execute a set of instructions so since the instructions are the same, the environment Docker will create (Docker container) will also be the same.

In this tutorial, I will show you how to set up a Python 🐍 application using multiple Docker containers. In theory, you could have one big Docker container that has Nginx, Flask and Postgres but I prefer to split the application up. For example into its core components, web server (Nginx), application (Flask) and database (Postgres). The main advantage of this is that it makes it easier to replace components of the application and also makes it easier to detect errors as you can see which container is cauing the error.

Note: Everything in this tutorial has been tested on Ubuntu Linux.

Prerequisites

• Install Docker
• (optional) Install docker-compose

Nginx

The first Docker container called Nginx will be the main gateway into our application it will be used as a proxy server. It will receive HTTP requests and forward them onto our Python application.

FROM nginx:latest

RUN rm /etc/nginx/conf.d/default.conf
COPY docker/nginx/example.conf /etc/nginx/conf.d/

This is a very simple dockerfile that takes uses the latest Nginx docker image. It then removes the default configuration and adds our configuration.

server {
  listen 80;
  server_name _;

  location / {
    try_files $uri @app;
  }

  location @app {
    include /etc/nginx/uwsgi_params;
    uwsgi_pass flask:8080;
  }
}

This is a simple Nginx configuration file which listens for traffic on port 80 (HTTP). It then passes on the data to uWSGI (hence location /). We then pass the HTTP request to another Docker container called flask on port 8080. This configuration cannot be used for https. Warning Only use https to send secure data. The reason we give it the container name flask rather than localhost is because this is how Docker networking works by default (bridge networking) to allow container to container communication. We do a something thing to allow when connecting Flask container to the Postgres container.

Flask

NOTE: Link to the Python app source code in source_code/src/example/ this is the code that is turned into the tar in the dist folder.

The second Docker container will contain our Python application running on a uWSGI server. The uWSGI server is a web application server based on the WSGI specification will allow Python to communicate with web servers. In this case, it essentially acts as middleware between Nginx and Flask translating requests between them. So essentially uWSGI receives an HTTP request from Nginx and translates into something Flask can understand. This container stores all the core Python code required for this simple API.

# Base Image
FROM python:3.6-alpine as BASE

RUN apk add --no-cache linux-headers g++ postgresql-dev gcc build-base linux-headers ca-certificates python3-dev libffi-dev libressl-dev libxslt-dev
RUN pip wheel --wheel-dir=/root/wheels psycopg2
RUN pip wheel --wheel-dir=/root/wheels cryptography

# Actual Image
FROM python:3.6-alpine as RELEASE

EXPOSE 8080
WORKDIR /app 

ENV POSTGRES_USER="" POSTGRES_PASSWORD="" POSTGRES_HOST=postgres POSTGRES_PORT=5432 POSTGRES_DB=""

COPY dist/ ./dist/
COPY docker/flask/uwsgi.ini ./
COPY --from=BASE /root/wheels /root/wheels

RUN apk add --no-cache build-base linux-headers postgresql-dev pcre-dev libpq uwsgi-python3 && \
    pip install --no-index --find-links=/root/wheels /root/wheels/* && \
    pip install dist/*

CMD ["uwsgi", "--ini", "/app/uwsgi.ini"]

This dockerfile uses a relatively new Docker feature called multi-stage builds. Here we use a base image (Python3.6) to generate some Python wheel files. These wheel files require specific Linux dependencies that we don’t actually need in our main Docker container. Then we define our actual image and copy over the wheel files that we need for our application. This is done to help reduce the size of our Docker image file, we want to try to make the image as possible (as much as it makes sense). At the end of the dockerfile, the BASE image is destroyed.

So our actual Docker image is a bit more interesting. It does the following;

• It exposes port 8080, this actually doesn’t do anything but is simply for documentation purposes
• It then creates a default directory /app/
• We define some environment variables that are required by this container (all used to connect to Postgres). Please Note in a production environment you don’t want to expose passwords and username as environment variables on your docker containers, instead, you should use a secrets stores such as HashiCorp Vault. These variables will be defined when we run the container
• It copies the dist folder which has our Python package as a tar file. You can generate this file if you have a setup.py file and run python setup.py sdist in the same folder as your setup.py
• It copies the uwsgi.ini used to configure the uWSGI server
• It copies all the wheels folder from the BASE image hence the --from=BASE
• Then we install the wheels and our everything in the dist folder, which our Python code as a tar
• Finally when the Docker image will be run it will execute uwsgi --ini /app/uwsgi.ini. Using the uwsgi.ini file we copied into the image

In theory, you could simply copy and install the requirements.txt and copy all the source code to the /app folder. However, I prefer to generate and install the actual Python package I think it’s cleaner and you only have to copy a single tar file. However, this does require you to run the command to generate the dist folder before you try to build the Docker image.

Note: The environment variables POSTGRES_ should be the same values as defined in database.conf.

[uwsgi]
socket = :8080
module = example.wsgi:app
master = 1
processes = 4
plugin = python

This is the configuration file used by the uWSGI server. This is where we define which port uWSGI listens for traffic on in this cases it’s 8080. Note that since we’ve defined socket you cannot access the uWSGI server directly you need a web server in front of it, if you wanted to use just uWSGI you would change this option to http. The other import option is the module, we point it to our installed module example then the wsgi module and app variable. Hence the module=example.wsgi:app. In this example the wsgi.py module calls create_app() function which creates the Flask app.

Postgres

The Postgres image is simpler the latest Postgres image from Docker hub, then we pass some environment variables to it to configure it.

POSTGRES_USER=test
POSTGRES_PASSWORD=password
POSTGRES_HOST=postgres
POSTGRES_PORT=5432
POSTGRES_DB=example

The environment variables passed look something like this. NOTE You don’t need to pass the port or the host to Postgres Docker container. These are used by the Flask container.

Docker Compose

So we’ve defined our dockerfile and configuration files used by those dockerfiles but how do we actually use Docker. One way we can use docker is to define it using docker-compose. Here we define a set of services and Docker will automatically run and build those services and handle the networking for us. I personally use docker-compose for development as it saves a lot of time running the docker build and docker run commands for each Docker image/container.

version: '3.5'

services:
  web_server:
    container_name: nginx
    build:
      context: .
      dockerfile: docker/nginx/Dockerfile
    ports:
      - 80:80
    depends_on:
      - app

  app:
    container_name: flask
    build:
      context: .
      dockerfile: docker/flask/Dockerfile
    env_file: docker/database.conf
    expose:
      - 8080
    depends_on:
      - database

  database:
    container_name: postgres
    image: postgres:latest
    env_file: docker/database.conf
    ports:
      - 5432:5432  
    volumes:
      - db_volume:/var/lib/postgresql

volumes:
  db_volume:

So at the top of the file we define the version number of docker-compose, it is recommended that users use version 3 now. Then we define our services, one service equals one Docker container. Each service is given a name, such as web_server, app and database.

web_server

This service runs our Nginx server. We call the container nginx for obvious reasons. We pass it the location of the dockerfile to build. The build context: . simply means relative to this current working directory so we when we COPY file we will copy them relative to docker-compose.yml file. The final thing we do publish our ports so all traffic on the host machine on port 80 is mapped to the Docker container also on port 80. We could use any port on our guest machine say we used 8001, then we would access the web server by going to localhost:8001. The final part specifies this container depends on the app container so app will be run before this container.

app

This is a relatively simple service, again we point it to our flask dockerfile and set build context to the current folder. Then we pass some environment variables as a file, the variables are taken from this file (same database.conf as defined above). These variables are used to allow Python to connect to the database. Finally, we expose port 8080, again this for documentation purposes so other users know this container expects traffic on port 8080. Since we need to connect to the database when we set up our app we depend on the database container being run first.

database

This service doesn’t have its own dockerfile but instead uses the official Postgres image. It then passes some environment variables as a file, the same file that gets passed to Flask container. We don’t actually need the host or port variables but it’s easier to maintain a single file in this case. We then map the host port 5432 to the guest Docker container port 5432. This is the port that Postgres listens on. Like with Nginx you can set the host port to whatever you want, but make sure you change this in database.conf and update POSTGRES_PORT variable. Finally, we mount a volume so that data is persistent, without this when the database Docker container was killed you would lose all your data. By mounting db_volume even you kill the container to say update the Postgres image your data will persist.

Docker Compose Build/Run

To actually run the docker-compose file (in the same folder as docker-compose.yml), you can do something like below. Where -d means it runs in the background. This will build all three services and once it has built our Docker images it will run those Docker images as Docker containers.

docker-compose up --build -d

Docker Build/Run

One important thing to note is docker-compose should not really be used in production for several reasons, such as downtime when updating your Docker containers. If your deploying to only 1 host docker-compose should be fine but in reality, most applications required high availability and zero downtime updates, in this case, you should at using a container orchestration tools such as Kuberenetes. So an alternative approach is to build and run each Docker container yourself, the equivalent commands for this docker-compose.yml file would be.

# Build our images first
docker build -f docker/nginx/Dockerfile -t nginx .
docker build -f docker/flask/Dockerfile -t flask .

# Run our containers
docker run -d --name nginx -p 80:80 nginx
docker run -d --name flask -p 8080  --env-file docker/database.conf flask
docker volume create --name db_volume
docker run -d --name postgres -p 5432:5432 \
           ---------------------------------------------------------------------------------------------------env-file docker/database.conf \
           -v db_volume:/var/lib/postgresql postgres:latest

Note: After you’ve built your own images you can push them to either a public or private Docker registry so you or other people can access them. This is a common way to access your images during your CI pipeline. In fact base images like postgres:latest are taken from the official Docker registry.

Appendix

• Example source code

Prerequisites

• Install Docker
• (optional) Install docker-compose
• Android device/emulator to test on

Docker

{
  "main": "node_modules/expo/AppEntry.js",
  "private": true,
  "scripts": {
    "android": "expo-cli start --android",
    "ios": "expo-cli start --ios",
    "start": "expo-cli start"
  },
  "dependencies": {
    "expo": "30.0.0",
    "expo-cli": "2.2.4",
    "react": "16.3.1",
    "react-native": "https://github.com/expo/react-native/archive/sdk-30.0.0.tar.gz"
  }
}

The package.json file I will be using the following example is a very barebones file, just including the minimum packages required to run Expo.

FROM node:latest
LABEL version=1.2.1

ENV ADB_IP="192.168.1.1"
ENV REACT_NATIVE_PACKAGER_HOSTNAME="192.255.255.255"

EXPOSE 19000
EXPOSE 19001

RUN apt-get update && \
    apt-get install android-tools-adb
WORKDIR /app

COPY package.json yarn.lock app.json ./
RUN yarn --network-timeout 100000
CMD adb connect $ADB_IP && \
        yarn run android

FROM node:latest

Tells us which Docker Image we are using as a base, in this case, the official node.js image. This is because it will have a lot of the dependencies we need already installed such as yarn and npm.

ENV ADB_IP="192.168.1.1"
ENV REACT_NATIVE_PACKAGER_HOSTNAME="192.255.255.255"

Sets an environment variable which can be accessed during runtime of the Docker container. Strictly speaking, these don’t need to be here because we can always inject into the Docker container at runtime, but I like to have the environment variables documented.

The ADB_IP is IP of the Android device 📱 to connect to. The REACT_NATIVE_PACKAGER_HOSTNAME environment variable is very important because it sets which IP address Expo (cli) is running on, this is the IP Address your phone will try to connect to. If this is not set correctly, you’ll get an error similar to Figure 1. You can work out the correct IP address on Linux by using the following command. The first one should host IP (192.168.27.128 on my machine).

hostname -I
192.168.27.128 192.168.130.128 172.17.0.1 172.19.0.1 172.18.0.1

The reason this environment variable needs to be set is because by default the React Native packager (which expo relies on) picks the first IP it sees on the machine, hence you can run expo on your host machine fine but when you run in a Docker container you cannot connect to it because it’s trying to use the Docker IP address (one of the ones starting with 172.xxx.xxx.xxx).

EXPOSE 19000
EXPOSE 19001

This is essentially meta data letting the user of the Docker container know that they can access data on those ports.

RUN apt-get update && \
    apt-get install android-tools-adb

Install Android Debugging Bridge (ADB), which is used to connect to an Android device and debug the application.

COPY package.json yarn.lock app.json ./
RUN yarn --network-timeout 100000

Copy some important files from host to Docker container. The package.json and yarn.lock are used to install the dependencies and app.json is required by expo as a bare minimum.

CMD adb connect $ADB_IP && \
    yarn run android
    # runs expo-cli start --android

Running Docker

This command runs when the Docker Image is first to run, every other command is used to build to the image itself. This uses an environment variable passed into the Docker container and connects to the Android device at $ADBIP. Then run the android command in _package.json. Then you can simply run the following commands to build and start your Docker container.

docker build -t expo-android .
docker run -e ADB_IP=192.168.112.101 \
            -e REACT_NATIVE_PACKAGER_HOSTNAME=192.168.1.1 \
            -p 19000:19000 \
            -p 19001:19001 \
            expo-android

• -t is used to name the image (expo-android)
• . tells Docker where the Dockerfile is (in the current directory)
• –env sets environment used by Docker container when it starts to run (REACT_NATIVE_PACKAGER_HOSTNAME andADB_IP are overwritten using these new values)
• -p publishes ports, in this example, it maps port 19000 on the host to port 19000 on the Docker container (and also 19001), as we need to access port 19000 and 19001 so that Expo (expo-cli) can connect to our Android device.

version: "3.5"

services:
  expo_android:
    container_name: expo_android
    build:
      context: .
      dockerfile: Dockerfile
    env_file: .env
    ports:
      - 19000:19000
      - 19001:19001
    volumes:
      - ${PWD}/:/app/

Since expo is being used to build mobile phone applications Docker isn’t going to be used in production. I prefer to use docker-compose to do the building and running, it means I can run one simple command and do the building and running in one step. Quick aside docker-compose is great for development, especially when you need to run multiple Docker container, but is not really built to be used in production. Look at using a container orchestration tool such as Kubernetes.

I also mount my current directory on the host machine to /app/ directory on the docker container, this is so that any files that change on my host machine will also change in the Docker container, rather than having to build the Docker container again.

docker-compose up --build -d

Environment Variables

ADB_IP="192.168.112.101"
REACT_NATIVE_PACKAGER_HOSTNAME="192.168.27.128"

An example .env file used to pass environment variables (using docker-compose) to the Docker container.

Appendix

• Example source code
• Docker explained
• GitHub issue around could not connect errors
• Genymotion emulator
• GIF overlay creator (Nyan Docker)
• React logo from here