Github Actions For Docker Containers In Self Hosted Enviroments

Github actions are a powerful tool for deploying docker containers and images. I recently wanted to try an deploy to a self-hosted server. Here are a collection of things I learned while doing so.

First, we need to install the Github action runner on our server. I recommend running the runner as a service. We can only have 1 runner per server. So if we're looking to deploy multiple repos to the same server, then we'll need to register it was a organizational runner instead of a repo runner. Also the repo needs to be a private repo in order to use an organizational runner.

In the repo, we can define our workflow as a yaml file in the folder .github/workflows in the root of the repo. This is where we will define the Github actions for the deployment. I'll be saving mine to a file called main.yml but you can name it whatever you'd like.

At the top of the yml file, we can define a name for the workflow.

name: Deploy Site To Server

Then we'll want to specify when this workflow will run. In this case, we want this workflow to run whenever there are changes pushed to the master branch.

on:
  push:
    branches:
    - master

Next, we can define jobs to run. In this case, we have just one job and we named it deploy. The runs-on property needs to be the label that we assigned to the runner. The default label is self-hosted but if you have multiple org runners it may be helpful to have unique descriptive labels for each runner.

jobs:
  deploy:
    runs-on: self-hosted

Lastly, we enter the steps we want this job to run. Usually, your first step will be to checkout the code. In the context of self-hosted runners, this checkout step, saves the repo to our server the runner is installed on, and makes it available to any additional steps in your Github action workflow.

steps:
    - name: Checkout code
    uses: actions/checkout@v2

In our scenario, after the code in our repo is checked out, we want to build a new docker image from a Dockerfile we have in the root of our repo. This will take our code and publish it as a docker image. We can name the image anything we wish. But it needs to be all lowercase with no spaces. The dot after the image name designates the Dockerfile is in the current directory.

- name: Build Docker Image
run: docker build -t myimagename .

Lastly, the final step will be to run the docker image as a container in docker. I'm using docker compose to set up my container. So we'll simply call for that.

- name: Start Docker Compose
run: docker compose up -d

Here is my full main.yml workflow file.

name: Deploy Site To Server

on:
  push:
    branches:
    - master
    
jobs:
  deploy:
    runs-on: self-hosted

    steps:
      - name: Checkout code
        uses: actions/checkout@v2
        
      - name: Build Docker Image
        run: docker build -t myimagename .

      - name: Start Docker Compose
        run: docker compose up -d

There are many other uses for Github actions. But this is a simple yet really great worflow for deploying a new docker image and spinning up a container to a self-hosted server using a Github actions workflow. It's also a great example of how a Github workflow and a Dockerfile can work together to build a image that can be quickly used in a container using docker compose.