Skip to content

Latest commit

 

History

History
440 lines (328 loc) · 16.8 KB

installation.md

File metadata and controls

440 lines (328 loc) · 16.8 KB

Installation and operations

Detailed setup, update and removal steps. For the one-line install and an overview of what it changes, see the README.


Before you start

St0r must be installed on the same machine as UrBackup Server. It opens UrBackup's SQLite databases and the backup storage folder as local files, so a remote UrBackup server is not supported.

Requirement Detail
UrBackup Server 2.5.x — developed and verified against 2.5.38
OS Ubuntu or Debian (the installer uses apt)
Runtime Node.js 20+, MariaDB, Nginx

If UrBackup Server is not already installed, the automated installer will install it — from the ppa:uroni/urbackup PPA on Ubuntu, or the official .deb on Debian.


Automated installation

curl -fsSL https://raw.githubusercontent.com/agit8or1/St0r/main/install.sh | sudo bash

Or review it first, which is the better habit for a script run as root:

wget https://raw.githubusercontent.com/agit8or1/St0r/main/install.sh
less install.sh
sudo bash install.sh

Run on its own like this, the installer installs the latest published GitHub release, the same one About → Check for Updates installs. It downloads the signed release asset (st0r-v<version>.tar.gz and .sig) and verifies the signature against the St0r release key built into install.sh itself; it refuses to install anything that does not verify. Only releases from 3.2.130 on are signed: install older ones from a checkout. Run from inside a clone (git clone, then sudo ./install.sh in it), it installs that checkout. To install a specific release, set ST0R_INSTALL_VERSION, for example curl -fsSL …/install.sh | sudo ST0R_INSTALL_VERSION=3.2.118 bash. The first line it prints says which version it chose and why.

To serve St0r over HTTPS from the start, give it a DNS name that already points at the server (port 80 must be reachable for the Let's Encrypt challenge):

curl -fsSL https://raw.githubusercontent.com/agit8or1/St0r/main/install.sh \
  | sudo bash -s -- --domain backup.example.com --email you@example.com

--email is optional (expiry notices). Running install.sh --domain … on an existing install only enables HTTPS.

The installer will:

  1. Install Node.js 20, MariaDB, Nginx, rsync, sqlite3, openssh-client — and UrBackup Server if absent.
  2. Create the urbackup_gui database and apply the schema and migrations.
  3. Create the st0r system account (no login shell, home /var/lib/st0r), which St0r runs as. An existing install that ran as the user who installed it is moved to this account.
  4. Copy St0r into /opt/urbackup-gui, owned by st0r, and build the backend and frontend there as st0r (npm ci --ignore-scripts from the lockfile; the sqlite3 binary is the official prebuilt, checked against the SHA-256 in setup/sqlite3-prebuilt.sha256).
  5. Install the root-owned files: the updater /usr/local/lib/st0r/auto-update.sh, its no-argument launcher /usr/local/lib/st0r/start-update, the helper /usr/local/lib/st0r/st0r-helper (the panel's other root actions, each one fixed and validated), the release key /etc/st0r/release-signers, and /etc/sudoers.d/st0r-update, which lets st0r run the launcher and the helper and nothing else.
  6. On first install, write /etc/nginx/sites-available/urbackup-gui, enable it as the default site on port 80, and remove /etc/nginx/sites-enabled/default. An existing St0r site is never overwritten, so re-running the installer keeps Certbot's HTTPS configuration.
  7. Add st0r to the urbackup group and make /var/urbackup/backup_server*.db group-writable.
  8. Install and start the urbackup-gui systemd service.
  9. With --domain, get a certificate with Certbot and redirect HTTP to HTTPS.

Then open http://YOUR_SERVER_IP (or https:// your domain) and sign in as admin. The installer prints the generated password when it finishes; it is also in /opt/urbackup-gui/initial-admin-password.txt and the service log. You must change it at first login. See First login.


Manual installation

1. Dependencies

sudo apt-get update
sudo apt-get install -y curl gnupg2 nginx mariadb-server rsync sqlite3

curl -fsSL https://deb.nodesource.com/setup_20.x | sudo bash -
sudo apt-get install -y nodejs

2. Database

sudo systemctl enable --now mariadb

sudo mysql -u root <<'EOF'
CREATE DATABASE urbackup_gui CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci;
CREATE USER 'urbackup'@'localhost' IDENTIFIED BY 'CHANGE_ME';
GRANT ALL PRIVILEGES ON urbackup_gui.* TO 'urbackup'@'localhost';
FLUSH PRIVILEGES;
EOF

sudo mysql -u root urbackup_gui < database/init/01_schema.sql
for m in database/migrations/*.sql; do sudo mysql -u root urbackup_gui < "$m"; done

3. Application

# St0r's own account: no login, no sudo of its own
sudo useradd --system --user-group --home-dir /var/lib/st0r --shell /usr/sbin/nologin st0r
sudo install -d -o st0r -g st0r -m 0750 /var/lib/st0r

sudo mkdir -p /opt/urbackup-gui
sudo cp -r . /opt/urbackup-gui/
sudo chown -R st0r:st0r /opt/urbackup-gui

cd /opt/urbackup-gui/backend
sudo -u st0r -H npm ci --ignore-scripts
sudo -u st0r -H bash ../setup/install-sqlite3.sh "$PWD"    # pinned, checksummed sqlite3 binary
sudo -u st0r -H npm run build

sudo -u st0r tee .env >/dev/null <<EOF
NODE_ENV=production
PORT=3000
DB_HOST=localhost
DB_PORT=3306
DB_NAME=urbackup_gui
DB_USER=urbackup
DB_PASSWORD=CHANGE_ME
JWT_SECRET=$(openssl rand -hex 64)
APP_SECRET_KEY=$(openssl rand -hex 32)
URBACKUP_DB_PATH=/var/urbackup/backup_server.db
URBACKUP_API_URL=http://localhost:55414/x
URBACKUP_USERNAME=admin
URBACKUP_PASSWORD=
EOF

cd /opt/urbackup-gui/frontend
sudo -u st0r -H npm ci --ignore-scripts && sudo -u st0r -H npm run build

JWT_SECRET and APP_SECRET_KEY are required — the backend refuses to start without a strong JWT_SECRET. APP_SECRET_KEY is the key used to encrypt replication SSH credentials at rest; losing it makes stored replication credentials unreadable.

4. Database access for the service user

St0r reads UrBackup's SQLite databases directly, and writes to them for a few operations:

sudo usermod -a -G urbackup st0r
sudo chmod g+w /var/urbackup/backup_server.db /var/urbackup/backup_server_settings.db

5. Services

# Root-owned updater, launcher, helper, release key and their sudo rule — from the
# checkout, not from /opt (which the service user can write to)
sudo bash setup/install-root-files.sh "$PWD" st0r

sudo cp setup/urbackup-gui.service /etc/systemd/system/
sudo systemctl daemon-reload
sudo systemctl enable --now urbackup-gui

sudo cp /opt/urbackup-gui/setup/nginx-site.conf /etc/nginx/sites-available/urbackup-gui
sudo ln -sf /etc/nginx/sites-available/urbackup-gui /etc/nginx/sites-enabled/urbackup-gui
sudo rm -f /etc/nginx/sites-enabled/default   # see the note below before running this
sudo nginx -t && sudo systemctl restart nginx

Configuration reference

Backend settings live in /opt/urbackup-gui/backend/.env. The full annotated list is in .env.example. The ones that matter most:

Variable Purpose
DB_* MariaDB connection for St0r's own database
JWT_SECRET Session signing key. Required; no default is accepted
APP_SECRET_KEY Encrypts replication SSH credentials at rest
URBACKUP_DB_PATH Path to backup_server.db (default /var/urbackup/backup_server.db)
URBACKUP_API_URL UrBackup HTTP API (default http://localhost:55414/x)
URBACKUP_PASSWORD Leave empty if the UrBackup admin account has no password
ST0R_DISK_* Disk guard thresholds — see .env.example
STOR_DRILL_SCRATCH Scratch storage for recovery drills (default /tmp/st0r-drills) — see recovery-verification.md

.env is preserved across updates.


Running behind an existing web server

The bundled Nginx site claims port 80 as default_server and the installer removes Nginx's default site. If the machine already serves web content, skip that part and proxy to the backend instead — it listens on 127.0.0.1:3000:

location /api/ {
    proxy_pass http://127.0.0.1:3000;
    proxy_http_version 1.1;
    proxy_set_header Host $host;
    proxy_set_header X-Real-IP $remote_addr;
    proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
    proxy_set_header X-Forwarded-Proto $scheme;
}

location / {
    root /opt/urbackup-gui/frontend/dist;
    try_files $uri /index.html;
}

Enabling HTTPS

Without --domain the installer configures plain HTTP only, and says so when it finishes. To add HTTPS later, re-run it with your domain (this only enables HTTPS on an existing install):

sudo ./install.sh --domain backup.example.com          # from a checkout
curl -fsSL https://raw.githubusercontent.com/agit8or1/St0r/main/install.sh | sudo bash -s -- --domain backup.example.com

or run Certbot by hand with the bundled Nginx site in place:

sudo apt-get install -y certbot python3-certbot-nginx
sudo certbot --nginx -d backup.example.com --redirect

Re-running the installer later does not overwrite the Nginx site, so the HTTPS configuration stays.

Do not expose St0r over plain HTTP to an untrusted network — session cookies and the login form travel in clear text.


Service management

sudo systemctl status urbackup-gui
sudo systemctl restart urbackup-gui
sudo journalctl -u urbackup-gui -f

sudo nginx -t && sudo systemctl restart nginx

Updating

From the interface

About → Check for Updates → Update Now. The panel runs sudo /usr/local/lib/st0r/start-update (no arguments), which starts the root-owned /usr/local/lib/st0r/auto-update.sh. The updater downloads the signed release, verifies it against /etc/st0r/release-signers and refuses it if the signature or version does not match. It then backs up the current installation, copies the new files in and installs dependencies with npm ci --ignore-scripts from the release's lockfile (and the checksum-pinned sqlite3 binary), builds — all as the service user — applies the database migrations from the verified release, refreshes the root-owned updater files and restarts the service. .env and the downloads directory are preserved. It restores the backup automatically if a step fails.

Installs from before 3.2.131 have no launcher yet; their first update from the interface runs /opt/urbackup-gui/setup/auto-update.sh once, which installs it. Re-running install.sh does the same.

Since 3.2.132 St0r runs as its own st0r account. An update moves an install that still runs as the user who installed it over to st0r, after checking that st0r can run its Node.js (and cannot modify it) and read the backup storage; if a check fails, or the panel does not start as st0r, it stays on the old account and the update log says why. Re-running install.sh makes the move too. Features that need root (UrBackup and OS updates, reboot, deleting backups, cleanup, image export, the log page) go through /usr/local/lib/st0r/st0r-helper; until an update has installed it, they report that the update should be run once more.

From a checkout

cd /path/to/St0r
git pull
sudo ./deploy.sh

Deploying only one half

The backend and the frontend can be deployed independently:

# Backend — needs a service restart
cd backend && npm run build
sudo rsync -a --delete --chown=st0r:st0r dist/ /opt/urbackup-gui/backend/dist/
sudo systemctl restart urbackup-gui

# Frontend — nginx serves the files directly, so no restart
cd frontend && npm run build
sudo rsync -a --delete --chown=st0r:st0r --exclude downloads dist/ /opt/urbackup-gui/frontend/dist/

--exclude downloads matters: frontend/dist/downloads/ holds published installers and is not build output.

Layout

<checkout>/                     Development and source
├── backend/src/                TypeScript source
├── backend/dist/               Compiled output (gitignored)
├── frontend/src/               React source
├── frontend/dist/              Vite build output (gitignored)
└── deploy.sh                   Build, sync, migrate and restart

/opt/urbackup-gui/              Production
├── backend/dist/               Running backend
├── backend/.env                Secrets — preserved across updates
├── frontend/dist/              Static files served by nginx
└── version.json                Version manifest the update checker reads

/usr/local/lib/st0r/            Root-owned updater (auto-update.sh), its launcher (start-update)
                                and the helper for the panel's other root actions (st0r-helper)
/etc/st0r/release-signers       Release key updates are verified against
/etc/sudoers.d/st0r-update      Lets st0r run the launcher and the helper, nothing else
/var/lib/st0r/                  Home of the st0r service account (npm cache)

deploy.sh builds both halves, syncs them into /opt/urbackup-gui, applies migrations, deploys version.json, and restarts the service — failing loudly with logs if it does not come back.


Uninstalling

This removes St0r. It does not touch UrBackup, its databases, or your backups.

sudo systemctl disable --now urbackup-gui
sudo rm /etc/systemd/system/urbackup-gui.service
sudo systemctl daemon-reload

sudo rm -f /etc/nginx/sites-enabled/urbackup-gui /etc/nginx/sites-available/urbackup-gui
sudo systemctl restart nginx

sudo rm -rf /opt/urbackup-gui /usr/local/lib/st0r /etc/st0r /etc/sudoers.d/st0r-update
sudo userdel st0r && sudo rm -rf /var/lib/st0r
sudo mysql -u root -e "DROP DATABASE urbackup_gui; DROP USER 'urbackup'@'localhost';"

Two things the installer changed that this does not undo — reverse them by hand if you want to:

  • Nginx's default site was deleted. Restore it with sudo ln -sf /etc/nginx/sites-available/default /etc/nginx/sites-enabled/default.
  • The service user was added to the urbackup group and UrBackup's database files were made group-writable.

Backing up St0r's own database

St0r's accounts, customers and replication configuration live in the urbackup_gui MariaDB database, separately from UrBackup's own data. Server Settings → Database Backup creates a compressed dump into /opt/urbackup-gui/backups/, and lists, restores or deletes existing ones. These are administrator-only actions.

This is not a backup of UrBackup's databases or of your backup data. For those, see Backing up UrBackup's databases — worth reading before any maintenance that touches /var/urbackup.


Replication setup

  1. Replication → Targets → Add Target.
  2. Enter the standby server's host, SSH user and credentials. An SSH key is preferable to a password.
  3. Set the target root path, and any repository path mappings.
  4. Test Connection to verify SSH and rsync reachability.
  5. Replication → Settings to enable replication and choose the trigger mode.
  6. Run Now on a target starts an immediate run.

SSH credentials are encrypted with AES-256-GCM using a key derived from APP_SECRET_KEY.

Replication copies the backup store to another machine. It does not make backups immutable — a deletion or corruption on the source replicates to the target. To check that the copy can actually be restored, set up a recovery drill against the target.


Troubleshooting

Backend will not start

sudo journalctl -u urbackup-gui -n 50
sudo ss -lptn 'sport = :3000'
mysql -u urbackup -p urbackup_gui -e "SELECT 1;"

A missing or weak JWT_SECRET stops the backend deliberately, with that reason in the log.

File browser lists nothing

The service user must be able to read UrBackup's storage tree. Confirm it is in the urbackup group (id "$USER") and that every directory above the backup folder is traversable.

Backups will not start (start_ok: false)

UrBackup rejected the request. The usual cause is internet file or image backups being disabled for that endpoint — check Endpoint Settings → Transfer and Image Backup.

Nginx problems

sudo nginx -t
sudo tail -f /var/log/nginx/error.log

Address already in use or a default_server conflict usually means another site already owns port 80 — see Running behind an existing web server.