En

Installing and Configuring SSL Certificates#

Sherpa Orchestrator supports HTTPS connections to ensure secure communication. This guide describes ways to obtain SSL certificates for use in the system.

Recommendations for Obtaining Certificates#

Important: Before obtaining certificates, consult your internal network administrator or your company's certification authority. Corporate certificates are usually provided by the IT department and ensure better integration with the existing security infrastructure.

If corporate certificates are not available, consider the following options for obtaining certificates for external domains in the sections below.

Obtaining Corporate Certificates#

If your organization has an internal certification authority (CA), contact your system administrator to obtain certificates. Provide them with the domain for the certificates and receive 2 files: the certificate (.crt) and the private key (.key). After obtaining them, install them as follows:

# Create a directory for certificates
mkdir -p ./nginx/config/certs/

# Copy the certificates (rename the files as received)
cp your_certificate.crt ./nginx/config/certs/orchestrator.crt
cp your_private.key ./nginx/config/certs/orchestrator.key
💡 Comments on Obtaining Corporate Certificates

mkdir -p ./nginx/config/certs/ - creates a directory for certificates

  • -p - creates parent directories as needed

cp your_certificate.crt ./nginx/config/certs/orchestrator.crt - copies the certificate cp your_private.key ./nginx/config/certs/orchestrator.key - copies the private key

After copying the files, configure their permissions and ownership as described in the “Setting Correct Permissions” section below.

Obtaining Trusted Certificates via Let's Encrypt#

To obtain free trusted certificates from Let's Encrypt, use Certbot on a machine with internet access.

Installing Certbot#

# On Ubuntu/Debian
sudo apt update
sudo apt install certbot

# On CentOS/RHEL
sudo yum install certbot

# On macOS (with Homebrew)
brew install certbot
💡 Comments on Installing Certbot

Ubuntu/Debian:

  • sudo apt update - updates the package list
  • sudo apt install certbot - installs Certbot

CentOS/RHEL:

  • sudo yum install certbot - installs Certbot via yum

macOS:

  • brew install certbot - installs Certbot via Homebrew

Obtaining a Certificate for a Domain#

# Obtain a certificate for your domain (replace yourdomain.com with your domain)
sudo certbot certonly --standalone -d yourdomain.com

# Or for a wildcard certificate (requires DNS challenge)
sudo certbot certonly --manual --preferred-challenges=dns -d yourdomain.com -d *.yourdomain.com
💡 Comments on Obtaining a Certificate

sudo certbot certonly --standalone -d yourdomain.com - obtains a certificate for the domain

  • certonly - obtains only certificates, without configuring the web server
  • --standalone - runs a temporary web server for HTTP-01 challenge
  • -d yourdomain.com - specifies the domain for the certificate

*sudo certbot certonly --manual --preferred-challenges=dns -d yourdomain.com -d .yourdomain.com - obtains a wildcard certificate

  • --manual - manual mode (requires DNS record)
  • --preferred-challenges=dns - uses DNS-01 challenge
  • -d *.yourdomain.com - wildcard domain

Location of Obtained Certificates#

After successfully obtaining the certificates, they will be located in the directory /etc/letsencrypt/live/yourdomain.com/:

# Check the contents of the directory with certificates
sudo ls -la /etc/letsencrypt/live/yourdomain.com/

# The output should contain:
# cert.pem (certificate)
# chain.pem (certificate chain)
# fullchain.pem (full chain)
# privkey.pem (private key)
💡 Comments on the Location of Certificates

sudo ls -la /etc/letsencrypt/live/yourdomain.com/ - shows the contents of the directory with certificates

  • /etc/letsencrypt/live/ - standard Let's Encrypt directory
  • yourdomain.com/ - subdirectory for the domain

Certificate files:

  • cert.pem - domain certificate
  • chain.pem - chain of intermediate certificates
  • fullchain.pem - full certificate with chain
  • privkey.pem - private key

Transferring Certificates to the Target Machine#

Copy the certificates to the machine where Sherpa Orchestrator will be installed:

# Create a directory for certificates on the target machine
mkdir -p ./nginx/config/certs/

# Copy the certificates (replace yourdomain.com with your domain)
sudo scp /etc/letsencrypt/live/yourdomain.com/fullchain.pem user@target-server:./nginx/config/certs/orchestrator.crt
sudo scp /etc/letsencrypt/live/yourdomain.com/privkey.pem user@target-server:./nginx/config/certs/orchestrator.key
💡 Comments on Transferring Certificates

mkdir -p ./nginx/config/certs/ - creates a directory for certificates

sudo scp /etc/letsencrypt/live/yourdomain.com/fullchain.pem user@target-server:./nginx/config/certs/orchestrator.crt - copies the certificate

  • scp - secure copy
  • fullchain.pem - full certificate with chain
  • Renamed to orchestrator.crt

sudo scp /etc/letsencrypt/live/yourdomain.com/privkey.pem user@target-server:./nginx/config/certs/orchestrator.key - copies the private key

  • privkey.pem - private key
  • Renamed to orchestrator.key

Creating Self-Signed Certificates (for Testing)#

WARNING: Self-signed certificates are not trusted and will trigger security warnings in browsers. Use this method only for testing or in isolated networks!

Creating a Self-Signed Certificate with OpenSSL#

# Create a directory for certificates
mkdir -p ./nginx/config/certs/

# Generate a private key
openssl genrsa -out ./nginx/config/certs/orchestrator.key 2048

# Create a self-signed certificate
openssl req -new -x509 -key ./nginx/config/certs/orchestrator.key -out ./nginx/config/certs/orchestrator.crt -days 365 -subj "/C=RU/ST=State/L=City/O=Organization/CN=orchestrator.sherparpa.ru"
💡 Comments on Creating Self-Signed Certificates

mkdir -p ./nginx/config/certs/ - creates a directory for certificates

openssl genrsa -out ./nginx/config/certs/orchestrator.key 2048 - generates a private key

  • genrsa - generates RSA key
  • -out file.key - output file
  • 2048 - key length in bits

openssl req -new -x509 -key keyfile.key -out certfile.crt -days 365 -subj "/C=RU/..." - creates a self-signed certificate

  • req -new -x509 - creates a new self-signed certificate
  • -key keyfile.key - uses the specified private key
  • -out certfile.crt - output certificate file
  • -days 365 - validity period (1 year)
  • -subj "/C=RU/ST=State/L=City/O=Organization/CN=domain.com" - subject information

Verifying Created Certificates#

# Check certificate information
openssl x509 -in ./nginx/config/certs/orchestrator.crt -text -noout

# Check the key and certificate match
openssl rsa -in ./nginx/config/certs/orchestrator.key -check
💡 Comments on Verifying Certificates

openssl x509 -in ./nginx/config/certs/orchestrator.crt -text -noout - shows information about the certificate

  • x509 - command for working with X.509 certificates
  • -in file.crt - input certificate file
  • -text - outputs textual information
  • -noout - does not output the encoded certificate

openssl rsa -in ./nginx/config/certs/orchestrator.key -check - checks the private key

  • rsa - command for working with RSA keys
  • -in file.key - input key file
  • -check - checks the validity of the key

Setting Correct Permissions#

After copying or creating the certificates, run the following commands on the Sherpa Orchestrator server from the directory containing the client docker-compose.yml file.

nginx runs without root privileges in the container and uses the group with GID 65532. It needs access through this group to read the private key, so set the file permissions and ownership:

sudo chmod 644 ./nginx/config/certs/orchestrator.crt
sudo chmod 640 ./nginx/config/certs/orchestrator.key
sudo chown root:65532 ./nginx/config/certs/orchestrator.crt ./nginx/config/certs/orchestrator.key
💡 Comments on Setting Permissions

sudo chmod 644 ./nginx/config/certs/orchestrator.crt - sets permissions on the certificate

  • 644 - rw-r--r-- (read for all, write only for the owner)

sudo chmod 640 ./nginx/config/certs/orchestrator.key - sets permissions on the private key

  • 640 - rw-r----- (read and write for the owner, read for the group, no access for others)

sudo chown root:65532 ./nginx/config/certs/orchestrator.crt ./nginx/config/certs/orchestrator.key - sets the owner and group of both files

  • root - file owner
  • 65532 - GID of the nginx group in the container

When the owner is root, permissions of 600 prevent nginx from reading the key. This configuration requires both permissions of 640 and group 65532.

Security Recommendations#

  1. Always use trusted certificates for production environments
  2. Regularly renew certificates before they expire
  3. Store private keys in a secure location with restricted access
  4. Monitor certificate expiration dates and set up alerts
  5. Use strong cipher suites in server configuration

After obtaining and configuring certificates by any of the described methods, return to the main installation guide for Sherpa Orchestrator.