Install LibrePortal
One command turns a fresh Debian or Ubuntu machine into your own app server. Here's what to run, what it does to the machine while it works, and how to get into the WebUI afterwards.
On this page
Installing LibrePortal takes one command and a bit of patience. When it's done you'll have a web page, the WebUI, where you install and look after apps without touching the terminal again unless you want to.
This page walks through it from start to finish. If you haven't picked a machine yet, read What you need first; it's short.
Before you start#
You need three things:
- A Debian or Ubuntu machine. Debian 10 to 13 and Ubuntu 18.04 to 26.04 are all fine. Debian 13 or Ubuntu 26.04 LTS is the best choice for a new machine. An ordinary PC (x86-64) runs every app; an ARM board like a Raspberry Pi runs LibrePortal too, but a few apps only exist for PCs.
- A way to type commands on it as root, either sitting at it or over SSH. You'll use
sudo. - An internet connection for the machine, for downloading LibrePortal, Docker and your apps.
Give it a machine of its own
LibrePortal switches on a firewall, runs Docker, and wants ports 80 and 443 for itself if you add a domain later. It's happiest on a machine that isn't doing other jobs. An old laptop, a small mini PC or a cheap VPS all work well.
Run the installer#
On the machine, run:
curl -fsSL https://get.libreportal.org/install.sh | sudo bash
That downloads the installer and runs it as root. The installer then downloads the newest LibrePortal release and checks it before using it: the file has to match its published checksum and carry LibrePortal's signature, or nothing is installed.
Would rather read it first?
Piping a script from the internet straight into sudo bash asks for a lot of trust, so it's fair to look before you leap. The installer is one readable file: install.sh. You can also download it, read it, and run it yourself:
curl -fsSL https://get.libreportal.org/install.sh -o install.sh
less install.sh
sudo bash install.sh
Add --dry-run to have it fetch and verify everything, say what it would do, and stop.
What happens while it runs#
It isn't instant. The installer updates the system, installs Docker and builds the WebUI, so leave it running until you see the finished card. Here's what's going on.
First, it checks the machine#
Before it changes anything, the installer looks the machine over and prints a short list: the operating system, processor, memory, free disk space, what the kernel supports, the clock, the internet connection and DNS, and whether any ports LibrePortal needs are already in use.
Each line is marked one of three ways:
- ✗ a problem. The install stops before touching anything, and the line says how to fix it. Fix it and run the same command again.
- ! a warning. Worth knowing, but the install carries on. Less than 2 GB of memory is a warning; less than 1 GB is a problem.
- i for information. Nothing to do.
If you understand a problem and want to carry on anyway, add --ignore-checks (see choosing things yourself). You can run the same checks any time later with libreportal system check.
Then it sets the machine up#
Once the checks pass, the installer:
- Updates the operating system with
apt-get dist-upgrade, and installs the handful of packages LibrePortal uses, includingresticfor backups. - Installs Docker, the thing that runs your apps, in rootless mode under its own user,
dockerinstall. Your apps' containers don't run as root. - Creates a user called
libreportalthat runs LibrePortal itself. It isn't in thesudogroup; it can only do the few root jobs it's been given. - Turns on the firewall (ufw), after allowing SSH and the WebUI through it first, so you don't lose your connection.
- Adds a swap file if the machine has 8 GB of memory or less and no swap yet. Swap won't make anything faster, but it stops apps being killed when memory runs short.
- Makes three folders:
/libreportal-systemfor LibrePortal's settings, database and logs,/libreportal-containersfor your apps' data, and/libreportal-backupsfor backups. - Starts the WebUI on a port picked at random between 3000 and 9999.
Why it works this way
The random port is deliberate. Bots on the internet knock on the usual ports all day. A WebUI that isn't on any of them is one fewer thing for them to find, and it never clashes with an app you install later.
When it's finished#
The installer ends with a card like this:
✅ LibrePortal installation complete! <3
📄 Full install log
/libreportal-system/logs/install-20260929-101500.log
🔐 WebUI Credentials
Username qhzmwtrkbsle
Password run: libreportal webui login show
🌐 Open the WebUI at
This network http://192.168.1.50:4821
Your username and address will be different. Two things to notice:
The password may not be on it. The installer never writes the WebUI password into its log, and when it can't be sure it's talking to your screen directly (the curl … | sudo bash command feeds it through a pipe), it leaves the password off the card too and prints run: libreportal webui login show instead. Do exactly that:
Advanced Do this from the command line
sudo -u libreportal libreportal webui login show
New to the command line? How to run LibrePortal commands →
That prints the username, password and every address the WebUI can be opened at. The libreportal command always runs as the libreportal user, which is why it starts with sudo -u libreportal.
There's a second password you can ignore. Near the start, the installer also printed a line beginning Generated password for the 'libreportal' system user. That one belongs to the libreportal user account on the machine, not the WebUI, and you don't need it to sign in. It isn't in the install log either; if you ever want it, this shows it again:
Advanced Do this from the command line
sudo -u libreportal libreportal secret get system CFG_LIBREPORTAL_USER_PASS
New to the command line? How to run LibrePortal commands →
Save the login somewhere safe
Put the WebUI username and password in your password manager now. If you lose them, libreportal webui login show gets them back, and libreportal webui login reset makes new ones.
Now open the address in a browser on any device on the same network. You'll see a sign-in page. From here, First login and setup takes over.
Choosing things yourself#
Everything has a sensible default, but you can pass options to the installer. Put them after bash -s -- like this:
curl -fsSL https://get.libreportal.org/install.sh | sudo bash -s -- --password='a long passphrase'
| Option | What it does |
|---|---|
--password=… |
Sets the libreportal system user's password instead of generating one. It isn't the WebUI login. |
--version=X.Y.Z |
Installs that exact version rather than the newest. |
--channel=edge |
Follows the edge channel, which gets new releases before stable. |
--ignore-checks |
Installs even when a check marked ✗ failed. |
--dry-run |
Downloads and verifies everything, says what it would do, and stops. |
--system-dir=… |
Where LibrePortal keeps its settings, database and logs. |
--containers-dir=… |
Where your apps keep their data. |
--backups-dir=… |
Where backups go by default. |
Putting the data on another disk#
The three folders can live anywhere. If the machine has a small system disk and a big second one, send the growing parts to the big one:
curl -fsSL https://get.libreportal.org/install.sh | sudo bash -s -- \
--containers-dir=/mnt/bigdisk/libreportal-apps \
--backups-dir=/mnt/bigdisk/libreportal-backups
The one-line installer never stops to ask about disks, so these options are how you choose. You can still change things later. LibrePortal's own folder and the apps' folder can be moved to another disk with libreportal storage relocate; the backups folder can't, but you can add a backup location on another disk instead. And you can add a drive at any time and move apps onto it one by one. Disks and storage explains how.
Not inside your home folder
The installer won't put app data or backups under /home/<you> unless you add --allow-home. Your apps' user would need to be able to walk through your home folder to reach them, which is a small privacy trade-off, and encrypted home folders cause trouble. The defaults at the top of the disk avoid both.
Running it again#
Running the install command on a machine that already has LibrePortal doesn't reinstall it. It upgrades it: your WebUI login, settings, apps and data all stay as they are, no new password is printed, and it ends by saying which version you now have. It also leaves the operating system alone unless you add --update-os.
Most updates don't need this; the WebUI offers them with a button. Some releases change the parts of LibrePortal that run as root, and those have to come through the installer. The WebUI tells you when that's the case. Updates has the details.
If something goes wrong#
- Read the end of the log. Every install writes one to
/libreportal-system/logs/install-<date>-<time>.log, with passwords blanked out. - Check the machine.
sudo -u libreportal libreportal system check --detailsruns the pre-install checks again with the reasons behind each line. - Fix what it points at, then run the same command again. A check marked ✗ stops the install before anything changes, so there's nothing to clean up first.
- Can't reach the WebUI? Make sure you're on the same network as the server, and use the exact port from the card.
sudo -u libreportal libreportal webui repairputs the WebUI back on plainhttp://and prints its address. That helps when a browser refuses the WebUI's HTTPS certificate after you've changed the HTTPS setting.
Troubleshooting has more.