Add README.md
This commit is contained in:
parent
6fea6eff5c
commit
b4b56ec33d
73
README.md
Normal file
73
README.md
Normal file
@ -0,0 +1,73 @@
|
||||
# Action for Docker Compose deployment to branch.dsv.su.se
|
||||
|
||||
> [!IMPORTANT]
|
||||
> Please read the section [about the Compose file](#compose-file-1)
|
||||
|
||||
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 router](https://traefik.io/traefik/) 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](#so-what-is-that-compose_project_name-and-vhost)
|
||||
|
||||
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 have your Traefik-enabled services join the `traefik` network. This is done using the [top-level element `networks`](https://docs.docker.com/reference/compose-file/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](https://doc.traefik.io/traefik/routing/routers/) and each router must have a unique name. [`${COMPOSE_PROJECT_NAME}`](https://docs.docker.com/compose/how-tos/environment-variables/envvars/#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.
|
Loading…
x
Reference in New Issue
Block a user