Table of Contents

• Action for Docker Compose deployment to branch.dsv.su.se
• Quickstart
• TLDR
• Inputs
• gitea-token
• ssh-key
• compose-file
• Outputs
• url
• Compose file
• Isolation
• Traefik
• <router name> in the Traefik labels
• <host> in the Traefik labels
• Example Compose file

Action for Docker Compose deployment to branch.dsv.su.se

This action takes the current branch (that triggered the workflow) and clones it to the branch.dsv.su.se server and runs docker compose -f ${compose-file} up and gives you back a URL pointing to the deployment.

Important

Please read the section about the Compose file

Quickstart

[...]
  - uses: https://gitea.dsv.su.se/ansv7779/action-branch-deploy@v1
    with:
      gitea-token: ${{ secrets.GITEA_TOKEN }}
      ssh-key: ${{ secrets.BRANCH_DEPLOY_KEY }}
      compose-file: compose.yaml

TLDR

• Create your own network for inter-service communication
• Join Traefik network on exposed services
• Add Traefik routing labels to exposed services
• Use environment variable COMPOSE_PROJECT_NAME for unique values
• Environment variable VHOST is the fully qualified hostname for your deployment

Inputs

gitea-token

The token used to authenticate with the Gitea API. Defaults to ${{ secrets.GITEA_TOKEN }} which is populated by Gitea automatically.

ssh-key

The SSH key used to access the deploy script on branch.dsv.su.se. Defaults to ${{ secrets.BRANCH_DEPLOY_KEY }} and is populated for you in the DMC organisation.

compose-file

The Compose file to use when starting the services on branch.dsv.su.se. Defaults to compose.yaml

There are many specifics that you have to adhere to in the Compose file used that will be reacted to by branch.dsv.su.se. These specifics are related to how traffic gets routed to your services and how to isolate your services from other deployments on the same server. This is explained in the Compose file section below.

Outputs

url

The complete URL where the system can be accessed.

Compose file

Isolation

Since there are multiple deployments on the same server, it is important to isolate your services from others. There are two primary things that need to be isolated, container names and networks.

Container names are dealt with by not specifying a container_name for the services in the Compose file. This will make Docker Compose generate a name for each container based on the project name and service name and since this action takes care to set a unique project name for each deployment, the container names will be unique.

Important

Do not specify a container_name for a service in the Compose file.

When containers talk directly to each other they need to be on the same network. They are referenced using the service name as the hostname. Since it is impossible to know what every service will be named you must define your own network (separate from the Traefik network) for inter-service communication. Networks need to have unique names so generate a name based on ${COMPOSE_PROJECT_NAME}.

Important

Define your own network for inter-service communication.

Traefik

On branch.dsv.su.se there is a Traefik proxy running in the Docker environment that takes care of routing traffic to your containers based on the HTTP host used. As such, your containers should not have host port bindings.

Important

Your containers should not have host port bindings.

To get Traefik to send traffic to your container you need to inform Traefik what host you are interested in, this is done using labels.

labels:
  - "traefik.enable=true"
  - "traefik.http.routers.<router name>.rule=Host(`<host>`)"
  - "traefik.http.routers.<router name>.tls.certresolver=letsencrypt"

Note

<router name> and <host> are placeholders that should be replaced with your own values, they are both explained below in their respective sections.

Note

The example shows a Host rule which is the most common but there are many others, see the Traefik documentation for more information.

What do all these labels mean? First one tells Traefik that this container should have traffic routed to it. The rule says which traffic. tls.certresolver tells Traefik how to generate HTTPS certificate, the only valid value is letsencrypt. Unfortunately this has to be specified on each exposed service since there is no way to set a default.

There is one final thing to do which is to have your Traefik-enabled services join the traefik network. This is done using the top-level element networks. This is an existing network that your services should join, not create, so external: true is specified.

networks:
  traefik:
    name: traefik
    external: true

Not all your services should join this network, but you still want them to be able to communicate with each other. For that you should define a second network used by those services that need to communicate.

<router name> in the Traefik labels

This is a unique name that is used to identify the router in Traefik. The name has to be globally unique among all deployed systems, for all repositories and all branches. Fortunately there's an environment variable that is set up for you named ${COMPOSE_PROJECT_NAME} that is guaranteed to be unique. This is used in the example below. There is rarely, if ever, a need to deviate from this.

${COMPOSE_PROJECT_NAME} can be used for other must be unique values as well, see usage below in the example.

<host> in the Traefik labels

If a Host rule is used, the hostname can be accessed using the environment variable ${VHOST}. This is a fully qualified hostname that is unique for each deployment and can be prefixed if there's a need for multiple hosts. Do not use . in the hostname.

Example Compose file

The below Compose file consists of three services: a frontend that runs in the browser, an api that is used by the frontend and a db that is used by the api. The frontend service is exposed to the outside world, as is the api service as it is meant to be accessed by the application running in the browser. However, it uses a different host than what is used by the frontend and that hostname is passed as an environment variable to the frontend so it knows where it is. The db lives in an internal network that it shares with api and is not exposed to the outside world.

services:
  frontend:
    build:
      context: ./frontend/
    depends_on:
      - api
    networks:
      - traefik
    environment:
      - API_URL=api-${VHOST} # will be something like api-repository-branch.branch.dsv.su.se
    labels:
      - "traefik.enable=true"
      - "traefik.http.routers.${COMPOSE_PROJECT_NAME}.rule=Host(`${VHOST}`)"
      - "traefik.http.routers.${COMPOSE_PROJECT_NAME}.tls.certresolver=letsencrypt"

  api:
    build:
      context: ./api/
    depends_on:
      - db
    networks:
      - internal
      - traefik
    environment:
      - DATABASE_HOSTNAME=db # can use service name as hostname since they share the internal network
      - FRONTEND_URL=${VHOST} # if needed to configure CORS for example
    labels:
      - "traefik.enable=true"
      - "traefik.http.routers.api-${COMPOSE_PROJECT_NAME}.rule=Host(`api-${VHOST}`)"
      - "traefik.http.routers.api-${COMPOSE_PROJECT_NAME}.tls.certresolver=letsencrypt"

  db:
    image: mariadb:latest
    networks:
      - internal

networks:
  internal:
    name: ${COMPOSE_PROJECT_NAME}_internal
  traefik:
    name: traefik
    external: true