SubakoOS

Operate

Troubleshooting

Begin with the service journal. SubakoOS surfaces many failures in the interface, but the journal includes the underlying exception and privileged-helper output.

bash
sudo systemctl status subakoos
journalctl -u subakoos -n 200 --no-pager

The site does not load

Confirm the service is listening locally:

bash
curl -i http://127.0.0.1:8080/api/health

If local health works, inspect the reverse proxy, certificate, FRONTEND_ORIGIN, and TRUSTED_PROXY_IPS. Production refresh cookies require HTTPS.

Login fails

  • Confirm the account exists on the host and can authenticate through PAM.
  • Confirm the initially selected administrator has wheel access.
  • Inspect /etc/pam.d/subakoos and the service journal.
  • Check that the browser is using the configured HTTPS origin.

A host operation reports a sudo error

Production host operations require the installed root-owned helper and targeted sudoers policy. A source-tree development server intentionally cannot use that policy. Re-run the installer to repair deployed files rather than broadening sudo permissions manually.

bash
sudo visudo -cf /etc/sudoers.d/subakoos
sudo ls -l /opt/subakoos/privileged/subako-privileged

A feature is unavailable

Optional host tools may not be installed. Re-run the bootstrap with the required feature group or use its --check-only mode to inspect the transaction first.

A release upgrade fails

The installer stores timestamped SQLite backups in /var/lib/subakoos/database-backups/. Stop the service before restoring a selected backup, then restore its ownership and mode before restarting.

bash
sudo systemctl stop subakoos
sudo cp /var/lib/subakoos/database-backups/subakoos-<timestamp>.db.bak \
  /var/lib/subakoos/database/subakoos.db
sudo chown subakoos:root /var/lib/subakoos/database/subakoos.db
sudo chmod 0640 /var/lib/subakoos/database/subakoos.db
sudo systemctl start subakoos

Reporting a problem

Search GitHub issues before opening a report. Include the SubakoOS version, host distribution, affected module, relevant redacted logs, and exact reproduction steps. Never publish passwords, tokens, private keys, or secret values.

Edit this page on GitHub ↗