LibrePortal/docs/guide/install-and-use.md

LibrePortal — Install & Use

How to install, place, update, and remove LibrePortal. For building releases or running a dev copy, see development guide.

Note: the get.libreportal.org host isn't live yet. Until it is, install from a local release artifact or a git/local checkout — see development guide. The commands below are the intended public flow.

Requirements

• A Debian or Ubuntu host.
• root (run with sudo).
• curl (or wget) and tar.

Install

curl -fsSL https://get.libreportal.org/install.sh | sudo bash

This downloads a versioned, checksum-verified release tarball (no git, no login), installs LibrePortal, and prints the WebUI address + a generated password (also saved to the install log). To choose the password yourself add --password=….

Put data where you want it (separate disks, external drives)

The installer just asks. If it finds another drive, it offers it before installing anything — one list, two independent questions:

Where should LibrePortal keep things?

  1)  This disk (default)      911.9G   808.4G free
  2)  /mnt/bigdisk             3.6T     3.6T free

LibrePortal — settings, database, logs. Around 20 MB, and it stays small.
Choose [1]:

App data — everything your apps store. This is the one that grows.
Choose [1]:

They're separate on purpose. On a desktop you usually only move the second. On a small board with an 8 GB eMMC and a USB SSD you move both.

It picks a subdirectory on the drive you choose, never the mount point itself, and skips a question when the matching flag was already passed — or the whole thing when there is nothing else to choose, no terminal, or you're running unattended.

The three roots below are still there for scripted installs:

Flag (default)	Holds	Owner
--system-dir=/libreportal-system	configs, database, logs, install	the manager user
--containers-dir=/libreportal-containers	live app data	the container user
--backups-dir=/libreportal-backups	backup repositories	the container user

curl -fsSL https://get.libreportal.org/install.sh | sudo bash -s -- \
  --system-dir=/mnt/ssd/libreportal \
  --containers-dir=/mnt/ssd/libreportal-apps \
  --backups-dir=/mnt/bigdisk/libreportal-backups

Notes:

• Defaults are top-level dirs on purpose — they avoid the permission/encryption pitfalls of living inside a user's home. To put containers/backups inside /home/<user> you must add --allow-home (it needs the container user to traverse that home — a small privacy trade-off).
• Other flags: --manager-user=NAME (default libreportal), --channel=stable|edge (default stable), --version=X.Y.Z (pin a version).

Where things end up

<system-dir>/      configs/  logs/  install/  database.db  ssl/  ssh/
<containers-dir>/  one folder per installed app (+ the libreportal WebUI)
<backups-dir>/     one folder per backup location

The three roots are chosen at install and fixed afterward — changing them is a deliberate reinstall, not a setting, and that is part of the security model.

What is not fixed is where each app's data lives. You can register extra drives at any time and place apps on them individually:

libreportal storage scan             # what else could hold app data
libreportal storage add /mnt/bigdisk # register it (must be an empty directory)
libreportal app move nextcloud bigdisk

New apps follow CFG_STORAGE_DEFAULT (General → Basic), so one setting sends everything to the big disk without touching each app. An app whose drive is not mounted refuses to start rather than being rebuilt empty on the bare mount point.

Update

LibrePortal checks its channel for a newer version and shows a badge in the WebUI when one is available. Apply it from the dashboard, or on the host:

libreportal update apply       # update now if a newer version exists
libreportal update check       # just re-check the channel

Updates download + verify the new release tarball and redeploy. Your data, configs, and backups are untouched (they live outside the replaced install tree).

Some releases carry a fix that an already-installed app only picks up on its next install — see upgrade notes for the versions that need a manual step.

Backups on an external / removable drive

Point a backup location at the drive's mount path. For a removable disk, set Require Mounted Drive on the location (config key CFG_BACKUP_LOC_<n>_REQUIRE_MOUNT=true): LibrePortal then refuses to back up when the drive isn't mounted, so an unplugged disk never silently fills your system disk. Use a Linux filesystem (ext4/xfs/btrfs) — FAT/exFAT/NTFS can't hold the required ownership and will warn.

Uninstall

sudo libreportal-uninstall
# keep the rootless Docker layer + image cache for a fast reinstall:
sudo libreportal-uninstall --skip-docker-images

libreportal-uninstall is a fixed command on $PATH (no data path to type — it reads the real install locations from the installed service, so it works even with custom roots). It removes the three roots, the system users, and the small out-of-tree footprint (/usr/local/lib/libreportal, the /etc integration files).

⚠️ Uninstall permanently deletes all app data, configs, and the database. Take a backup first if you want to keep anything.