Getting Started

1. Install orosu-server

On your target deployment machine (Debian/Ubuntu):

curl -fsSL https://packages.nerdy.pro/NerdyPro.gpg | sudo gpg --dearmor -o /usr/share/keyrings/nerdy-pro.gpg
echo "deb [signed-by=/usr/share/keyrings/nerdy-pro.gpg] https://packages.nerdy.pro/ stable main" | sudo tee /etc/apt/sources.list.d/nerdy-pro.list
sudo apt update
sudo apt install orosu

This adds the Orosu apt repository and installs the orosu-server and orosu-keygen packages, along with a systemd service for orosu-server.

2. Generate a keypair

orosu-server authenticates clients by Ed25519 keypair, not a shared secret. Generate one with orosu-keygen:

cd /etc/orosu
orosu-keygen --name my-ci-client \
  --private-key-output my-ci-client.key \
  --public-key-output my-ci-client.pub

This produces two files:

• Public key (my-ci-client.pub) — stays on the server, referenced from its config.
• Private key (my-ci-client.key) — goes into your CI system's secrets. Never commit it.

3. Configure orosu-server

Edit /etc/orosu/config.yaml:

listen:
  tcp: "127.0.0.1:8081"

clients:
  - name: my-ci-client
    secret_file: /etc/orosu/my-ci-client.pub

If you don't want to expose the server directly to the internet, put it behind a reverse proxy that forwards WebSocket upgrades — for nginx:

location /deploy/ {
    proxy_pass http://127.0.0.1:8081/;
    proxy_http_version 1.1;
    proxy_set_header Upgrade $http_upgrade;
    proxy_set_header Connection "upgrade";
    proxy_read_timeout 7d;
}

That makes the server reachable at wss://your-domain/deploy/.

4. Define a script

Scripts are the only thing a client is ever allowed to run — CI can pass arguments and files to them, but never an arbitrary command. Create one:

sudo mkdir -p /etc/orosu/scripts
sudo tee /etc/orosu/scripts/deploy.sh <<'EOF'
#!/bin/bash
echo "Hello, $1!"
EOF
sudo chmod +x /etc/orosu/scripts/deploy.sh

Then register it under the client in /etc/orosu/config.yaml:

clients:
  - name: my-ci-client
    secret_file: /etc/orosu/my-ci-client.pub
    scripts:
      - name: deploy
        command: ["bash", "/etc/orosu/scripts/deploy.sh"]

Restart the service to pick up the change: sudo systemctl restart orosu-server.

5. Trigger it from CI

Add the private key from step 2 as a repository or organization secret (e.g. OROSU_KEY), then add a step to your workflow using the GitHub Action:

- name: Deploy
  uses: orosu-ci/orosu@v0
  with:
    address: wss://your-domain/deploy/
    script: deploy
    key: ${{ secrets.OROSU_KEY }}
    arguments: "from CI"

Once triggered, orosu-server runs deploy.sh and streams its output back into the job log — you should see Hello, from CI!.