Installation

SubakoOS currently supports native installation on Fedora 39 or later, Arch Linux, EndeavourOS, and CachyOS. Fedora is the primary and CI-tested platform.

Review the bootstrap before running it as root. Tagged releases include a signed checksum manifest and a production runtime bundle.

Install a stable release

Download the current release bootstrap from GitHub:

curl -fLO https://github.com/lypticDNA/SubakoOS/releases/latest/download/install.sh
less install.sh
sudo bash install.sh

The guided installer validates the host, verifies the signed release, enrolls the first administrator, offers optional feature groups, and installs the systemd service.

For an unattended minimal installation:

sudo bash install.sh \
  --admin-user alice \
  --features none \
  --plugins family-profiles,family-calendar,family-lists \
  --firewall-manager keep \
  --non-interactive --yes

Use --check-only with the same arguments to inspect the planned package and host changes without applying them.

Choose feature groups

Available groups include containers, storage, networking, tailscale, samba, sshfs, backups, dns, filesystems, monitoring, and tls. Choose none for a small base installation or all to install every supported dependency.

Configure HTTPS

Production SubakoOS listens on 127.0.0.1:8080. Put a TLS reverse proxy in front of it; remote plain HTTP is rejected.

subako.example.com {
    reverse_proxy 127.0.0.1:8080
}

Set the public origin in /etc/subakoos/subakoos.env:

FRONTEND_ORIGIN=https://subako.example.com
TRUSTED_PROXY_IPS=127.0.0.1

Then restart the service:

sudo systemctl restart subakoos

Keep TRUSTED_PROXY_IPS limited to the actual proxy addresses.

First login

Open the HTTPS URL and sign in with the Linux account selected during installation. SubakoOS verifies the password through PAM and confirms that the account has wheel access before creating the first application administrator.

Upgrade

Download and run the latest signed bootstrap again. Existing SQLite databases are backed up before migration, plugin states are retained, and the installed version is recorded in /opt/subakoos/VERSION.

Uninstall

The installed uninstaller preserves application data and configuration by default:

sudo bash /opt/subakoos/scripts/uninstall.sh

To permanently remove application data, configuration, credentials, and the service account:

sudo bash /opt/subakoos/scripts/uninstall.sh --purge-data

Continue with Using SubakoOS after the first successful login.