Skip to content

Installation

OpenSCM is designed to be lightweight with minimal dependencies, running on everything from enterprise servers to edge devices.

Prerequisites

Requirement Details
Operating System Linux, Windows 10+, FreeBSD, macOS, Arch Linux
Architecture x86_64, ARM64, ARMv7, i686, RISC-V 64, PowerPC 64 LE, s390x, LoongArch64
Privileges sudo (Linux/macOS) or Administrator (Windows)

Server Installation

The server only needs to be installed once on a central host.

1. Set up the repository:

curl -sS https://repo.openscm.io/openscm.gpg | sudo gpg --dearmor -o /usr/share/keyrings/openscm.gpg
echo "deb [signed-by=/usr/share/keyrings/openscm.gpg] https://repo.openscm.io/stable/debian stable main" | sudo tee /etc/apt/sources.list.d/openscm.list
sudo apt update

2. Install:

sudo apt install scmserver

1. Set up the repository:

sudo tee /etc/yum.repos.d/openscm.repo <<EOF
[openscm]
name=OpenSCM Stable
baseurl=https://repo.openscm.io/stable/redhat/
enabled=1
gpgcheck=1
gpgkey=https://repo.openscm.io/openscm.gpg
EOF

2. Install:

sudo yum install scmserver

1. Set up the repository:

sudo zypper addrepo https://repo.openscm.io/stable/redhat/ openscm
sudo zypper refresh

2. Install:

sudo zypper install scmserver

docker run -d \
  --name openscm \
  -p 8000:8000 \
  -v openscm_config:/etc/openscm \
  -v openscm_data:/var/lib/openscm \
  openscm/scmserver:latest

Or using Docker Compose:

version: '3.8'

services:
  openscm:
    image: openscm/scmserver:latest
    container_name: openscm
    restart: unless-stopped
    ports:
      - "8000:8000"
    volumes:
      - openscm_data:/var/lib/openscm
      - openscm_config:/etc/openscm

volumes:
  openscm_data:
  openscm_config:

Volume Backup

Always mount the /etc/openscm volume. If it is lost all registered agents will need to re-register.

Download the installer from the Downloads page and run the setup wizard. The server will be registered as a Windows Service automatically.

Access the dashboard at http://localhost:8000 after installation.

Prefer a direct download? Get the latest packages from the Downloads page.

# Debian/Ubuntu example
sudo dpkg -i scmserver_0.6.2-1_amd64.deb

Agent Installation

Install the agent on every system you want to monitor. The agent is lightweight and has no runtime dependencies.

1. Set up the repository:

curl -sS https://repo.openscm.io/openscm.gpg | sudo gpg --dearmor -o /usr/share/keyrings/openscm.gpg
echo "deb [signed-by=/usr/share/keyrings/openscm.gpg] https://repo.openscm.io/stable/debian stable main" | sudo tee /etc/apt/sources.list.d/openscm.list
sudo apt update

2. Install:

sudo apt install scmclient

1. Set up the repository:

sudo tee /etc/yum.repos.d/openscm.repo <<EOF
[openscm]
name=OpenSCM Stable
baseurl=https://repo.openscm.io/stable/redhat/
enabled=1
gpgcheck=1
gpgkey=https://repo.openscm.io/openscm.gpg
EOF

2. Install:

sudo yum install scmclient

1. Set up the repository:

sudo zypper addrepo https://repo.openscm.io/stable/redhat/ openscm
sudo zypper refresh

2. Install:

sudo zypper install scmclient

Import the OpenSCM signing key:

curl -sS https://repo.openscm.io/openscm.gpg -o /tmp/openscm.gpg
sudo pacman-key --add /tmp/openscm.gpg
sudo pacman-key --lsign-key 8A39E120F8B52DBB

Install directly from the repository:

sudo pacman -U https://repo.openscm.io/stable/arch/scmclient_0.6.2-1_x86_64.pkg.tar.zst

Available architectures: x86_64, aarch64, armv7h

Note

Arch Linux packages are available for x86_64, ARM64, and ARMv7 only. For i686, s390x, and LoongArch64 use the Debian or RPM packages.

Download the package from the Downloads page and run:

pkg add scmclient-0.6.2-freebsd-amd64.pkg

The service will start automatically after installation. Edit the config to point to your server then restart:

vi /usr/local/etc/openscm/scmclient.config
service scmclient restart

Download the package from the Downloads page and double-click to install, or from the terminal:

sudo installer -pkg scmclient_0.6.2-1_macos.pkg -target /

Edit the config to point to your server then restart:

sudo vi /usr/local/etc/openscm/scmclient.config
sudo launchctl bootout system/io.openscm.scmclient
sudo launchctl bootstrap system /Library/LaunchDaemons/io.openscm.scmclient.plist

Download the installer from the Downloads page and run the setup wizard. The agent will be registered as a Windows Service automatically.

# Debian/Ubuntu example
sudo dpkg -i scmclient_0.6.2-1_amd64.deb

Post-Installation Setup

1. Configure the Agent

Edit the config file and point it to your server:

sudo vi /etc/openscm/scmclient.config

vi /usr/local/etc/openscm/scmclient.config

sudo vi /usr/local/etc/openscm/scmclient.config

Use the registry editor or the installer wizard to set the server URL.

[server]
url = "https://your-openscm-server.com"  # Your server URL
organization = "default"                    # Organization identifier

[client]
heartbeat = "300"                        # Check-in interval in seconds
loglevel = "info"

2. Restart the Agent

sudo systemctl restart scmclient
sudo systemctl enable scmclient

service scmclient restart

sudo launchctl bootout system/io.openscm.scmclient
sudo launchctl bootstrap system /Library/LaunchDaemons/io.openscm.scmclient.plist

Restart-Service OpenSCMClient

3. Approve the Agent

Once the agent starts it will send a registration request to the server.

  1. Log in to the OpenSCM dashboard
  2. Navigate to Systems
  3. Find the pending system and click Approve

The agent is now active and will begin receiving compliance tests.

First-run Setup

On a fresh installation, the dashboard will walk you through creating your admin account on the first visit. No default credentials are set.

Verify Installation

# Check server status
sudo systemctl status scmserver

# Check agent status
sudo systemctl status scmclient

# View logs
sudo journalctl -u scmserver -f
sudo journalctl -u scmclient -f

# Check agent status
service scmclient status

# View logs
tail -f /var/log/openscm/scmclient.log

# Check agent status
sudo launchctl list | grep openscm

# View logs
tail -f /var/log/openscm/scmclient.log

# Check service status
Get-Service OpenSCMServer
Get-Service OpenSCMClient

Health Probes

The server exposes two public, unauthenticated HTTP endpoints for use by load balancers, container orchestrators, and uptime monitors. Both are whitelisted by the init-guard middleware so they answer even before the first-run setup is complete — which means a Kubernetes pod can come up cleanly during a fresh install or a rolling upgrade with mid-flight migrations.

GET /health — liveness

"Is the process alive and accepting HTTP?" Returns immediately, no database query, no work.

$ curl -i http://localhost:8000/health
HTTP/1.1 200 OK
content-type: application/json

{"status":"ok"}

Use for Kubernetes livenessProbe, the Docker image's HEALTHCHECK, and basic load-balancer pool-membership decisions. If /health ever stops returning 200, the orchestrator should restart the container.

GET /ready — readiness

"Is the server able to serve real user traffic?" Returns 200 OK only when the database pool answers a trivial query and the schema is set up. Returns 503 Service Unavailable otherwise.

Response When What it means
200 OK with {"status":"ok","schema_version":N} DB reachable, schema present Send traffic
503 with {"status":"db_unavailable"} DB pool can't SELECT 1 Hold traffic; check disk / DB lock
503 with {"status":"setup_pending"} Fresh install — /install not completed yet Hold traffic until the first-run wizard is finished

Use for Kubernetes readinessProbe so the load balancer keeps the old pod in rotation while a rolling deploy runs migrations on the new one.

Example wiring

livenessProbe:
  httpGet:
    path: /health
    port: 8000
  periodSeconds: 10
  failureThreshold: 3
readinessProbe:
  httpGet:
    path: /ready
    port: 8000
  periodSeconds: 5
  failureThreshold: 3

HEALTHCHECK --interval=30s --timeout=3s --start-period=5s --retries=3 \
  CMD curl -fsS http://localhost:8000/health || exit 1

# docker-compose.yml
services:
  scmserver:
    image: openscm/scmserver:latest
    healthcheck:
      test: ["CMD", "curl", "-fsS", "http://localhost:8000/health"]
      interval: 30s
      timeout: 3s
      retries: 3

backend openscm
    option httpchk GET /ready
    http-check expect status 200
    server srv1 10.0.0.1:8000 check inter 5s fall 3 rise 2
    server srv2 10.0.0.2:8000 check inter 5s fall 3 rise 2

Add nginx-plus / ngx_http_upstream_check_module:

upstream openscm {
    server 10.0.0.1:8000;
    server 10.0.0.2:8000;
    check interval=5000 rise=2 fall=3 timeout=3000 type=http;
    check_http_send "GET /ready HTTP/1.0\r\n\r\n";
    check_http_expect_alive http_2xx;
}

Both endpoints bypass the init-guard

Unlike every other route on the server, /health and /ready answer even before /install has been completed. This is deliberate so that a Kubernetes pod can be marked alive (and the load balancer can wait for it to become ready) during the brief window between container start and the first-run admin completing the setup wizard.