DEV Community: Jack Kweyunga

Strengthen OpenSSH Security through Ansible and GitHub Actions

Jack Kweyunga — Fri, 20 Sep 2024 18:50:41 +0000

By the end of this article, you will be able to harden the security of a remote OpenSSH server using an Ansible GitHub action. Basic security measures will be applied to the SSH server.

Change the SSH port to a custom one
Disable root login
Set an idle timeout interval
Change the maximum login attempts
Disable password authentication
Disable X11 forwarding
Update UFW rules

Feel free to add more after. All the source code is available here: https://github.com/jackkweyunga/ssh-hardening-with-ansible-and-gh-actions

Let's get started!

Prerequisites

Basic knowledge of Ansible
Basic knowledge of GitHub Actions
A remote Ubuntu server with OpenSSH server installed

Project Structure

.
├── .github
│   └── workflows
│       ├── ssh.yml
│       └── ufw.yml
├── ssh
│   └── tasks
│       └── main.yml
├── ufw
│   └── tasks
│       └── main.yml
├── create-sudo-password-ansible-secret.sh
├── ssh.yml
└── ufw.yml

6 directories, 7 files

Ansible playbooks

The SSH ansible playbook

Let's start by creating an Ansible role. This will perform the hardening tasks for us.

ssh/tasks/main.yml

- name: Harden SSH security
  become: true
  block:
    - name: Install / Update openssh-server (Debian-based systems)
      ansible.builtin.package:
        name: openssh-server
        state: latest
      when: ansible_os_family == 'Debian'

    - name: Check SSH configuration syntax
      command: sshd -t
      register: sshd_config_check
      ignore_errors: true

    - name: Ensure SSH service is running
      ansible.builtin.service:
        name: ssh
        state: started
        enabled: yes
      when: sshd_config_check.rc != 0


    - name: Disable root login
      lineinfile:
        path: /etc/ssh/sshd_config
        regexp: '^#?PermitRootLogin'
        line: 'PermitRootLogin no'
        state: present
        backup: yes

    - name: Disable password authentication
      lineinfile:
        path: /etc/ssh/sshd_config
        regexp: '^#?PasswordAuthentication'
        line: 'PasswordAuthentication no'
        state: present
        backup: yes

    - name: Disable X11 forwarding
      lineinfile:
        path: /etc/ssh/sshd_config
        regexp: '^#?X11Forwarding'
        line: 'X11Forwarding no'
        state: present

    - name: Set idle timeout interval
      lineinfile:
        path: /etc/ssh/sshd_config
        regexp: '^#?ClientAliveInterval'
        line: 'ClientAliveInterval {{ ssh_alive_interval }}'
        state: present

    - name: Set maximum number of login attempts
      lineinfile:
        path: /etc/ssh/sshd_config
        regexp: '^#?MaxAuthTries'
        line: 'MaxAuthTries {{ ssh_max_auth_tries }}'
        state: present

    - name: Ensure UFW is installed and enabled (Debian-based systems)
      ansible.builtin.service:
        name: ufw
        state: started
      when: ansible_os_family == 'Debian'

    - name: Add firewall rule for new SSH port
      ansible.builtin.ufw:
        rule: allow
        port: '{{ ssh_new_port }}'
        proto: tcp

    - name: Enable UFW if not already enabled
      ansible.builtin.ufw:
        state: enabled

    - name: Change SSH port to {{ ssh_new_port }}
      lineinfile:
        path: /etc/ssh/sshd_config
        regexp: '^#?Port'
        line: 'Port {{ ssh_new_port }}'
        state: present

    - name: Check SSH configuration syntax
      command: sshd -t
      register: sshd_config_check_before_restart
      ignore_errors: true

    - name: Restart SSH service to apply changes
      ansible.builtin.service:
        name: ssh
        state: restarted
      when: sshd_config_check_before_restart.rc == 0

- name: Reconnect to server using new SSH port
  become: true
  local_action:
    module: wait_for
    host: "{{ inventory_hostname }}"
    port: '{{ ssh_new_port }}'
    delay: 10
    timeout: 300
    state: started

Now, let's define the actual playbook and reference the SSH role within.

ssh.yml


- name: SSH Hardening
  hosts: all
  become: yes

  vars_files:
    - secret

  vars:
    ssh_new_port: "{{ lookup('env', 'SSH_NEW_PORT') }}"
    ssh_alive_interval: "{{ lookup('env', 'SSH_ALIVE_INTERVAL') }}"
    ssh_max_auth_tries: "{{ lookup('env', 'SSH_MAX_AUTH_TRIES') }}"

  roles:
    - ssh

The UFW ansible playbook

Let's start by creating an Ansible role to configure UFW and add minimal port rules.

ufw/tasks/main.yml

---
- name: Ensure UFW is installed
  apt:
    name: ufw
    state: present

- name: Set logging
  community.general.ufw:
    logging: 'on'

- name: Limit SSH attempts
  community.general.ufw:
    rule: limit
    port: 22
    proto: tcp

- name: Limit SSH attempts
  community.general.ufw:
    rule: limit
    port: 2222
    proto: tcp

- name: Allow SSH
  ufw:
    rule: allow
    port: 22
    proto: tcp

- name: Allow SSH
  ufw:
    rule: allow
    port: 2222
    proto: tcp

- name: Allow HTTP
  ufw:
    rule: allow
    port: 80
    proto: tcp

- name: Allow HTTPS
  ufw:
    rule: allow
    port: 443
    proto: tcp

# - name: Allow custom port (e.g., 8080)
#   ufw:
#     rule: allow
#     port: 8080
#     proto: tcp

- name: Set default incoming policy to deny
  ufw:
    default: deny
    direction: incoming

- name: Set default outgoing policy to allow
  ufw:
    default: allow
    direction: outgoing

- name: Enable UFW
  ufw:
    state: enabled

And of course, the playbook.

ufw.yml

---

- name: Configure UFW Firewall on Ubuntu
  hosts: all
  become: yes

  vars_files:
    - secret

  roles:
    - ufw

Helper files

Let add a helper file which helps us create a sudo password Ansible secret for the remote server. This allows Ansible to run sudo commands in the automation without exposing the password in logs or source code.

create-sudo-password-ansible-secret.sh

#!/bin/bash

# variables
VAULT_PASSWORD=$(openssl rand -base64 12)
VAULT_PASSWORD_FILE="ansible/vault.txt"
VAULT_FILE="ansible/secret"

SUDO_PASSWORD="$1"
SUDO_PASSWORD_FILE="/tmp/sudo-password"

# sudo passord is required
if [ -z "${SUDO_PASSWORD}" ]; then
    echo "Usage: $0 <sudo-password>"
    exit 1
fi

# create vault password file
echo "${VAULT_PASSWORD}" > "${VAULT_PASSWORD_FILE}"

# create a sudo password file
echo "ansible_sudo_pass: \"${SUDO_PASSWORD}\"" > "${SUDO_PASSWORD_FILE}"

# encrypt sudo password
ansible-vault encrypt --vault-password-file "${VAULT_PASSWORD_FILE}" "${SUDO_PASSWORD_FILE}" --output "${VAULT_FILE}"

GitHub Actions

After creating the Ansible plays, let's move on to creating the GitHub workflows we’ll be running.

ssh workflow

First, there is the SSH workflow, which will run the SSH playbook when triggered.

.github/workflows/ssh.yml

name: ssh hardening

on:
  workflow_dispatch:
    inputs:
      REMOTE_USER:
        type: string
        description: 'Remote User'
        required: true
      HOME_DIR:
        type: string
        description: 'Home Directory'
        required: true
      TARGET_HOST:
        description: 'Target Host'
        required: true
      SSH_PORT:
        description: 'SSH Port'
        required: true

      SSH_NEW_PORT:
        description: 'SSH new Port'
        required: true
        default: "2222"
      SSH_ALIVE_INTERVAL:
        description: 'SSH Alive Interval'
        required: true
        default: "300"
      SSH_MAX_AUTH_TRIES:
        description: 'SSH Max Auth Tries'
        required: true
        default: "3"

jobs:
   ansible:
    runs-on: ubuntu-latest
    env:
      SSH_NEW_PORT: "${{ inputs.SSH_NEW_PORT }}"
      SSH_ALIVE_INTERVAL: "${{ inputs.SSH_ALIVE_INTERVAL }}"
      SSH_MAX_AUTH_TRIES: "${{ inputs.SSH_MAX_AUTH_TRIES }}"
    steps:
      - name: Checkout
        uses: actions/checkout@v2

      - name: Add SSH Keys
        run: |
          cat << EOF > ansible/ssh-key
          ${{ secrets.SSH_PRIVATE_KEY }}
          EOF

      - name: Update ssh private key permissions
        run: |
          chmod 400 ansible/ssh-key
      - name: Install Ansible
        run: |
          pip install ansible

      - name: Adding or Override Ansible inventory File
        run: |
          cat << EOF > ansible/inventory.ini
          [servers]
          ${{ inputs.TARGET_HOST }}
          EOF

      - name: Adding or Override Ansible Config File
        run: |
          cat << EOF > ./ansible/ansible.cfg
          [defaults]
          ansible_python_interpreter='/usr/bin/python3'
          deprecation_warnings=False
          inventory=./inventory.ini
          remote_tmp="/tmp"
          remote_user="${{ inputs.REMOTE_USER }}"
          remote_port=${{ inputs.SSH_PORT }}
          host_key_checking=False
          private_key_file = ./ssh-key
          retries=2
          EOF

      - name: Run main playbook
        run: |
          sh create-sudo-password-ansible-secret.sh "${{ secrets.SUDO_PASSWORD }}"
          ANSIBLE_CONFIG=ansible/ansible.cfg ansible-playbook ssh.yml --vault-password-file=ansible/vault.txt

ufw workflow

Next, the UFW workflow will run the UFW playbook when triggered.

.github/workflows/ufw.yml

name: minimal UFW

on:
  workflow_dispatch:
    inputs:
      REMOTE_USER:
        type: string
        description: 'Remote User'
        required: true
      HOME_DIR:
        type: string
        description: 'Home Directory'
        required: true
      TARGET_HOST:
        description: 'Target Host'
        required: true
      SSH_PORT:
        description: 'SSH Port'
        required: true

jobs:
   ansible:
    runs-on: ubuntu-latest

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

      - name: Add SSH Keys
        run: |
          cat << EOF > ansible/ssh-key
          ${{ secrets.SSH_PRIVATE_KEY }}
          EOF

      - name: Update ssh private key permissions
        run: |
          chmod 400 ansible/ssh-key
      - name: Install Ansible
        run: |
          pip install ansible

      - name: Adding or Override Ansible inventory File
        run: |
          cat << EOF > ansible/inventory.ini
          [servers]
          ${{ inputs.TARGET_HOST }}
          EOF

      - name: Adding or Override Ansible Config File
        run: |
          cat << EOF > ./ansible/ansible.cfg
          [defaults]
          ansible_python_interpreter='/usr/bin/python3'
          deprecation_warnings=False
          inventory=./inventory.ini
          remote_tmp="/tmp"
          remote_user="${{ inputs.REMOTE_USER }}"
          remote_port=${{ inputs.SSH_PORT }}
          host_key_checking=False
          private_key_file = ./ssh-key
          retries=2
          EOF

      - name: Run main playbook
        run: |
          sh create-sudo-password-ansible-secret.sh "${{ secrets.SUDO_PASSWORD }}"
          ANSIBLE_CONFIG=ansible/ansible.cfg ansible-playbook ufw.yml --vault-password-file=ansible/vault.txt

Now that that's done, let's push the repository to GitHub. I assume you have already created a remote GitHub repository for this project.

git init
git commit -m "initial commit"
git push

GitHub secrets

Navigate to Settings, then Secrets and Variables, and finally Actions in your repository. Add the following GitHub secrets:

SSH_PRIVATE_KEY: A private key whose public key is added to the authorized_keys file on the server.
SUDO_PASSWORD: The password of the remote sudo user

Operation

On GitHub, go to the Actions tab of the repository to verify that the two workflows are available.

Select the one you want to start with, click the "Run workflow" button, fill in the form, and click "Run workflow" again. Monitor the progress to debug any errors if they occur and try again.

Congratulations! You can now change the settings to harden OpenSSH servers for any other remote hosts you have.

Seeking expert guidance in Ops, DevOps, or DevSecOps? I provide customized consultancy services for personal projects, small teams, and organizations. Whether you require assistance in optimizing operations, improving your CI/CD pipelines, or implementing strong security practices, I am here to support you. Let's collaborate to elevate your projects. Contact me today | LinkedIn | GitHub

Traefik Proxy Guide: Configuring public Domain Names for Docker Containers

Jack Kweyunga — Fri, 13 Sep 2024 04:49:28 +0000

Disclaimer

This article introduces Traefik, a modern reverse proxy and load balancer for deploying micro-services. We will cover its basics, key features, configuration, and integration with Docker. By the end, you should understand how to set up and use Traefik in your projects.

The final example in this article builds on concepts discussed in my previous article: How to Automate Deployment with Ansible and GitHub Actions. In that article, I explained how to streamline your deployment process using Ansible for configuration management and GitHub Actions for continuous integration and deployment. If you haven't read it yet, I highly recommend doing so to fully grasp the advanced section of this article. Understanding the automation techniques covered there will be crucial for implementing the final example effectively.

Introduction

Traefik is a modern open-source reverse proxy and load balancer. It’s built with simplicity and flexibility in mind. Traefik excels in a containerized setup, especially with micro-services.

(Image source: Traefik Documentation)

Key features of Traefik proxy

Traefik comes with amazing features, including:

Dynamic configurations
Automatic SSL/TLS
Load balancing
Middleware support
Integration with other platforms

Configuring Traefik

Traefik configurations are written in familiar syntax i.e TOML or YAML .

Traefik gives you flexibility on the type of configuration you are comfortable with. It support the following types of configurations;

Static configuration where every or some configurations are defined in a single file; traefik.yml
Dynamic configuration where different providers are supported and used to automatically detect or create Traefik configurations.

For example, with the Docker provider, configurations are defined as labels on Docker containers and automatically detected as Traefik configurations.

Other supported providers include Swarm, Nomad, Kubernetes, Consul, and many more.

Traefik & Docker

In this article, our focus is on Traefik’s Docker provider. We are going to install traefik as a docker container and the use it to proxy a python flask application ( also a docker container ).

A Demo project

For this first demo, I’ll explain a simple setup using docker-compose. In the next demo, we will integrate with GitHub Actions and Ansible.

Here is the project structure.

traefik-demo\
|-- docker-compose.yml
|-- traefik\
|   |-- certs\
|   |-- traefik.yml

To get started, we need to define a Traefik configuration file. Here is what it should look like:

traefik.yml

global:
  checkNewVersion: true
  sendAnonymousUsage: false  # true by default

# (Optional) Log information
# ---
# log:
#  level: ERROR  # DEBUG, INFO, WARNING, ERROR, CRITICAL
#   format: common  # common, json, logfmt
#   filePath: /var/log/traefik/traefik.log

# (Optional) Accesslog
# ---
# accesslog:
  # format: common  # common, json, logfmt
  # filePath: /var/log/traefik/access.log

# (Optional) Enable API and Dashboard
# ---
api:
  dashboard: true  # true by default
  insecure: false  # Don't do this in production!

# Entry Points configuration
# ---
entryPoints:
  web:
    address: :80
    # (Optional) Redirect to HTTPS
    # ---
    http:
      redirections:
        entryPoint:
          to: websecure
          scheme: https

  websecure:
    address: :443

# Configure your CertificateResolver here...
# ---
certificatesResolvers:
  staging:
    acme:
      email: "{ EMAIL }"
      storage: /etc/traefik/certs/acme.json
      caServer: "https://acme-staging-v02.api.letsencrypt.org/directory"
      tlsChallenge: {}
      httpChallenge:
        entryPoint: web

  production:
    acme:
      email: "{ EMAIL }"
      storage: /etc/traefik/certs/acme.json
      caServer: "https://acme-v02.api.letsencrypt.org/directory"
      tlsChallenge: {}
      httpChallenge:
        entryPoint: web

providers:
  docker:
    exposedByDefault: false  # Default is true
  file:
    # watch for dynamic configuration changes
    directory: /etc/traefik
    watch: true

For automatic SSL to work, make sure to add a valid email. Replace “{ EMAIL }” with your own email address.

Let’s see how the docker compose file would look like.

docker-compose.yml

# Run traefik webserver, portainer, watchtower 

services:

  traefik:
    container_name: "traefik"
    image: "traefik:v2.5"
    ports:
      - "80:80"
      - "443:443"
      # - "59808:8080" # Uncomment this to expose the traefik dashboard
    volumes:
      - /var/run/docker.sock:/var/run/docker.sock
      - traefik-ssl-certs:/ssl-certs
      - ./traefik:/etc/traefik
    networks:
      - traefik_network
    restart: always

  api:
    image: ghcr.io/jackkweyunga/auto-deploy-flask-to-server:main
    environment:
      - FLASK_ENV=production
      - DEBUG=${DEBUG}
    expose:
      - "5000"
    network:
      - traefik_network
    labels:
      - traefik.enable=true    
      - traefik.http.routers.api.rule=Host(`mydomain.com`)
      - traefik.http.routers.api.entrypoints=websecure
      - traefik.http.services.api.loadbalancer.server.port=5000
      - traefik.http.routers.api.tls.certresolver=production
    restart: always

networks:
  traefik_network:
    external: true

volumes:
  traefik-ssl-certs:

Notice that we have defined a traefik_network in the docker-compose file as external. We need to create this network before running the file. Every other Docker container that will be proxied by Traefik must join the traefik_network.

sudo docker network create traefik_network

Notice the labels we added to the API service and that it is also part of the traefik_network. The labels define Traefik configurations. Below is a detailed explanation of each label.

traefik.enable=true

Tells Traefik to proxy this container/service.
traefik.http.routers.api.rule=Host(mydomain.com)

Tells Traefik to route all traffic from mydomain.com to this container/service. Ensure proper DNS records are set up to point the domain name to the server running Traefik.
traefik.http.routers.api.entrypoints=websecure

Tells Traefik to use a secure entry point for this container/service, as defined in the traefik.yml configuration file. This means using port 443, the secure port.
traefik.http.services.api.loadbalancer.server.port=5000

Tells Traefik to direct traffic to port 5000 of the container.
traefik.http.routers.api.tls.certresolver=production

Tells Traefik to use the production Let's Encrypt endpoints when fetching SSL certificates. This is also referenced in the traefik.yml configuration file.

NOTE: For each service, the router name must be unique from router names in other services. The same rule applies to service names. The router name is the part that comes after the dot, like traefik.http.routers.{router name}. If router names of different services are the same, proxying will fail.

When the setup runs on the server, Traefik will listen on ports 80 and 443. Any traffic on port 80 will be redirected to the secure port 443. Also, when someone visits mydomain.com, a response from the Flask application will be returned.

Add traefik to your CI/CD workflow

Referring to the article How to Automate Deployment with Ansible and GitHub Actions, where we set up our CI/CD workflow with Ansible and GitHub Actions, we will now build on that and add the Traefik proxy. This will let us assign public domain names to our services.

Follow this GitHub repository: https://github.com/jackkweyunga/auto-deploy-flask-to-server

Traefik Ansible role

First, we add a Traefik Ansible role. In this role, we define the automation needed to configure and run Traefik on a remote server. Below is the file structure, which can be added to the structure mentioned in the previous article.

--- previous ---
.github\
    workflows\
        deploy-proxy.yml
ansible\
    proxy.yml
    traefik\
        tasks\
            main.yml
        templates\
            traefik.yml.jinja2

templates/traefik.yml.jinja2

global:
  checkNewVersion: true
  sendAnonymousUsage: false  # true by default

# (Optional) Log information
# ---
# log:
#  level: ERROR  # DEBUG, INFO, WARNING, ERROR, CRITICAL
#   format: common  # common, json, logfmt
#   filePath: /var/log/traefik/traefik.log

# (Optional) Accesslog
# ---
# accesslog:
  # format: common  # common, json, logfmt
  # filePath: /var/log/traefik/access.log

# (Optional) Enable API and Dashboard
# ---
api:
  dashboard: true  # true by default
  insecure: false  # Don't do this in production!

# Entry Points configuration
# ---
entryPoints:
  web:
    address: :80
    # (Optional) Redirect to HTTPS
    # ---
    http:
      redirections:
        entryPoint:
          to: websecure
          scheme: https

  websecure:
    address: :443

# Configure your CertificateResolver here...
# ---
certificatesResolvers:
  staging:
    acme:
      email: {{ EMAIL }}
      storage: /etc/traefik/certs/acme.json
      caServer: "https://acme-staging-v02.api.letsencrypt.org/directory"
      tlsChallenge: {}
      httpChallenge:
        entryPoint: web

  production:
    acme:
      email: {{ EMAIL }}
      storage: /etc/traefik/certs/acme.json
      caServer: "https://acme-v02.api.letsencrypt.org/directory"
      tlsChallenge: {}
      httpChallenge:
        entryPoint: web

serversTransport:
  insecureSkipVerify: true

providers:
  docker:
    exposedByDefault: false  # Default is true
  file:
    # watch for dynamic configuration changes
    directory: /etc/traefik
    watch: true

This Traefik configuration template allows us to pass variables to it while saving it on the remote server. In this case, an EMAIL will be passed.

tasks/main.yml

---

- name: Preparing required files and Directories in /etc/traefik
  become: true
  block:

    - name: Create directory
      file:
        path: /etc/traefik
        state: directory

    - name: Create directory2
      file:
        path: /etc/traefik/certs
        state: directory

    - name: Copy config file
      ansible.builtin.template:
        src: templates/traefik.yml.jinja2
        dest: /etc/traefik/traefik.yaml

- name: Configuring traefik
  become: true
  block:

    - name: Create ssl-certs Volume
      community.docker.docker_volume:
        name: traefik-ssl-certs

      register: v_output
      ignore_errors: true

    - name: Debug output
      ansible.builtin.debug:
        var: v_output

    - block:
      - name: Create traefik_network
        become: true
        community.docker.docker_network:
          name: traefik_network
        register: n_output
        ignore_errors: true

      - name: Debug output
        ansible.builtin.debug:
          var: n_output

      when: v_output

    - block:

      - name: Deploy Traefik
        community.docker.docker_container:
          name: traefik
          image: "traefik:v2.10"
          ports:
            - "80:80"
            - "443:443"
            - "59808:8080"
          volumes:
            - /var/run/docker.sock:/var/run/docker.sock
            - traefik-ssl-certs:/ssl-certs
            - /etc/traefik:/etc/traefik
          networks:
            - name: "traefik_network" # required. Name of the network to operate on.
          restart_policy: always
          labels:
            com.centurylinklabs.watchtower.enable: "false"
        register: d_output
        ignore_errors: true

      - name: Debug output
        ansible.builtin.debug:
          var: d_output

      when: n_output

In this task, where the magic happens, we create the required folders, files, Docker volumes, and Docker networks (traefik_network). Then, we use Ansible’s docker_container community plugin to run Traefik on the remote server(s). If you look closely, you'll notice the similarity to the docker-compose.yml we used in the first demo.

ansible/proxy.yml

---
- hosts: webservers

  vars_files:
    - secret

  roles:
    - traefik

  vars:

    EMAIL: "{{ lookup('ansible.builtin.env', 'EMAIL') }}"

This is the main Ansible playbook we’ll run to configure Traefik. Notice how it references the Traefik role. We also read the EMAIL variable from the environment variable.

Now that the Ansible configurations are ready, let's add a GitHub workflow to run Ansible on demand with GitHub Action runners.

Add the proxy GitHub Workflow

.github/workflows/deploy-proxy.yml

name: proxy

on:
  workflow_dispatch:
    inputs:
      REMOTE_USER:
        type: string
        description: 'Remote User'
        required: true
        default: 'ubuntu' # Edit here 
      EMAIL:
        type: string
        description: 'Email for fetching certs'
        required: true
        default: '<put a valid email here>' # Edit here
      HOME_DIR:
        type: string
        description: 'Home Directory'
        required: true
        default: '/home/ubuntu' # Edit here
      TARGET_HOST:
        description: 'Target Host'
        required: true
        default: "< ip / domain >" # Edit here

jobs:
   ansible:
    runs-on: ubuntu-latest
    env:
      EMAIL: "${{ inputs.EMAIL }}"

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

      - name: Add SSH Keys
        run: |
          cat << EOF > ansible/devops-key
          ${{ secrets.SSH_DEVOPS_KEY_PRIVATE }}
          EOF

      - name: Update devops private key permissions
        run: |
          chmod 400 ansible/devops-key
      - name: Install Ansible
        run: |
          pip install ansible

      - name: Adding or Override Ansible inventory File
        run: |
          cat << EOF > ansible/inventory.ini
          [webservers]
          ${{ inputs.TARGET_HOST }}
          EOF

      - name: Adding or Override Ansible Config File
        run: |
          cat << EOF > ./ansible/ansible.cfg
          [defaults]
          ansible_python_interpreter='/usr/bin/python3'
          deprecation_warnings=False
          inventory=./inventory.ini
          remote_tmp="${{ inputs.HOME_DIR }}/.ansible/tmp"
          remote_user="${{ inputs.REMOTE_USER }}"
          host_key_checking=False
          private_key_file = ./devops-key
          retries=2
          EOF

      - name: Run main playbook
        run: |
          sh ansible/create-sudo-password-ansible-secret.sh ${{ secrets.SUDO_PASSWORD }}
          ANSIBLE_CONFIG=ansible/ansible.cfg ansible-playbook ansible/proxy.yml --vault-password-file=ansible/vault.txt

Make sure to edit the EMAIL and TARGET_HOST inputs.

We can now edit the flask-api ansible role to include traefik configurations via container labels.

Update the flask-api Ansible role

Edit ansible/flask-api/files/docker-compose.yml


volumes:
  portainer-data:

# Added networks
networks:
  traefik_network:
    external: true

services:

  portainer:
    image: portainer/portainer-ce:alpine
    container_name: portainer
    command: -H unix:///var/run/docker.sock
    expose:
      - "9000"
    volumes:
      # Connect docker socket to portainer
      - "/var/run/docker.sock:/var/run/docker.sock"
      # Persist portainer data
      - "portainer_data:/data"
    restart: always
    # Added networks
    networks:
      - traefik_network
    # Added lables
    labels:
      - "traefik.enable=true"
      - "traefik.http.routers.portainer.rule=Host(`${PORTAINER_DOMAIN}`)"
      - "traefik.http.routers.portainer.entrypoints=websecure"
      - "traefik.http.routers.portainer.tls.certresolver=production"
      - "traefik.http.routers.portainer.tls=true"
      - "traefik.http.services.portainer.loadbalancer.server.port=9000"
      - "traefik.docker.network=traefik_network"


  watchtower:
    container_name: "watchtower"
    image: "docker.io/containrrr/watchtower"
    volumes:
      - /var/run/docker.sock:/var/run/docker.sock
      # To enable docker authentication, uncomment the line below.
      # You also need to make sure you are logged in to docker in the server
      # E.g by running: sudo docker login ghcr.io
      # - /root/.docker/config.json:/config.json:ro
    restart: always
    environment:
      TZ: Africa/Dar_es_Salaam
      WATCHTOWER_LIFECYCLE_HOOKS: "1" # Enable pre/post-update scripts
    command: --debug --cleanup --interval 30

  web:
    image: ghcr.io/jackkweyunga/auto-deploy-flask-to-server:main
    environment:
      - FLASK_ENV=production
      - DEBUG=${DEBUG}
    expose:
      - "5000"
    restart: always
    # Added networks
    networks:
      - traefik_network
    # Added labels
    labels:    
      - com.centurylinklabs.watchtower.enable=true
      - traefik.enable=true    
      - traefik.http.routers.api.rule=Host(`${FLASK_API_DOMAIN}`)
      - traefik.http.routers.api.entrypoints=websecure
      - traefik.http.services.api.loadbalancer.server.port=5000
      - traefik.http.routers.api.tls.certresolver=production

    logging:
      driver: "json-file"
      options:
        max-size: "10m"
        max-file: "3"

    deploy:
      resources:
        limits:
          memory: "256m"
          cpus: "0.50"

Check all places with the comment #Added ... These sections are due to adding the Traefik proxy configurations.

Notice new variables:

FLASK_API_DOMAIN: The domain name of our Flask API, e.g., api.mydomain.com
PORTAINER_DOMAIN: The domain name of our Portainer instance, e.g., portainer.mydomain.com

As a result, we need to add these variables to ansible/deploy.yml so that we can read them from the environment in GitHub Actions runners.

Edit: ansible/deploy.yml

---
- hosts: webservers

  # an encrypted ansible secret file containing the sudo password
  vars_files:
    - secret

  roles:
    - services

  environment:
    DEBUG: "{{ lookup('ansible.builtin.env', 'DEBUG') }}"
    # Added new variables
    FLASK_API_DOMAIN: "{{ lookup('ansible.builtin.env', 'FLASK_API_DOMAIN') }}"
    PORTAINER_DOMAIN: "{{ lookup('ansible.builtin.env', 'PORTAINER_DOMAIN') }}"

Update the GitHub workflow for deployment

Finally, we edit the deploy.yml GitHub actions workflow file to include the domains

name: ansible-deploy

on:
  workflow_dispatch:
    inputs:
      REMOTE_USER:
        type: string
        description: 'Remote User'
        required: true
        default: 'ubuntu'
      HOME_DIR:
        type: string
        description: 'Home Directory'
        required: true
        default: '/home/ubuntu'
      TARGET_HOST:
        description: 'Target Host'
        required: true
        default: "example.com" # Change this to your server IP or Domain

jobs:
   ansible:
    runs-on: ubuntu-latest
    env:
      DEBUG: 0
      # Added new variables
      FLASK_API_DOMAIN: "api.mydomain.com" # Add your domain
      PORTAINER_DOMAIN: "portainer.mydomain.com" # Add your domain
    steps:

      - name: Checkout
        uses: actions/checkout@v2

      - name: Add SSH Keys
        run: |
          cat << EOF > ansible/devops-key
          ${{ secrets.SSH_DEVOPS_KEY_PRIVATE }}
          EOF

      - name: Update devops private key permissions
        run: |
          chmod 400 ansible/devops-key

      - name: Install Ansible
        run: |
          pip install ansible

      - name: Adding or Override Ansible inventory File
        run: |
          cat << EOF > ansible/inventory.ini
          [webservers]
          ${{ inputs.TARGET_HOST }}
          EOF

      - name: Adding or Override Ansible Config File
        run: |
          cat << EOF > ./ansible/ansible.cfg
          [defaults]
          ansible_python_interpreter='/usr/bin/python3'
          deprecation_warnings=False
          inventory=./inventory.ini
          remote_tmp="${{ inputs.HOME_DIR }}/.ansible/tmp"
          remote_user="${{ inputs.REMOTE_USER }}"
          host_key_checking=False
          private_key_file = ./devops-key
          retries=2
          EOF

      - name: Run deploy playbook
        run: |
          sh ansible/create-sudo-password-ansible-secret.sh ${{ secrets.SUDO_PASSWORD }}
          ANSIBLE_CONFIG=ansible/ansible.cfg ansible-playbook ansible/deploy.yml --vault-password-file=ansible/vault.txt

Make sure to add working domain, that have DNS records directing them to the target server.

Operation

To install traefik on a remote server, run the proxy GitHub workflow. After that run the deploy GitHub workflow to update your infrastructure with the newly added traefik configurations and Domain names.

After both runs are successful, you can now visit your domains securely (with SSL). If SSL has not activated yet, give it some time and monitor Traefik’s logs in Portainer in case there is an issue.

Happy Configuring !

Conclusion

If you have reached this point, it is evident that Traefik significantly enhances your workflow. The Traefik proxy is an outstanding project that integrates seamlessly with containers and can be easily incorporated into your CI/CD pipeline.

With the addition of Traefik, our setup is nearly complete. Stay tuned for my next article.

How to Automate Deployment with Ansible and GitHub Actions

Jack Kweyunga — Fri, 06 Sep 2024 13:20:40 +0000

Introduction

The world of technology is moving quickly. It's moving so fast that keeping up with everything new can be overwhelming. Therefore, the need to automate some basic tasks is inevitable.

Most development jobs today require you to deploy the application you've built (API, chat-bot, web app, etc.) either as a final stage or during development to show real-time progress to your clients. As a developer, you need to understand the deployment process. However, your main focus should be on building the product and its logic.

To save time and stay focused, you should automate the deployment process before starting development. Once this is set up, you can concentrate on building the product.

Automating deployments is part of DevOps practices that improve an organization's efficiency. It reduces lead time, allowing changes to be shipped faster (in minutes), decreases deployment time since the process is automated, and enhances the overall work experience. This is known as Continuous Delivery, meaning released code is shipped to production faster and automatically. While there's more to the terminology, today we will learn how to automate deployments.

Follow up with this GitHub repository: https://github.com/jackkweyunga/auto-deploy-flask-to-server

Tools

Most of you have already heard of or used Ansible and GitHub Actions since they are popular tools. If you haven't, don't worry—they are simple and easy to understand. By the end of this article, you'll have a good start.

ANSIBLE is a general-purpose IT automation tool created using Python with a large community around it. It is mostly used for configuration management, provisioning resources, orchestration, and more. Read more
GITHUB ACTIONS is a feature by GitHub that lets you automate workflows such as running tests, builds, and releases based on given triggers. Read more

Setup

To accomplish our goal today, we need to package our application so that it's portable and easy to run. This is where Docker comes in. You have likely heard of Docker, and maybe even used it.

For this article, we'll be building and deploying a simple Flask API.

The folder structure will be as follows:

auto-deploy-flask-to-server
    .github\
        workflows\
            docker-image.yml
            deploy.yml
    ansible\
        flask-api\
            files\
                docker-compose.yml
            tasks\
                main.yml
        deploy.yml
        create-sudo-password-ansible-secret.sh
    Dockerfile
    app.py
    requirements.txt
    docker-compose.dev.yml
    .dockerignore
    .gitignore

Application ( Flask API )

In our app.py, there is a simple Flask route that returns a JSON object with the current time.

app.py

from flask import Flask
from datetime import datetime as dt
import os

app = Flask(__name__)

@app.route("/")
def heartbeat():
    return {
        "now": dt.utcnow()
    }

if __name__ == "__main__":
    # Get the DEBUG environment variable, defaulting to True if not set.
    debug = os.environ.get("DEBUG", "True").lower() in ("true", "1")

    app.run(debug=debug)

Docker

This is what the Dockerfile should look like.

Dockerfile

# Use an official Python runtime as a parent image
FROM python:3.11-slim

# Set environment variables
ENV PYTHONDONTWRITEBYTECODE=1 \
    PYTHONUNBUFFERED=1

# Create and set the working directory
WORKDIR /app

# Copy the requirements file and install dependencies
COPY requirements.txt /app/
RUN pip install --no-cache-dir -r requirements.txt

# Copy the application code to the working directory
COPY . /app/

# Expose the port the app runs on
EXPOSE 5000

# Set the environment variable to ensure Python runs in production mode
ENV FLASK_ENV=production

# Command to run the application
CMD ["python", "app.py"]

After adding a Dockerfile, we can proceed to test our application image. Use the following docker command to build the image. Solve any occurring errors until the build is successful and the docker image runs correctly.

# Build docker image
# windows
docker build -t flask_app .

# linux
sudo docker build -t flask_app .

# Run the image
# windows
docker run -rm -p "5000:5000" flask_app

# linux
sudo docker run -rm -p "5000:5000" flask_app

Now let's add content to the docker-image.yml file in the .github/workflows directory. This will automate Docker image builds for our application. For more details about this file, please refer to this article: Upload Docker Images to GitHub: A Simple Guide with GitHub Actions. This setup will create a Docker image tagged with the commit hash and git branch, whenever we commit our code to GitHub.

.github/workflows/docker-image.yml


name: ci # Put the name of your choice

on:
  workflow_dispatch:
  push:
    branches:
      - "main" # Change to the branch name you are targeting

env:
  REGISTRY: ghcr.io
  IMAGE_NAME: ${{ github.repository }} # takes the name of the repository. 

jobs:

  build-publish-deploy:
    name: build and push docker
    runs-on: ubuntu-latest
    permissions:
      contents: write
      packages: write

    steps:

    - name: checkout
      uses: actions/checkout@v3

    - name: Set up Docker Builds
      uses: docker/setup-buildx-action@v2

    - name: Login to Container registry
      uses: docker/login-action@v2
      with:
        registry: ${{ env.REGISTRY }}
        username: ${{ github.actor }}
        password: ${{ secrets.GITHUB_TOKEN }}

    - name: Extract metadata (tags, labels) for Docker
      id: meta
      uses: docker/metadata-action@69f6fc9d46f2f8bf0d5491e4aabe0bb8c6a4678a
      with:
        images: |
          ${{ env.REGISTRY }}/${{ env.IMAGE_NAME }}
        tags: |
          type=ref,event=branch
          type=ref,event=tag
          type=ref,event=pr
          type=sha
        flavor: |
          latest=auto
          prefix=
          suffix=

    - name: Build and push hash tagged image
      uses: docker/build-push-action@v2
      with:
        context: .
        push: true
        tags: ${{ steps.meta.outputs.tags }}
        labels: ${{ steps.meta.outputs.labels }}
        cache-from: type=registry,ref=${{ env.REGISTRY }}/${{ env.IMAGE_NAME }}:latest
        cache-to: type=inline

Let us add content to the docker-compose.dev.yml file in the root directory of our project. Use this docker-compose file for testing and development if needed.

docker-compose.dev.yml

services:
  web:
    build: .
    container_name: flask_app
    environment:
      - FLASK_ENV=development
      - DEBUG=True
    ports:
      - "5000:5000"
    restart: always

    logging:
      driver: "json-file"
      options:
        max-size: "10m"
        max-file: "3"

    deploy:
      resources:
        limits:
          memory: "256m"
          cpus: "0.50"

To run the docker-compose file, run te following commands.

# windows
docker compose -f docker-compose.dev.yml build
docker compose -f docker-compose.dev.yml up -d

# linux
sudo docker compose -f docker-compose.dev.yml build
sudo doccker compose -f docker-compose.dev.yml up -d

Ansible

It's time to finish setting up Ansible in our project. We will be making changes to the contents of the Ansible folder.

ansible\
        flask-api\
            files\
                docker-compose.yml
            tasks\
                main.yml
        deploy.yml
        create-sudo-password-ansible-secret.sh

We've organized ansible in roles. flask-api is an ansible role with all the files and tasks needed to deploy our flask application. But hey, what's an ansible role ?

An ansible role provides a structured way to organize files, vars, templates and tasks related to a given automation.

You can always add another role for other automation. For example: A database role

Let's add content to the docker-compose.yml file in the ansible/flask-api/files directory, which is our production Docker Compose file. Notice that we no longer set build: .; instead, we use the remote path to the Docker image we built earlier.

You might ask yourself why this Docker Compose file look similar to the one in the root directory. Well, this is because your testing and, if possible, development environments should be as close as possible to the production environment. This helps minimize errors and bugs that might occur in production but are not detectable in testing or development. It doesn't eliminate them entirely but reduces them.

Additional services are portainer and watchtower.

Portainer is a web interface for Docker that helps you manage containers, images, stacks, and more.

Watchtower is crucial in our setup because it pulls new images after they are published with GitHub Actions. Since we are going to be using ghcr.io , in a public way, we do not need to setup any docker authentication for it. Otherwise, we had to setup docker authentication for private container registries.

ansible/flask-api/files/docker-compose.yml


volumes:
    portainer-data:

services:

  portainer:
    image: portainer/portainer-ce:alpine
    container_name: portainer
    command: -H unix:///var/run/docker.sock
    ports:
      - "9000:9000"
    volumes:
      # Connect docker socket to portainer
      - "/var/run/docker.sock:/var/run/docker.sock"
      # Persist portainer data
      - "portainer-data:/data"
    restart: always

  watchtower:
    container_name: "watchtower"
    image: "docker.io/containrrr/watchtower"
    volumes:
      - /var/run/docker.sock:/var/run/docker.sock
      # To enable docker authentication, uncomment the line below.
      # You also need to make sure you are logged in to docker in the server
      # E.g by running: sudo docker login ghcr.io
      # - /root/.docker/config.json:/config.json:ro
    restart: always
    environment:
      TZ: Africa/Dar_es_Salaam
      WATCHTOWER_LIFECYCLE_HOOKS: "1" # Enable pre/post-update scripts
    command: --debug --cleanup --interval 30

  web:
    image: ghcr.io/jackkweyunga/auto-deploy-flask-to-server:main
    environment:
      - FLASK_ENV=production
      - DEBUG=${DEBUG}
    ports:
      - "5000:5000"
    restart: always

    logging:
      driver: "json-file"
      options:
        max-size: "10m"
        max-file: "3"

    deploy:
      resources:
        limits:
          memory: "256m"
          cpus: "0.50"

Let's define our task in ansible/flask-api/tasks/main.yml. What does it do?

Creates a project directory on the remote server if it doesn't exist. In our case, it's the .flask-api folder.
Copies relevant files to the server. In our case, it's the docker-compose.yml file.
Runs the compose commands to pull and run the services.

ansible/flask-api/tasks/main.yml

# main task
- name: Deploy app
  become: true
  block:

    - name: Create a directory if it does not exist
      ansible.builtin.file:
        path: "{{ lookup('ansible.builtin.env', 'HOME_DIR') }}/{{ lookup('ansible.builtin.env', 'PROJECT_DIR') }}/.flask-app"
        state: directory

    - name: Copy compose file to server
      ansible.builtin.copy:
        src: "files/"
        dest: "{{ lookup('ansible.builtin.env', 'HOME_DIR') }}/{{ lookup('ansible.builtin.env', 'PROJECT_DIR') }}/.flask-app/"

    # Uncomment this when working with private repositories
    # Make sure the environment variables; DOCKER_TOKEN and DOCKER_USERNAME are provided
    # 
    # - name: Login to Docker via vars/main.yaml
    #  shell: "echo \"{{ lookup('ansible.builtin.env', 'DOCKER_TOKEN') }}\" | docker login ghcr.io -u {{ lookup('ansible.builtin.env', 'DOCKER_USERNAME') }} --password-stdin"

    - name: Docker Compose Up
      community.docker.docker_compose_v2:
        project_src: "{{ lookup('ansible.builtin.env', 'HOME_DIR') }}/{{ lookup('ansible.builtin.env', 'PROJECT_DIR') }}/.flask-app"
        pull: "always"
      register: output

    - name: Debug output
      ansible.builtin.debug:
        var: output

For Ansible to run automation tasks, you need to define a playbook. But what is a playbook?

A playbook in Ansible contains a list of tasks and/or roles to be executed against a list of hosts (e.g., web servers).

In our setup, we define the playbook ansible/deploy.yml . What does it do?

Provides a way to pass sudo password when running privileged sudo commands
Defines the roles to be run
Defines the remote environment variables ( We do not need for this setup )

ansible/deploy.yml

---
- hosts: webservers

  # an encrypted ansible secret file containing the sudo password
  vars_files:
    - secret

  roles:
    - services

  environment:
    DEBUG: "{{ lookup('ansible.builtin.env', 'DEBUG') }}"

To ensure that the encrypted sudo password is available ( secret ) , we need to run the script create-sudo-password-ansible-secret.sh . What does the script do ?

creates the vault password file ( vault.txt )
create the encrypted vars file ( secret ) containing the ansible_sudo_pass which will be passed when running privileged sudo commands with ansible.

ansible/create-sudo-password-ansible-secret.sh

#!/bin/bash

# variables
VAULT_PASSWORD=$(openssl rand -base64 12)
VAULT_PASSWORD_FILE="ansible/vault.txt"
VAULT_FILE="ansible/secret"

SUDO_PASSWORD="$1"
SUDO_PASSWORD_FILE="/tmp/sudo-password"

# sudo passord is required
if [ -z "${SUDO_PASSWORD}" ]; then
    echo "Usage: $0 <sudo-password>"
    exit 1
fi

# create vault password file
echo "${VAULT_PASSWORD}" > "${VAULT_PASSWORD_FILE}"

# create a sudo password file
echo "ansible_sudo_pass: ${SUDO_PASSWORD}" > "${SUDO_PASSWORD_FILE}"

# encrypt sudo password
ansible-vault encrypt --vault-password-file "${VAULT_PASSWORD_FILE}" "${SUDO_PASSWORD_FILE}" --output "${VAULT_FILE}"

That's it for Ansible. Coming up next: GitHub Actions setup.

GitHub Actions

We previously created a GitHub Actions workflow file .github/workflows/docker-image.yml that builds and publishes a Docker image for us on push events.

In this section, we are going to add another workflow, that will run the deploy.yml ansible playbook. Let's add content to the file: .github/workflows/ansible-deploy.yml

.github/workflows/ansible-deploy.yml

name: ansible-deploy

on:
  workflow_dispatch:
    inputs:
      REMOTE_USER:
        type: string
        description: 'Remote User'
        required: true
        default: 'ubuntu'
      HOME_DIR:
        type: string
        description: 'Home Directory'
        required: true
        default: '/home/ubuntu'
      TARGET_HOST:
        description: 'Target Host'
        required: true
        default: "example.com" # Change this to your server IP or Domain

jobs:
   ansible:
    runs-on: ubuntu-latest
    env:
      DEBUG: 0
    steps:

      - name: Checkout
        uses: actions/checkout@v2

      - name: Add SSH Keys
        run: |
          cat << EOF > ansible/devops-key
          ${{ secrets.SSH_DEVOPS_KEY_PRIVATE }}
          EOF

      - name: Update devops private key permissions
        run: |
          chmod 400 ansible/devops-key

      - name: Install Ansible
        run: |
          pip install ansible

      - name: Adding or Override Ansible inventory File
        run: |
          cat << EOF > ansible/inventory.ini
          [webservers]
          ${{ inputs.TARGET_HOST }}
          EOF

      - name: Adding or Override Ansible Config File
        run: |
          cat << EOF > ./ansible/ansible.cfg
          [defaults]
          ansible_python_interpreter='/usr/bin/python3'
          deprecation_warnings=False
          inventory=./inventory.ini
          remote_tmp="${{ inputs.HOME_DIR }}/.ansible/tmp"
          remote_user="${{ inputs.REMOTE_USER }}"
          host_key_checking=False
          private_key_file = ./devops-key
          retries=2
          EOF

      - name: Run deploy playbook
        run: |
          sh ansible/create-sudo-password-ansible-secret.sh ${{ secrets.SUDO_PASSWORD }}
          ANSIBLE_CONFIG=ansible/ansible.cfg ansible-playbook ansible/deploy.yml --vault-password-file=ansible/vault.txt

The workflow installs Ansible on the GitHub Ubuntu runner.
It creates the Ansible inventory file ansible/inventory.ini, filling it with the target host IP or domain.
It creates the Ansible configuration file ansible/ansible.cfg based on the GitHub Actions inputs and secrets.
It runs the script to create the sudo password Ansible secret.
It runs the Ansible playbook.

Notice areas in the YAML file where values are read from the variable secret. This refers to the GitHub Actions secrets. You can edit them by navigating to settings/secrets/actions in your GitHub repository. For this workflow, we need to add the following GitHub secrets:

SUDO_PASSWORD: The password of the remote user
SSH_DEVOPS_KEY_PRIVATE: The SSH private key with access to the remote server

Use GitHub secrets to store private information needed by a workflow. That's it for GitHub Actions. Now, let's review what we have done so far.

Operation

Now that our setup is complete, let's learn how it operates.

When you push to the main branch, a new Docker image will be published to the GitHub container registry. If the workflow fails, you need to check and fix the error until it works again.
The workflow ansible-deploy is manually triggered to configure and deploy the application to the server. This is done for the first time and whenever configurations change. There is no need to run it regularly.
Whenever a new image is published, Watchtower will automatically pull the image into the server and continuously update the containers running the image.

In this way, we have completed the set up for automated deployments to a server using ansible and GitHub actions.

Conclusion

Wow! It's been quite a journey. If you've made it this far, you've probably learned a thing or two about automated deployments with Ansible and GitHub Actions. If anything is unclear, please ask, and I'll be happy to help. I hope you enjoyed the article.

Whats next ?

One can go further and do the following to improve or scale up the process:

Add automated tests that run before an image is built and published.
Add Ansible configuration tests that run when Ansible configurations are updated.
Scale up the setup with Kubernetes and Argo CD (depending on the organization's needs and components).

Upload Docker Images to GitHub: A Simple Guide with GitHub Actions

Jack Kweyunga — Fri, 06 Sep 2024 13:09:42 +0000

We are going to create a GitHub action that, when triggered, builds and pushes our application image to the GitHub container registry, making it ready for production or testing. Triggers will be manual or on push.

Who is this for.

Docker enthusiasts
GitHub actions users
DevOps practitioners

The process.

First, create a Dockerfile for your project.

Test your Dockerfile to ensure it works and successfully builds a functional Docker image.

Create the following folder structure at the root of your application. Add a file named docker-image.yml.

my-project
    .github
        workflows
            docker-image.yml

Add the following content to the docker-image.yml file. Change the branch name if it is different from the one you are targeting.


name: ci # Put the name of your choice

on:
  workflow_dispatch:
  push:
    branches:
      - "master" # Change to the branch name you are targeting

env:
  REGISTRY: ghcr.io
  IMAGE_NAME: ${{ github.repository }} # takes the name of the repository. 

jobs:

  build-publish-deploy:
    name: build and push docker
    runs-on: ubuntu-latest
    permissions:
      contents: write
      packages: write

    steps:

    - name: checkout
      uses: actions/checkout@v3

    - name: Set up Docker Builds
      uses: docker/setup-buildx-action@v2

    - name: Login to Container registry
      uses: docker/login-action@v2
      with:
        registry: ${{ env.REGISTRY }}
        username: ${{ github.actor }}
        password: ${{ secrets.GITHUB_TOKEN }}

    - name: Extract metadata (tags, labels) for Docker
      id: meta
      uses: docker/metadata-action@69f6fc9d46f2f8bf0d5491e4aabe0bb8c6a4678a
      with:
        images: |
          ${{ env.REGISTRY }}/${{ env.IMAGE_NAME }}
        tags: |
          type=ref,event=branch
          type=ref,event=tag
          type=ref,event=pr
          type=sha
        flavor: |
          latest=auto
          prefix=
          suffix=

    - name: Build and push hash tagged image
      uses: docker/build-push-action@v2
      with:
        context: .
        push: true
        tags: ${{ steps.meta.outputs.tags }}
        labels: ${{ steps.meta.outputs.labels }}
        cache-from: type=registry,ref=${{ env.REGISTRY }}/${{ env.IMAGE_NAME }}:latest
        cache-to: type=inline

Commit your changes and push them to GitHub.

After that, visit the Actions tab in your GitHub repository to see available and running GitHub actions. GitHub actions are displayed using the name specified in the docker-image.yml file. In our case, we named our action "ci". You can name it whatever you like.

By selecting the "ci" GitHub action, you can manually trigger it at any time to build and push your application Docker images to GitHub's container registry (ghcr.io) as packages.

Why would you do this?

This process automates your Docker builds using GitHub actions. Automating builds is a key step in setting up a complete CI/CD pipeline for your development workflow. CI/CD boosts the performance of any development team by cutting deployment time, reducing lead time, lowering the change failure rate, and enhancing the overall development experience.

All the best 😎