Ubuntu Machine
This page explains how to install Semaphore Community Edition on a Linux Ubuntu machine.
Overview
If this is your first time using Semaphore we suggest trying out Semaphore Cloud to see if the platform fits your needs. You can create a free trial account without a credit card and use every feature.
The self-hosted installation is recommended for users and teams that are familiar with Semaphore.
Prerequisites
- A DNS domain
- A Linux machine running Ubuntu. Preferably Ubuntu 24.04 LTS
- At least 8 CPUs and 16 GB of RAM
- A public IP address. Firewall rules should allow SSH (22), HTTP (80) and HTTPS (443) traffic
- SSH access to the machine
- Sudo or root permissions in the machine
Step 1 - Create DNS records
Configure your DNS by creating two A records that point to the reserved IP:
-
Go to your domain provider's DNS settings
-
Create root domain A record
- Type: A
- Name:
semaphore(e.g.semaphore.example.com) - Value: the public IP address of your Linux machine
-
Create a wildcard record
- Type: A
- Name:
*.semaphore(e.g.*.semaphore.example.com) - Value: the public IP address of your Linux machine
-
Wait for DNS propagation (typically a few minutes)
You can verify the creation of the TXT record in the Online Dig Tool for:
semaphore.example.com*.semaphore.example.com
Step 2 - Install tools
Open a terminal into your Linux machine, e.g. using SSH:
ssh <user>@<public-IP-address-of-machine>
Next, run the following commands to install the required tools:
sudo apt-get update
sudo apt-get -y install certbot
Step 3 - Define your configuration
Create a folder to store the configuration and certificates:
mkdir semaphore-install
cd semaphore-install
Create a file with the following environment variables. For the rest of the guide, we'll call this file semaphore-config. Change the values as needed:
export DOMAIN="<your-domain>"
export IP_ADDRESS=<public-IP-address-of-machine>
We highly recommend installing Semaphore on a subdomain, e.g. semaphore.example.com. Installing Semaphore on your main domain is discouraged as its operation might interfere with other services running on the same domain.
For example, if your domain is example.com, consider installing Semaphore on semaphore.example.com. See the example below.
export DOMAIN="semaphore.example.com"
export IP_ADDRESS=1.2.3.4
Step 4 - Create TLS certificates
You may skip this section if you already have wildcard certificates, e.g. *.semaphore.example.com for the domain where you are installing Semaphore.
We can use certbot to create a free wildcard TLS certificate with the following command:
source semaphore-config
mkdir -p certs
certbot certonly --manual --preferred-challenges=dns \
-d "*.${DOMAIN}" \
--register-unsafely-without-email \
--work-dir certs \
--config-dir certs \
--logs-dir certs
When you are prompted to create a DNS TXT record to verify domain ownership. For example:
Please deploy a DNS TXT record under the name:
_acme-challenge.semaphore.example.com.
with the following value:
EL545Zty7vUUvIHQRSkwxXTWsirldw91enasgB5uOHs
Create the DNS TXT record before continuing the certificate generation. Follow the instructions on the terminal.
You can verify the creation of the TXT record in the Google Dig Tool. Type the challenge DNS TXT record and check if its value corresponds to the correct value.
Once done, you should get a message like this:
Successfully received certificate.
Certificate is saved at: certs/live/semaphore.example.com/fullchain.pem
Key is saved at: certs/live/semaphore.example.com/privkey.pem
This certificate expires on 2025-02-27.
These files will be updated when the certificate renews.
Check the existence of the certificate files on the following paths. You will require both files during the Semaphore installation.
- Full chain certificate:
./certs/live/$DOMAIN/fullchain.pem - Private key certificate:
./certs/live/$DOMAIN/privkey.pem
You may delete the TXT record from your domain at this point. It's no longer needed.
Step 5 - Install k3s and Helm
Still inside the remote shell in your Linux machine, install Helm with:
curl -fsSL -o get_helm.sh https://raw.githubusercontent.com/helm/helm/main/scripts/get-helm-3 && chmod 700 get_helm.sh && ./get_helm.sh
Next, install k3s:
curl -sfL https://get.k3s.io | K3S_KUBECONFIG_MODE="644" sh -
export KUBECONFIG=/etc/rancher/k3s/k3s.yaml
Step 6 - Install Semaphore
We recommend running the following sanity checks to confirm you're ready for installation. The commands should not fail and return valid values.
source semaphore-config
echo "DOMAIN=${DOMAIN}"
echo "IP_ADDRESS=${IP_ADDRESS}"
ls certs/live/${DOMAIN}/fullchain.pem certs/live/${DOMAIN}/privkey.pem
Before installing Semaphore, we need the Emissary Ingress Controller to manage the ingress resources. Install it with:
export KUBECONFIG=/etc/rancher/k3s/k3s.yaml
kubectl apply -f https://app.getambassador.io/yaml/emissary/3.9.1/emissary-crds.yaml
kubectl wait --timeout=90s --for=condition=available deployment emissary-apiext -n emissary-system
Finally, install Semaphore with Helm:
helm upgrade --install --debug semaphore oci://ghcr.io/semaphoreio/semaphore \
--version v1.0.0-rc.1 \
--timeout 20m \
--set global.domain.ip=${IP_ADDRESS} \
--set global.domain.name=${DOMAIN} \
--set ingress.enabled=true \
--set ingress.ssl.enabled=true \
--set ingress.className=traefik \
--set ingress.ssl.type=custom \
--set ingress.ssl.crt=$(cat certs/live/${DOMAIN}/fullchain.pem | base64 -w 0) \
--set ingress.ssl.key=$(cat certs/live/${DOMAIN}/privkey.pem | base64 -w 0)
Once the installation is done, you the following command should appear in the terminal:
=============================================================================================
Congratulations, Semaphore has been installed successfully!
To start using the app, go to https://id.semaphore.example.com/login
You can fetch credentials for the login by running this command:
echo "Email: $(kubectl get secret user-creds -n default -o jsonpath='{.data.email}' | base64 -d)"; echo "Password: $(kubectl get secret user-creds -n default -o jsonpath='{.data.password}' | base64 -d)"
=============================================================================================
Execute the shown command to retrieve the login credentials.
$ echo "Email: $(kubectl get secret user-creds -n default -o jsonpath='{.data.email}' | base64 -d)"; echo "Password: $(kubectl get secret user-creds -n default -o jsonpath='{.data.password}' | base64 -d)"
Email: root@example.com
Password: AhGg_2v6uHuy7hqvNmeLw0O4RqI=
API Token: nQjnaPKQvW6TqXtpTNSx
Step 7 - First login
On new installations, the system may take up a few minutes to finish all setup tasks. If you cannot login right away, wait a few minutes and try again.
Open a browser and navigate to the domain to id.<your-domain>/login. For example: id.example.com/login
Fill in the username and password obtained at the end of step 7.
Once logged in, select the Semaphore organization to continue.
You should be greeted with the onboarding guide.
Post-installation tasks
Once you have Semaphore up and running, check out the following pages to finish setting up:
- Connect with GitHub: connect your instance with GitHub to access your repositories
- Guided tour: complete the guided tour to get familiarized with Semaphore Community Edition
- Invite users: invite users to your instance so they can start working on projects
- Add self-hosted agents: add more machines to scale up the capacity of your CI/CD platform
How to Uninstall Semaphore
If you want to completely uninstall Semaphore, follow these steps.
If you uninstall Semaphore you will lose access to all your projects, workflows and logs. You cannot undo this action.
First, connect to your server and uninstall Semaphore with the following command:
ssh <user>@<public-IP-address-of-machine>
export KUBECONFIG=/etc/rancher/k3s/k3s.yaml
helm uninstall semaphore
Delete the persistent volume claims:
kubectl delete pvc \
minio-artifacts-storage-minio-artifacts-0 \
minio-cache-storage-minio-cache-0 \
minio-logs-storage-minio-logs-0 \
postgres-storage-postgres-0 \
rabbitmq-storage-rabbitmq-0 \
redis-data-redis-0