Deploy Netos Semaphore

Deploy Semaphore & Netos Projects
Sync Semaphore Repository Updates from Netos
Deploying NGINX & Certificates

Deploy Semaphore & Netos Projects

Introduction

This guide details how to install Ansible Semaphore and automatically import all of the projects referenced in Netos NetOps. For example, to be able to Install NetBox, run through this process first.

1. Size Your Server

To run Semaphore and NetBox we'd suggest a server with a minimum of 4 x vCPU and 6GB of RAM, with SSD or NVMe disk.

In the future Netos will publish more comprehensive guidance on server sizing. Many variables need to be taken into account. For example, a static NetBox instance with 100k devices doesn't require many system resources (they are just rows in database tables after all), whereas a NetBox server with 1k devices that is getting hammered by constant API hits, many plugins, and many CPU intensive background jobs is a different story.

2. Install Ubuntu 24.04 LTS

The Netos Semaphore solution has been developed and tested only on Ubuntu 24.04 LTS (Long Term Support), which you can download from here. The ISO image will look like: ubuntu-24.04-live-server-amd64.iso.

Ubuntu release cycle | Ubuntu

Netos Semaphore will not work on earlier versions of Ubuntu.

3. Install Semaphore

Run Installation Script

On a fresh install of Ubuntu 24.04 LTS with internet access, paste this script.

sudo wget https://raw.githubusercontent.com/netos-networks/netos-netops/refs/heads/main/easy-deploy.sh && sudo chmod +x easy-deploy.sh && sudo ./easy-deploy.sh

Alternatively, if you want to clone the repo yourself, follow these exact steps:

sudo mkdir /netos
cd /netos
sudo git clone https://github.com/netos-networks/netos-netops
cd netos-netops
sudo chmod +x deploy.sh
clear
sudo ./deploy.sh

The /netos/ directory is central to many features, and in many cases (such as hard coded Semaphore variables) it's not easy to change, unless we start running sed on SQL dumps. Hence, please stick to the directory structure!

Installation Process

The deploy.sh script will:

Install dependencies on Ubuntu using apt
Install Ansible via pip into a venv
Run the semaphore-install Ansible playbook which will:
1. Install MySQL and provision the database
2. Install Semaphore
3. Import the Netos Semaphore projects from a SQL dump (semaphore-netos-netops.sql)
Present you with a URL to login to Semaphore to continue with the setup, e.g. https://10.1.1.1:3000

Re: step 4.3, we decided to import the Semaphore projects using a SQL backup rather than using the Semaphore UI Restore API. The Restore API doesn't support importing secret variables, which would have therefore required a significant amount of work for new users to just get a base instance up and running. You can of course (and should) change all the default passwords in a production build. Over time we'll transition to the Restore API.

Netos maintain a master/clean instance of the Semaphore project and create the semaphore-netos-netops.sql file as updates are made. If you want to add playbooks or tasks to the project, please create an issue in Netos NetOps GitHub.

4. Installation Screenshots

The following screenshots show the installation process when deploy.sh is run on the Ubuntu 24.04LTS server.

Note the URL you can connect to and to use TCP port 3000. Note that in the NGINX configuration guide, you can present this correctly using a FQDN on TCP443.

5. Connect to Semaphore

Once installed you should connect to a page like this, where you can login with the following default credentials. Check the Users, Accounts, and Tokens guide for more information about credentials and variables.

Username: admin
Password: admin

6. Delete Unwanted Projects & Tasks

You can delete unwanted projects, views, and tasks from the default Netos installation. When you pull repository updates, as outlined here, it will not change the Semaphore configuration. For example, maybe you want to delete these, if deployed:

Sync Semaphore Repository Updates from Netos

Introduction

Each Semaphore project links to an associated GitHub repository, for example:

NetOps = https://github.com/netos-networks/netos-netops
Netos NetBox = https://github.com/netos-networks/netos-netbox

When you run playbooks from within the projects, e.g. "Deploy NetBox" it is running the playbook locally, i.e. on the local filesystem. This is by design to give you control over pulling updates from GitHub, and to ensure stability in your environment. Over time more playbooks will be added and fixes made.

From within each SYSTEM view of each Semaphore project is a task named something like "Git Pull Project_Name Repo". Run this to pull the latest updates for that Semaphore project.

$image.png$

The local directory structure on the server looks like this:

NetOps = /netos/netos-netops
NetBox = /netos/netos-netbox
Netos Pod = /netos/netos-pod
Netos Airflow = /netos/netos-airflow

Don't edit or make changes to the repository directories as they will be force replaced each time you pull the repo.

The repository directories are excluded from the Semaphore backup job in the NetOps project.

Deploying NGINX & Certificates

Introduction

We have packaged pre-configured NGINX configurations for all applications that can be deployed through Semaphore, e.g. Semaphore, NetBox, Airflow, Elastic, and so on. Within each Netos defined project in Semaphore, there will be a "SYSTEM" tab which is where you deploy NGINX and certificate settings.

Configuration

NGINX

You can find the nginx.conf and {{ app_name }}.conf files in the nginx-* roles in the Ansible playbooks in the Netos GitHub repositories.

We suggest using our templates because each application has different requirements, for example, Semaphore requires WSS configurations for HTMLX, and NetBox requires /static/ to be correctly mounted. We have also configured backend keep-alives from NGINX to NetBox.

Custom vs. Self-Signed Certificates

In a lab environment a self-signed cert is ok (it'll give you a security warning when connecting via the browser). In each Semaphore project you'll see tasks like these which will provision the NGINX configuration and certificates.

Setup the Semaphore Environment

The variables are as follows. At a minimum we suggest setting the domain and hostname in ALL projects before deploying any applications, i.e. this example is for Netos NetOps, but you should do the same in Netos NetBox, etc.

DOMAIN = e.g. netos.io (don't put dots or asterisk at the start)
SEMAPHORE_HOSTNAME = e.g. server01-semaphore
CERT_DIR = This is where the certs will be stored. We suggest leaving everything in /netos/ as we have defined.
ORG_NAME = e.g. Netos Networks Ltd
CERT_CONTENT = the key chain for your private cert
PRIVATE_CERT_CONTENT = the private cert (see example below)

The hostname must be unique for each project, e.g. server01-ansible.netos.dev and server-01-netbox.netos.dev are permitted, however server-01.netos.dev for both Semaphore and NetBox would result in a validation check failure when running the playbook. This is because NGINX cannot have multiples sites with the same name bound to the same port, e.g. TCP/443.

If you want to add your own cert (or wildcard cert), e.g. signed for server-01-ansible.yourcompany.com, then you would paste something like this into the PRIVATE_CERT_CONTENT, and the longer key chain one in CERT_CONTENT.

Deploy the Certificates

In our case we have copied a wildcard full-chain cert and private key for *.core.netos.io into the environments in Semaphore.

After the playbook has deployed NGINX and the certs, you can change the domain in the URL and refresh the page.

Note that we configured DNS in advance of deploy NGINX and the certs. If you are running a local lab, you could set the hosts file on your workstation to point to the respective services. For example, like this:

10.1.1.1    uk-lab-nb05-semaphore.core.netos.io
10.1.1.1    uk-lab-nb05-netbox.core.netos.io

Troubleshooting

If things went wrong, you can always connect on the IP https://x.x.x.x:3000 URL to get into Semaphore, and delete the certs and NGINX site configuration file if required.

As long as you can connect to Semaphore, you can keep running the playbook to re-apply the settings, which will replace the certs and NGINX config files.

Then restart the NGINX process once the above files are deleted: sudo systemctl restart nginx.