3034eaf4c7
Two fixes. The wizard's "new apps store their data on" dropdown was a bare native <select>. The OS draws that popup and ignores our CSS, which is why it came out as stock white chrome — the WebUI already solves this with custom-select.js, which enhances any select.form-control into a themed button and list. It just needed the class. And the installer now asks for the two roots independently rather than only app data. I had argued one question was simpler, and for a desktop it is — the control plane is ~20 MB and moving it gains nothing. But on a small board with an 8 GB eMMC and a USB SSD you want both moved, and there was no way to say so without knowing the flags exist. Still one disk list and two short questions; each is skipped if its flag was already passed. Fixed a bug the test caught immediately: _initAskDisk returns the chosen path on stdout, and it was printing the prompt there too, so the question text became part of the answer — the system root ended up named after its own prompt. Prompts go to stderr now, stdout is the return channel. Verified every combination under a pty: both default, apps only, both moved, system only, and invalid-then-valid. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
142 lines
5.4 KiB
Markdown
142 lines
5.4 KiB
Markdown
# LibrePortal — Install & Use
|
|
|
|
How to install, place, update, and remove LibrePortal. For building releases or
|
|
running a dev copy, see [development guide](../contributing/development.md).
|
|
|
|
> **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](../contributing/development.md). The commands below are the intended public flow.
|
|
|
|
## Requirements
|
|
|
|
- A **Debian** or **Ubuntu** host.
|
|
- **root** (run with `sudo`).
|
|
- `curl` (or `wget`) and `tar`.
|
|
|
|
## Install
|
|
|
|
```bash
|
|
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 itself — 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 |
|
|
|
|
```bash
|
|
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:
|
|
|
|
```bash
|
|
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:
|
|
|
|
```bash
|
|
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](upgrade-notes.md) 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
|
|
|
|
```bash
|
|
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.
|