Local names
Opening your apps by name, like uptimekuma.home.arpa, instead of by address and port number, on your own network. Optional, and off until you turn it on.
On this page
Addresses like https://192.168.1.50:4821 work perfectly well, but nobody remembers them. Local names give each app a name on your own network instead, like https://uptimekuma.homeserver.internal.
They're entirely optional. Everything in LibrePortal works on addresses, and nothing gets worse if you never turn names on. They're a convenience for the people in your house who'd rather type a word than a number.
What you need first#
Names are served over HTTPS, so HTTPS without a domain (or with one) has to be on first. That needs Traefik installed.
You can turn names on without a DNS server, and over the VPN your server answers them itself for laptops and desktops. AdGuard Home or Pi-hole on this server is what answers "where is uptimekuma.homeserver.internal?" for devices at home, and it's required for phones on the VPN. The Local DNS card in the config offers to install one. See DNS for your VPN. Without one, point the names at your server on your router, or use the hosts file route below for a computer or two.
Then your devices have to ask it: see Making the names work on your devices.
Turning names on#
Local names live in one place: the Local names card on Admin → Network. Turn its switch on and it applies straight away, with no restart. From then on each app also answers at https://<app>.<your server's ending>, using the name LibrePortal knows it by: uptimekuma, nextcloud, vaultwarden. An app with a second web page gets a second name with the page's name added, and a second copy of an app called vaultwarden_work becomes vaultwarden-work.<ending>. The WebUI itself doesn't get a name; you keep opening it at its address, so a name that stops resolving can never lock you out of the page you'd fix it from.
The card shows the rest: the name ending, an example of a full name, what the Open buttons use, and a line that says whether names are working on the device you're looking at, with the reason when they aren't.
Your addresses keep working exactly as before. Names are an extra way in, not a replacement.
An app that's held until its admin account exists gets its name only once the account is made, including when you reinstall it. Until then nobody else on your network can reach it by name.
On the server, the same switch is a command:
Advanced Do this from the command line
sudo -u libreportal libreportal https names on
sudo -u libreportal libreportal https names off
New to the command line? How to run LibrePortal commands →
The name ending#
The part after the app's name, like uptimekuma.home.arpa, is the ending, and it's your server's own. LibrePortal makes one from the name you gave the server at install, under .internal: a server you called homeserver gets names like nextcloud.homeserver.internal. A server with no name gets a short one of its own. Only endings under .internal or .home.arpa are allowed.
Why those endings
.internal and .home.arpa are set aside for private networks and will never be sold as real domains, so a name under one can't clash with a website on the internet or be taken over by someone else. Each server having its own ending means two LibrePortal servers on the same network, or on the same VPN, never answer to the same name.
Older installs started on a shared lan.internal ending instead. If yours is still on it, the card offers Use this server's name to move to your own. It's worth doing, but it isn't done for you, because the ending is baked into the HTTPS certificate: a new ending means a new certificate, and every device will be asked to accept it once more. You can also set the ending yourself in the card's advanced settings, or with libreportal https suffix <ending>.
Making the names work on your devices#
A device looks a name up before it can open it. Out of the box, nothing on your network knows these names, so you need one of these.
With AdGuard Home or Pi-hole#
If AdGuard Home or Pi-hole is installed on the same server, LibrePortal adds the names to it for you, pointing at your server's address on your home network, and keeps them up to date as you install and remove apps. AdGuard Home gets one entry that covers every name; Pi-hole gets an entry for each app.
Your devices still have to ask that server for names. The usual way is to set your router to hand out your server's address as the DNS server, so every device at home uses it without being told. Where that setting lives depends on your router; look for "DNS" in its network or DHCP settings. You can also set it on a single device in its network settings.
With a hosts file#
Without a DNS app, you can add the names to one computer's hosts file (/etc/hosts on Linux and macOS, C:\Windows\System32\drivers\etc\hosts on Windows), one line per app:
192.168.1.50 uptimekuma.homeserver.internal
192.168.1.50 nextcloud.homeserver.internal
Use your server's own address instead of 192.168.1.50. It's fine for a laptop or two, but phones don't let you edit it, which is why a DNS app is the better answer for a household.
The certificate warning#
Names use the same certificate LibrePortal made when you turned on HTTPS without a domain, so your browser warns you about it the first time, just as it did for the addresses. Browsers remember your answer for each address separately, so you may be asked again the first time you open a name.
Which links the WebUI uses#
The Open buttons on your dashboard and app pages can use either the name or the address. That's the Link Style setting, on the Local names card on Admin → Network:
| Choice | Open buttons use |
|---|---|
| Auto — names where they work (the default) | The name, but only on a device where it's been checked and works. The address everywhere else. |
| Always IP | The address, always. |
| Always names | The name, always. |
On Auto, the WebUI quietly checks each name from your browser: does it reach this server, over HTTPS, with the certificate accepted? Only when all three are true does the button switch to the name. It checks again when you come back to the tab or change networks, and remembers the answer for a while, so your laptop can use names at home and addresses at a café without you doing anything.
Whichever way a button points, every address an app answers on is one click away. Next to an app with more than one, an Other ways to open menu lists them all, its local name, its address on your domain and its ip:port, each with Open and Copy, and says which work on the device you're looking at.
If you choose Always names and they don't work on a device, the WebUI says Names aren't working on this device. with the reason, and offers Use IP links on this device. That choice sticks to that browser only; Use names again puts it back.
Names over the VPN#
Names can work over the LibrePortal VPN too, so the same bookmark opens an app at home and when you're away. It's set per device when you add it to the VPN, because a phone and a laptop need different things to make it work, and because it's your choice whether the VPN answers your device's name lookups at all. See names over the VPN for how to turn it on for a device, and DNS for your VPN for the whole picture, including opening private apps by name and adding records of your own.
After you add a domain#
If you later move to a domain of your own, the names keep working, so nobody's bookmarks break. When nothing uses them any more, retire them:
Advanced Do this from the command line
sudo -u libreportal libreportal https retire-local
New to the command line? How to run LibrePortal commands →
