This action take 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

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.

Outputs

url

The complete URL where the system can be accessed.

Compose file

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.${COMPOSE_PROJECT_NAME}.rule=Host(`${VHOST}`)"
  - "traefik.http.routers.${COMPOSE_PROJECT_NAME}.tls.certresolver=letsencrypt"

Note

${COMPOSE_PROJECT_NAME} and ${VHOST} will be explained in the next section

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.

So what is that ${COMPOSE_PROJECT_NAME} and ${VHOST}?

The labels added to your service will define a new Traefik router and each router must have a unique name. ${COMPOSE_PROJECT_NAME} is used since it has a unique value already or there would be conflicts between common service names such as web or db.

${VHOST} is the fully qualified hostname that has been generated from your repository and branch name. Generally this is in the form <repo>-<branch>.branch.dsv.su.se but this should not be relied upon. What can be relied upon is that it is unique and it is possible to prepend values to generate other valid hosts. This can be used if you want to expose multiple services to the outside world, you can change the rule label value to something like Host(`api-${VHOST}`).

Both of these variables are available in the entire Compose file and can be sent to your services if they are needed.

Example Compose file

This 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.${COMPOSE_PROJECT_NAME}.rule=Host(`api-${VHOST}`)"
      - "traefik.http.routers.${COMPOSE_PROJECT_NAME}.tls.certresolver=letsencrypt"

  db:
    image: mariadb:latest
    networks:
      - internal

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