# LibrePortal — Install & Use

How to install, place, update, and remove LibrePortal. For building releases or
running a dev copy, see [DEVELOPMENT.md](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.md](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)

LibrePortal uses **three independent roots**, each can be its own path/disk:

| 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 locations are chosen at install and fixed afterward (changing them is a
deliberate reinstall, not a setting — this is part of the security model).

## 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).

## 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-system/install/uninstall.sh
# keep the rootless Docker layer + image cache for a fast reinstall:
sudo /libreportal-system/install/uninstall.sh --skip-docker-images
```

`uninstall.sh` finds your install automatically (even with custom roots — it reads
the real locations from the installed service) and removes the three roots, the
system users, and the small out-of-tree footprint (`/usr/local/lib/libreportal`,
the `/etc` integration files). `sudo init.sh uninstall` does the same thing.

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