Zolim Installer

Installer for Liqwee GitOps agent on Debian/Ubuntu (systemd + Docker).

Quick Start

Run on the target host:

bash install.sh register --host host-1 \
  --repo ssh://git@forgejo.app.liqwee.fr:2215/liqwee/zolim.git

host-1 must match docker-config/host-1/ in the Git repository.

Actions

Use exactly one action as the first argument:

• create-ssh-key create/use deploy SSH key
• create-secret create/store webhook secret
• github-login prompt for a GitHub username and PAT, then log Docker into ghcr.io
• register register agent (clone/update + systemd unit)
• start start/restart agent service
• update pull the configured branch, refresh agent files, and restart the registered service

Important

• --repo is required for --register.
• SSH workflow is enabled by default.
• no-sudo mode is enabled by default.
• Use --no-ssh to disable SSH workflow.
• Use --sudo to allow sudo elevation when not root.
• --repo is optional for --create-ssh-key.
  • Without --repo, key is created locally but host-key pinning/remote check is skipped.
• Registration is allowed with zero active stacks.
  • Agent service still starts; first deployment runs automatically on next sync/webhook after a stack is added.

Examples

# 1) create key only
bash install.sh create-ssh-key --host host-1

# 2) create secret only
bash install.sh create-secret

# 3) register agent (requires repo)
bash install.sh register --host host-1 --repo ssh://git@forgejo.app.liqwee.fr:2215/liqwee/zolim.git

# 4) start service only
bash install.sh start

# 5) update an existing agent without registering again
bash install.sh update

# 6) disable defaults if needed
bash install.sh register --host host-1 --repo https://forgejo.example/owner/repo.git --no-ssh --sudo

GitHub Container Registry Login

With Docker already installed, run:

bash install.sh github-login

Enter your GitHub username and personal access token when prompted. The PAT input is hidden and passed to Docker through standard input. Use a personal access token (classic) with read:packages permission to pull private images. Authorize the token for your organization's SSO if required.

The action follows the installer's root requirement; use --sudo from a non-root session. Docker saves the credentials for root, which runs the agent service. No agent registration is required.

Update an Existing Agent

Run the current installer on a registered host:

bash install.sh update

The update reads /etc/liqwee-agent.conf, fetches the configured Git branch using the existing credentials, and copies scripts/agent.sh and scripts/webhook.py from that clone into /opt/zolim/agent. It then restarts liqwee-agent.service and checks its health endpoint.

The existing configuration, SSH keys, systemd unit, stack .env files, and deployment checkpoints are preserved. No registration, package installation, or stack deployment runs. A deployment already in progress, local tracked changes, or a diverged branch stops the update before the service is restarted.

Use bash install.sh update --sudo from a non-root session. To apply deployment behavior changes immediately to existing stacks, run the agent separately:

bash /opt/zolim/agent/agent.sh --force

What It Does

• Installs missing dependencies (Git, Docker, Compose, Python)
• Clones or updates the GitOps repository
• Configures systemd service liqwee-agent
• Uses SSH workflow by default (can be disabled with --no-ssh)
• Starts webhook listener (default port 9999)

Create Webhook Secret

The installer creates a random secret automatically if --secret is not provided.

1. Read current secret

grep '^WEBHOOK_SECRET=' /etc/liqwee-agent.conf

2. Generate a new secret manually (optional)

openssl rand -hex 32

3. Set a custom secret during install

bash install.sh create-secret --host host-1 --secret 'your-strong-secret'

4. Rotate secret after installation

NEW_SECRET=$(openssl rand -hex 32)
sudo sed -i "s/^WEBHOOK_SECRET=.*/WEBHOOK_SECRET='$NEW_SECRET'/" /etc/liqwee-agent.conf
sudo systemctl restart liqwee-agent.service

5. Configure Forgejo webhook

• Repository Settings -> Webhooks
• URL: http://your-agent-host:9999/
• Secret: same value as WEBHOOK_SECRET
• Events: Push

Common Commands

Service status

systemctl status liqwee-agent

Logs

journalctl -u liqwee-agent -f

Health check

curl -fsS http://127.0.0.1:9999/health

Important Options

• --host ID host identifier (or first positional argument)
• --repo URL Git repository URL
• --branch NAME Git branch (default: main)
• --port N webhook port (default: 9999)
• --secret VALUE webhook bearer secret
• --ssh enable SSH workflow (default)
• --no-ssh disable SSH workflow
• --ssh-fingerprint SHA256:... pin SSH host key fingerprint
• --no-sudo keep no-sudo mode enabled (default)
• --sudo allow sudo elevation when not root

Troubleshooting

Agent not starting

journalctl -eu liqwee-agent

Port already used

ss -tlnp | grep 9999

SSH access denied

• Confirm deploy key is added in Forgejo (read-only)
• Confirm server fingerprint is correct
• Re-run installer with --ssh

Related Docs

• Project README: ../zolim/README.md
• Getting started: ../zolim/GETTING_STARTED.md
• Setup summary: ../zolim/SETUP_SUMMARY.md