How to deploy a Dotnet Aspire app to Coolify using Github Actions

recently i posted on linkedin that i was moving some of my servers from azure to coolify instances on hetzner. some of the azure costs did not weigh up to the purpose or revenue of athe apps on the servers.

coolify is an open-source self-hosted platform to deploy containerized apps quick and with ease. It even supports pull request environments that are automatically created for each pull request.

but... while with most frameworks the deployment in coolify works out-of-the-box using docker images, i was fortunate to find a setup that did not work this way. i wanted to deploy my .net aspire app. aspire is an orchestration tool for .net, something like docker compose, but different.

aspire is a little different if you want to use it in a container environment like coolify. it does not provide docker files. it only creates a docker compose file for you. it will then build the images of your .net projects.

first i tried the above in coolify using a custom script. it should have worked, if the coolify helper image for builds and deployments would have supported the newer version of the aspire cli with its sdk. i must say that i tried this a few months ago so some things might have changed meaning it could work now.

anyway, i decided to build the images in my github actions pipeline by recommendation of a colleague. in this post i will walk you through how to do this. i also made the code available on my github here.

aspire app

if you don't have your aspire app yet, first create an one using dotnet new aspire-starter if you don't have the aspire templates available yet first use dotnet new install Aspire.ProjectTemplates

add docker compose publisher

now add the docker nuget package to your apphost project: dotnet package add Aspire.Hosting.Docker

then add this to the apphost's program.cs: builder.AddDockerComposeEnvironment('docker-compose');

create docker compose file

make sure you have the aspire cli installed. if not, install using this article: https://learn.microsoft.com/en-us/dotnet/aspire/cli/install

run aspire publish. the compose file will be generated in the aspire-output folder. make sure to remove all network related stuff from this compose file. it will introduce conflicts within coolify and traefik (it's reverse proxy).

create github actions file

Add the github actions file below to your repo:

1# Run when commits are pushed to main
2on:
3  workflow_dispatch:
4  push:
5    # Run when commits are pushed to mainline branch (main or master)
6    # Set this to the mainline branch you are using
7    branches:
8      - main
9
10jobs:
11  build:
12    runs-on: ubuntu-latest
13    permissions:
14      contents: read
15      packages: write
16    env:
17      GITHUB_REGISTRY: ghcr.io
18      IMAGE_PREFIX: ${{ github.repository_owner }}
19    steps:
20      - name: Checkout
21        uses: actions/checkout@v4
22      - name: Setup .NET
23        uses: actions/setup-dotnet@v4
24        with:
25          dotnet-version: | 
26            10.x.x
27
28      - name: Install Aspire CLI
29        run: dotnet tool install -g aspire.cli --prerelease
30
31      - name: Log in to GitHub Container Registry
32        uses: docker/login-action@v3
33        with:
34          registry: ${{ env.GITHUB_REGISTRY }}
35          username: ${{ github.actor }}
36          password: ${{ secrets.GITHUB_TOKEN }}
37
38      - name: Tag and push apiservice image
39        run: |
40          dotnet publish aspire-coolify.ApiService -t:PublishContainer -c Release
41          docker tag aspire-coolify-apiservice:latest ${{ env.GITHUB_REGISTRY }}/${{ env.IMAGE_PREFIX }}/aspire-coolify-apiservice:latest
42          docker tag aspire-coolify-apiservice:latest ${{ env.GITHUB_REGISTRY }}/${{ env.IMAGE_PREFIX }}/aspire-coolify-apiservice:${{ github.sha }}
43          docker push ${{ env.GITHUB_REGISTRY }}/${{ env.IMAGE_PREFIX }}/aspire-coolify-apiservice:latest
44          docker push ${{ env.GITHUB_REGISTRY }}/${{ env.IMAGE_PREFIX }}/aspire-coolify-apiservice:${{ github.sha }}
45
46      - name: Tag and push webfrontend image
47        run: |
48          dotnet publish aspire-coolify.Web -t:PublishContainer -c Release
49          docker tag aspire-coolify-web:latest ${{ env.GITHUB_REGISTRY }}/${{ env.IMAGE_PREFIX }}/aspire-coolify-web:latest
50          docker tag aspire-coolify-web:latest ${{ env.GITHUB_REGISTRY }}/${{ env.IMAGE_PREFIX }}/aspire-coolify-web:${{ github.sha }}
51          docker push ${{ env.GITHUB_REGISTRY }}/${{ env.IMAGE_PREFIX }}/aspire-coolify-web:latest
52          docker push ${{ env.GITHUB_REGISTRY }}/${{ env.IMAGE_PREFIX }}/aspire-coolify-web:${{ github.sha }}
53
54      - name: Deploy to Coolify
55        run: |
56          curl --request GET '${{ secrets.COOLIFY_WEBHOOK }}' --header 'Authorization: Bearer ${{ secrets.COOLIFY_TOKEN }}'
Copy

create coolify project

now before we run the github actions we need to create a new coolify project. first give it a name:

now add a new resource. use a private repository (with github app).

next:

1. select your server.
2. select your github app.
3. select the repository with the app we created.
4. 1. choose build pack -> docker compose
   2. choose the right location of the docker compose file generated by docker compose.

environment variables

now let's fill the required environment variables. i listed them below:

1APISERVICE_IMAGE=ghcr.io/{your_gh_username}/aspire-coolify-apiservice:latest
2APISERVICE_PORT=8080
3WEBFRONTEND_IMAGE=ghcr.io/{your_gh_username}/aspire-coolify-web:latest
4WEBFRONTEND_PORT=8080
Copy

add coolify webhook vars to gh actions

now that we created the project, we can configure the coolify webhook. these are needed to call the coolify webhook which will trigger a new deploy of your aspire app.

see the webhook url under your project > webhooks. the token is an api token which can be created under keys & tokens > api tokens. the permission deploy is required. now add both COOLIFY_WEBHOOK and COOLIFY_TOKEN to your github repository settings > secrets and variables > actions > repository secrets.

that's all

you can now run your github actions and it should trigger a new deployment. once the deployment is completed you should be able to open your aspire app running on coolify.

help

docker login

if you haven't done already, you should login into your gh container registry on your host server. use the article below to login to your gh docker registry inside your coolify server. you can use the terminal option inside coolify.

https://docs.github.com/en/packages/working-with-a-github-packages-registry/working-with-the-container-registry

network

if you are having issues reaching your services, make sure you remove all network stuff in the docker compose file. as mentioned above this can interfere with coolify's network management.

conclusion

i hope this guide has helped you run aspire in coolify using github actions. if you need any help feel free to create an issue here, i will try to help if possible. if you liked this post feel free to follow me on linkedin. if you need more assistance you can schedule a free discovery call with FJAN IT.