Overview

In this blog post, I’d like to introduce you to Semaphore, an open-source Ansible management project. With Semaphore, you can automate and keep track of all your Ansible tasks in your homelab. Check out my current Ansible Playbooks in this GitHub repository.

Prerequisites

Before we dive into Semaphore, let’s ensure you meet the following prerequisites:

1. Some prior experience with Ansible and understanding of playbook formatting.
2. Ideally, some Docker experience as we’ll be using Docker-Compose for the setup.
3. Something in your homelab that you want to manage!

Getting the Docker Container Setup

Setting up the Docker container for Semaphore is straightforward. You’ll need to configure two primary files.

1. The first file is docker-compose.yml, which contains all the configuration for the container. You can find the file in this repository.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65

services:
  mysql:
    restart: unless-stopped
    ports:
      - 3306:3306
    image: mysql:8.0
    hostname: mysql-semaphore
    volumes:
      - semaphore-mysql:/var/lib/mysql
    environment:
      MYSQL_RANDOM_ROOT_PASSWORD: 'yes'
      MYSQL_DATABASE: semaphore
      MYSQL_USER: ${MYSQL_USER}
      MYSQL_PASSWORD: ${MYSQL_PASS}
    networks:
      - proxy
  semaphore:
    restart: unless-stopped
    ports:
      - 3000:3000
    image: semaphoreui/semaphore:latest
    environment:
      SEMAPHORE_DB_USER: ${MYSQL_USER}
      SEMAPHORE_DB_PASS: ${MYSQL_PASS}
      SEMAPHORE_DB_HOST: mysql-semaphore
      SEMAPHORE_DB_PORT: 3306 
      SEMAPHORE_DB_DIALECT: mysql
      SEMAPHORE_DB: semaphore
      SEMAPHORE_PLAYBOOK_PATH: /tmp/semaphore/
      SEMAPHORE_ADMIN_PASSWORD: ${SEMA_ADMIN_PASS}
      SEMAPHORE_ADMIN_NAME: ${SEMA_ADMIN_USER}
      SEMAPHORE_ADMIN_EMAIL: ${SEMA_ADMIN_EMAIL}
      SEMAPHORE_ADMIN: ${SEMA_ADMIN_USER}
      SEMAPHORE_ACCESS_KEY_ENCRYPTION: ${SEMA_ACCESS_KEY} # Generate using command 'head -c32 /dev/urandom | base64'
      #SEMAPHORE_LDAP_ACTIVATED: 'no' 
      #SEMAPHORE_LDAP_HOST: dc01.local.example.com
      #SEMAPHORE_LDAP_PORT: '636'
      #SEMAPHORE_LDAP_NEEDTLS: 'yes'
      #SEMAPHORE_LDAP_DN_BIND: 'uid=bind_user,cn=users,cn=accounts,dc=local,dc=shiftsystems,dc=net'
      #SEMAPHORE_LDAP_PASSWORD: 'ldap_bind_account_password'
      #SEMAPHORE_LDAP_DN_SEARCH: 'dc=local,dc=example,dc=com'
      #SEMAPHORE_LDAP_SEARCH_FILTER: "(\u0026(uid=%s)(memberOf=cn=ipausers,cn=groups,cn=accounts,dc=local,dc=example,dc=com))"
    depends_on:
      - mysql 
    networks:
      - proxy
    labels:
      - "traefik.enable=true"
      - "traefik.http.routers.semaphore.entrypoints=http"
      - "traefik.http.routers.semaphore.rule=Host(`${DNS_HOSTNAME_CLIENT}`)"
      - "traefik.http.middlewares.semaphore-https-redirect.redirectscheme.scheme=https"
      - "traefik.http.routers.semaphore.middlewares=semaphore-https-redirect"
      - "traefik.http.routers.semaphore-secure.entrypoints=https"
      - "traefik.http.routers.semaphore-secure.rule=Host(`${DNS_HOSTNAME_CLIENT}`)"
      - "traefik.http.routers.semaphore-secure.tls=true"
      - "traefik.http.routers.semaphore-secure.service=semaphore"
      - "traefik.http.services.semaphore.loadbalancer.server.port=3000"
      - "traefik.docker.network=proxy"

networks:
  proxy:
    external: true

volumes:
  semaphore-mysql: 

If you do not use Traefik for proxies, on the same host, go ahead and remove / comment out that part of the configuration).

2. The second file is a .env file that stores the credentials required for the Docker-Compose file. Fill in your valuable super-secret credentials in this file before spinning up the container.

1
2
3
4
5
6
7

MYSQL_PASS = 
MYSQL_USER = 
SEMA_ACCESS_KEY = 
SEMA_ADMIN_EMAIL = 
SEMA_ADMIN_PASS = 
SEMA_ADMIN_USER = 
DNS_HOSTNAME_CLIENT =

Semaphore Configuration to Get Started

Before you can start deploying Ansible tasks with Semaphore, there are a few necessary setup steps. In this tutorial, I will demonstrate the setup using my GitHub repository.

1. Set up the ‘Key Store’ profiles:
   • Once you’re logged into the Ansible Semaphore site, navigate to the ‘Key Store’ section.
   • Create three keys:
     • Key titled ‘None’ with Type ‘None’. This will be used for GitHub repository access (since it’s public).
     • Key titled ‘SSH-Key’ with Type ‘SSH Key’. This will be used for Ansible to run without sudo.
     • Key titled ‘SSH-Pass’ with Type ‘Login with password’. This will be used for non-sudo SSH Ansible tasks.
     • Key titled ‘SSH-Pass-Sudo’ with Type ‘Login with Password’. This will be used for sudo-required Ansible SSH tasks.

2. Set up the GitHub repository:
   • Use the URL of the repository.
   • Set the branch name (e.g., ‘main’).
   • If it’s a public repository, set ‘Access Key’ to None. If it’s an SSH private connection, create a key under ‘Key Store’ for that key and select it here.

3. Configure the inventory:
   • Under ‘Inventory’, create a ‘New Inventory’.
   • Provide a name and set the credentials to be used for non-sudo and sudo tasks (created earlier).
   • For the Type, select File if you have a local file containing the inventory, or use Static if you want to manage the inventory within Semaphore.

4. Create an environment file:
   • Under ‘Environment’, create a ‘New Environment’ named ‘default’.
   • Leave the extra variables section as ‘{}’.

Now that we have the initial required configuration done, let’s set up our playbooks.

Semaphore Task Templates / Playbooks

Navigate to the ‘Task Templates’ tab, and we will set up our first Task playbook.

1. Create a ‘New Template’ and provide the following parameters. Leave the Template as a ‘Task’:
   • Name: <name>
   • Description: <description>
   • Playbook Filename: <file/location/within/repo>
   • Inventory: <created-inv>
   • Repository: <created-repo>
   • Environment: <created-env>

2. Now that the playbook is created, navigate into it, and hit ‘Run’
   • You can use different features while executing the task typically foundational of Ansible such as, ‘Debug’,‘Dry Run’, ‘Diff’, etc.

From here, you’re all set! Start automating your Ansible tasks with Semaphore.

Useful Resources

Here are some useful resources for further exploration:

• Ansible Semaphore Site
• Ansible Documentation
• Docker Documentation
• My GitHub Repository