Deployment

Surfly is deployed as containerized microservices managed by Podman and systemd. The deployment uses Podman quadlet files that generate systemd services automatically.

Architecture Overview

The deployment uses Podman quadlets - container definitions that systemd automatically converts to service files using /usr/lib/systemd/system-generators/podman-system-generator --user. This provides native systemd integration with automatic startup, dependency management, and logging.

Installation Steps

1. Create Required Directories

# Main surfly directory - mounted on all containers for shared access
mkdir -p ~/surfly/certs

# Quadlet files - container definitions that generate systemd services
mkdir -p ~/.config/containers/systemd

# Systemd user service files and target definitions
mkdir -p ~/.config/systemd/user

The ~/surfly/ directory is mounted on all Podman containers, while ~/surfly/certs/ contains SSL certificates read by HAProxy for the HTTPS frontend.

2. Create Configuration File

# Set your Surfly credentials
export CLIENT_ID=your_client_id
export CLIENT_SECRET=your_client_secret

# Create environment file - loaded by all containers
echo "CLIENT_ID=$CLIENT_ID" > ~/surfly/config.env
echo "CLIENT_SECRET=$CLIENT_SECRET" >> ~/surfly/config.env

# Used in Dashboard and Studio to secure signed data. Must be kept secure.
echo "SECRET_KEY=$(openssl rand -base64 32)" >> ~/surfly/config.env

# Authorization tokens for internal dashboard API.
echo "DASHBOARD_AUTH_TOKEN=$(openssl rand -base64 32)" >> ~/surfly/config.env

# Authorization token for internal cobro API.
echo "COBRO_AUTH_TOKEN=$(openssl rand -base64 32)" >> ~/surfly/config.env

# Space separated list of the DNS servers.
echo "NGINX_DNS_RESOLVERS=1.1.1.1 8.8.8.8" >> ~/surfly/config.env

Caution

Replace your_client_id and your_client_secret with actual credentials provided by Surfly.

The config.env file is mounted as an environment file in all containers.

3. Copy SSL Certificates

# Copy certificates to directory read by HAProxy container
cp /path/to/your/certificates/* ~/surfly/certs/

# If using lego-generated certificates
cp ~/.lego/certificates/${DOMAIN}.pem ~/surfly/certs/

4. Download Installation Files

# Download Surfly license file
curl -u "$CLIENT_ID:$CLIENT_SECRET" https://build-agent.surfly.com/license -o ~/surfly/license.env

# Download Updated CA bundle
curl https://build-agent.surfly.com/public/ca_bundle.pem -o ~/surfly/ca_bundle.pem

# Download desired version of Surfly systemd services archive
VERSION="v5.1" # Update this version

# Create a temporary installation directory
mkdir ~/install/

# Download Surfly systemd services archive
curl -u "$CLIENT_ID:$CLIENT_SECRET" \
  https://build-agent.surfly.com/systemd/$VERSION.tar.gz \
  -o ~/install/systemd.tar.gz

Note

About the CA Bundle The CA bundle contains a daily updated collection of all intermediate and root certificates published by Mozilla. This bundle is required for Surfly to validate server certificates that may have incomplete certificate chains (missing intermediate certificates).

It’s recommended to periodically update the CA bundle and restart Surfly services to ensure the latest certificate validation:

# Update CA bundle
curl https://build-agent.surfly.com/public/ca_bundle.pem -o ~/surfly/ca_bundle.pem

# Restart Surfly services to load updated bundle
systemctl --user restart ss-surfly.target

5. Setup Container Registry Authentication

# Login to Surfly container registry
podman login --authfile ~/.config/containers/auth.json \
  --username "$CLIENT_ID" \
  --password "$CLIENT_SECRET" \
  images.surfly.com

If you see cgroupv2 warnings, ensure systemd user-linger is enabled and XDG_RUNTIME_DIR is set.

6. Install and Start Services

# Extract quadlet files and systemd targets
cd ~/install/
tar -xzf systemd.tar.gz

# Download all container images
./pull_images.sh

# Install quadlet files to user containers directory
cp ss-*.container ~/.config/containers/systemd/

# Install target files to user systemd directory
cp ss-*.target ~/.config/systemd/user/

# Generate systemd services from quadlets and start
systemctl --user daemon-reload
systemctl --user start ss-surfly.target
systemctl --user enable ss-surfly.target

Note

Quadlet files in ~/.config/containers/systemd/ are automatically converted to systemd service files when daemon-reload runs. You can test service generation with:

/usr/lib/systemd/system-generators/podman-system-generator --user --dryrun

7. Verify Deployment

# Check all services status
systemctl --user status ss-surfly.target

# List service dependencies
systemctl --user list-dependencies ss-surfly.target

# Verify that all services are running and healthy
curl http://127.0.0.1:8017/healthcheck/ | jq

# Example output:
[
  {
    "status": "UP",
    "service": "cmproxy",
    "took": "3ms"
  },
  {
    "status": "UP",
    "service": "proxy",
    "took": "4ms"
  },
  {
    "status": "UP",
    "service": "xresproxy",
    "took": "4ms"
  },
  {
    "status": "UP",
    "service": "haproxy",
    "took": "5ms"
  }
  // Additional services will be listed here
]

Access Application

Once all services show “active (running)” status, access the Surfly dashboard:

https://app.yourdomain.com

Replace yourdomain.com with your actual domain from the SSL certificates.

Service Management

# Check specific service logs
journalctl -f --user-unit ss-haproxy

# Restart all services
systemctl --user restart ss-surfly.target

# Stop all services
systemctl --user stop ss-surfly.target

# View quadlet-generated service files
systemctl --user cat ss-haproxy