What a homelab is

A homelab is a small computer in your home. It has no screen. It sits on a shelf and runs all day and all night. It blocks ads on every phone and laptop in the house. It plays your movies on the TV. It keeps your passwords, photos, and documents on hardware that you own. None of it is in the cloud of another company. It can run a Minecraft server for your friends. This computer is a homelab. Building one is a hobby, and it can save you money. It is also one of the best ways to learn how computers really work.

You do not need to be a programmer. You do not need to be "good with computers." You need to read with care. You need to type what you read. And you need to enjoy it when a thing works because you built it. This manual explains everything else when you need it. This includes what an IP address is, what a container is, and why you sometimes type commands and do not click.

How the manual is organized

The manual is a numbered path. Parts A to C are the base. Read them in order. After that, you choose what you want.

1. Part A (you are here) — what you need, how to read this manual, and a ten-minute tour of the network ideas that everything else uses.
2. Part B — erase the spare PC and install Proxmox. Erase means that all data on the PC is deleted. Copy off anything you want to keep before you start. Proxmox is free software that lets one computer run many small servers safely. Part B also teaches the few steps that you repeat for every app.
3. Part C — the six services that every homelab needs first: monitoring, ad blocking, friendly addresses, a dashboard, phone alerts, and safe remote access. The last chapter turns on weekly backups. In that chapter you restore a backup one time, to prove that the backups work. You do this before you install any apps.
4. Parts D, E, and F — the catalog: passwords, documents, recipes, RSS, media streaming, photo backup, and game servers. Pick only what you want. Each chapter works alone.
5. Part G — for later, when 500 GB is not enough. You add drives and do backups the right way.
6. Part H — what to do when something breaks (something will, and it is fine), and the small monthly tasks that keep everything healthy.

The server machine

Almost any PC from the last ten years can be a homelab. Office mini-PCs are good. These are the small black boxes that companies sell off in large numbers. An old gaming tower or a retired desktop from the closet is also good. All numbers in this manual fit the example machine below.

Do not worry about the specs too much. Your machine can become slow in the middle of a build. For example, apps are slow or the memory is full. In that case, build only Parts B and C and stop. Or move everything to a larger machine later. You do not lose what you learn. Each chapter works the same on any machine.

Everything else

1. A USB stick of 4 GB or more. 8 GB is safer. The installer image is 1.7 GB. A stick that says "2 GB" usually has less space after formatting, so the image does not fit. The install also erases the stick. Do not use the stick that has your tax documents.
2. Your everyday computer. It can run Windows, macOS, or Linux. You control the server in two ways. One way is the browser, for the graphical dashboard. The other way is the terminal. The terminal is a text window where you type commands and do not click. Ch. 9 · SSH & the terminal explains it. This manual calls your everyday computer "your PC".
3. Access to the admin page of your router. A sticker on the router usually shows the address and the password. You use it two times. The first time, you look up some network settings. The second time, you make every device in the house use your new ad blocker. Ch. 16 · AdGuard Home explains the second step.
4. About one free afternoon for Parts B and C. After that, each app chapter takes 15–30 minutes.

This is the full list. No other item is added later. Ch. 5 · Safety rules & passwords asks you to check each item one more time, just before Part B. That is a check. It is not a new requirement.

The most important rule: our numbers and your numbers

The networks in this manual use example numbers. Our example house network is 192.168.1.x. The router is at 192.168.1.1. The server is at 192.168.1.220. Each app container gets its own fixed address between .200 and .254. The spec plate of each chapter shows the exact address. Your house network probably uses similar numbers. But it does not always use the same numbers.

ipconfig

netstat -nr | grep default

ip route | head -1

Ethernet adapter Ethernet:
   IPv4 Address. . . . . . . : 192.168.1.37
   Subnet Mask . . . . . . . : 255.255.255.0
   Default Gateway . . . . . : 192.168.1.1

default            192.168.1.1        UGSc    en0

default via 192.168.1.1 dev eth0 proto dhcp metric 100

The visual signs

You already met most of them. The black boxes are command listings. The badge on the bar of a box shows where you type the command. This is important.

1. HOST badge — type the command on the server itself. This is the Proxmox machine, homelab.
2. CT badge — type the command inside a container. The chapter always shows first how you get inside. Usually you use pct enter on the host.
3. YOUR PC badge — type the command on your everyday computer.
4. The Copy button copies the whole listing. A comment starts with #. It is a note for you. Copying it with the command does no harm. The computer ignores it.
5. 📋 NOTES cards are references. You paste them into the Notes field of Proxmox for later. They are not commands.

A box with a blue header and the word NOTICE holds important information. A box with stripes and the word WARNING means that data loss, an outage, or a security risk is possible. Read it two times.

Each chapter starts with a spec plate. It shows the number of the container, its address, the disk and memory sizes, a time estimate, and a link to the official docs of the app.

Numbered headers, such as the "2" next to this one, give each paragraph an address. Suppose another chapter says "see 15.3". Then you go to chapter 15, section 3. Words with a dotted underline are glossary terms. Click them. The next section explains the parts that you meet inside a task: the click paths, the pictures, and the fold-out boxes.

How each task is taught: buttons first

Almost everything in this manual happens in a web page. These are the Proxmox dashboard at https://192.168.1.220:8006 and the screen of each app. So each task is taught first with the mouse. The keyboard way comes second. A task always has the same shape:

1. The click path. Each step shows the exact route in one grey pill, for example homelab → Create CT or CT 102 → Options → Features → Edit. An arrow means "then click".
2. One picture for each step. Below the step, you see the screen that you look at. Compare it with your screen before you click.
3. The keyboard way, folded away. A grey bar named "Prefer the terminal?" is below the clicks. Click it to open the same task as one or two commands. If you ignore it, you lose nothing. Both ways give the same result.
4. The exception. Some work has no buttons. The manual says this in one line and shows the commands.

A few tasks are buttons and one command. One example is a setting that Docker needs. It is a permission switch called keyctl. The Create CT wizard has no box for it. One command sets it, together with the timezone and start at boot. Another example is a folder that is shared from the server into a container. The data of the app then stays outside the container. For these tasks, the manual shows the clicks. Then it shows one black command bar. Then it gives one sentence that says why no button is used for that step. Type that one command. It is not optional.

Picture reference — the three frames

Frame	What it shows
Full panel	A complete dialog or page, as wide as the text. Use it to check that you are on the correct screen.
Step picture	A smaller picture between two steps. It shows the screen at that step only.
Crop	One button, one field, or one row, cut close. Use it to find a small control that is easy to miss.

Notice — your screen and our screen

Each picture comes from a real Proxmox server and a real app. They are set up exactly like the example in this manual. So the pictures show the example names and numbers: the node homelab and addresses in 192.168.1.x. Your screen shows your own. Apps also change their look between versions. A button can move or change its color. The words of a step are the instruction. The picture only confirms it.

Some work happens inside a container. For example, you install packages, run the app, or edit a configuration file. Proxmox has no buttons for this work. These parts start with one plain line. It is always the same line:

The Create CT wizard is shown one time, tab by tab, in Ch. 10 · The container wizard. Later chapters show only the screens that differ. They list only the values that you must change, and they point back to Ch. 10 · The container wizard to explain what each setting means. This keeps the chapters short.

pct start 102

Reading order

1. Parts A, B, and C: read them in order. Do not skip. Everything later needs them.
2. Parts D, E, and F: choose what you want. Each chapter works alone. Each chapter states its prerequisites in its first lines.
3. Part G: read it when your disk is full, or before you store anything that you cannot replace. Part H: read it when something does not work.
4. Each chapter in the sidebar is complete. Nothing here is a stub or a placeholder.
5. You are lost? The boxes named "Three ways in" on the Contents page give you a guided route. There is one route to build from zero, one to fix something broken, and one to look things up.

Addresses: your router runs a small town

1 · IP addresses. Each device on your home network has a number such as 192.168.1.37. This is its address. Think of street addresses. The first three parts (192.168.1) are the street that your whole house shares. The last number is the door. Two devices cannot use the same door.

2 · DHCP. Your router gives out the numbers. Your phone joins the Wi-Fi and asks: "Does anyone have an address for me?" The router lends it one. The router only lends. Next week, the phone can get a different number. This is DHCP. It is perfect for phones and laptops.

3 · Static addresses. A server is different. Everything in the house must find it at the same door every day. So we give the server and each of its containers a fixed address. We choose the address. It is high in the range, from .200 up. The pool of the router rarely reaches this high. You do not do this now. In the install chapters, you set the address for each container. You use the IPv4 field, set to "Static". You see this field in Proxmox when you create a container.

First, check one thing about your router. Find its DHCP range. This is the block of addresses that the router gives out. You do not need to change anything now. Only note if your range reaches .200 or higher. The install chapter has you fix it at the time that it matters. Follow these steps:

1. Find the address of your router. It is often on a sticker on the router. It also shows as the "gateway" address in the network settings of your PC.
2. Type that address in a browser.
3. Log in. The sticker usually shows the default user name and password. The sticker is missing or the login does not work? Try admin and admin, or admin and password. Or search for the model number of your router online. Nothing works? Skip this check. Do it later, in the install chapter.
4. Look for a menu named DHCP, LAN, or Network Settings. The range is there. It is usually a start address and an end address.
5. Read the range. Many routers lend from .100–.254 or even from .2–.254. These ranges include .200 and up.

Your range includes .200 and up? Then you have two choices in the install chapter. One choice is to end the range of the router below .200. This is usually one number field and a Save or Apply button. The menu is different for each brand. The other choice is to pick a block for this manual outside the range.

Do you change the range? Then check that the change worked. Follow these steps:

1. Do not use your PC or phone to check. They keep their old address until the lease ends. They stay online whether you typed the range correctly or not.
2. Connect one device again. Turn its Wi-Fi off and on.
3. Look at the address that the device gets. It must be inside the new range.
4. The address is not in the new range? Then the range was not saved. Open the router page. Type the range again. Press Save or Apply. Test again in the same way.
5. The old address still shows after a second try? Some routers apply a new range only after a restart. Restart the router. Test again.

4 · Ports. One address can host many services. Ports are the apartment numbers behind one street door. The text 192.168.1.223:3000 means "address .223, apartment 3000". Web pages usually use port 80. Because of this, the browser does not make you type it. DNS uses port 53. SSH uses port 22. A listing such as -p 80:80 has two apartment numbers. The number before the colon is the number that you type on your PC. The number after the colon is the number that the app uses inside its own box. They are often the same. But they can differ. The text -p 8080:80 is also normal. You see this -p format again when you install apps. For now, a port is only an apartment number.

Names, doors, and remote hands

5 · DNS. Nobody remembers numbers. So the internet has a phonebook. DNS changes wikipedia.org into an address. Your homelab can be the phonebook of your house. This is how ad blocking works. Ch. 16 · AdGuard Home answers the question "ads.example.com?" with "I do not know this name". This is also how vault.home can point to your own password vault (Ch. 17 · Nginx Proxy Manager).

6 · SSH. Your homelab server usually runs without a screen. No monitor is connected. SSH is a secure remote keyboard. On your PC, you type ssh root@192.168.1.220. This opens the command line of the server in your terminal window. It works as if you sit in front of the server. A key pair replaces passwords. One secret file is on your PC. One public file is on the server. You make your key pair in Ch. 9 · SSH & the terminal.

7 · Containers. The server runs each app in its own container. A container is a light box. It has its own address, its own files, and its own small Linux inside. The boxes cannot hit each other. An experiment can go wrong. Then you throw away one box and build it again in a few minutes. All other boxes keep running. This is why a homelab is safe to learn on. Ch. 8 · Containers vs virtual machines explains it in detail.

What stays inside your house

You can reach everything that you build in this manual only from inside your home network. The exception is a chapter that says a service is reachable from the internet. Your services are not on the internet. Strangers cannot reach them. The numbers show why. Addresses that start with 192.168., 10., or 172.16 to 172.31 are private. Every home in the world uses the same blocks. The public internet has no route to them. This is why your services are invisible from outside by default. You must do something on purpose to expose one.

You want to reach your homelab from a coffee shop? Do NOT open holes in your router. Use Ch. 19 · Remote access: Tailscale. It builds an encrypted private tunnel between your devices. It does not add anything that strangers can see.

The five rules

1. Give each service its own password. You make a dozen admin accounts during setup. Do not use one password for all of them. You build a password manager in Ch. 22 · Vaultwarden. Until then, a paper notebook next to the server is fine. At home, the risk is that you forget a password. The risk is not a thief with a list of passwords.
2. Do not forward ports. Never. Unless a chapter tells you to. Port forwarding tells your router to let strangers on the internet reach a service on your server. Ch. 4 · Networking in 10 minutes explains it. It is also a rule here, because half of all homelab horror stories start with "I opened a port to test something."
3. Update each month, on purpose. Do not update automatically. Do not skip updates. Ch. 71 · Monthly maintenance is a ten-minute checklist. Put a repeating reminder in your calendar now. Automatic updates can break things at 3 a.m. If you never update, the system gets old and gets security holes.
4. Before you store anything that you cannot lose, set up backups the right way. You can build and learn for weeks without backups. You can build everything again with this manual. This changes when real photos, documents, or years of data are on the server. Then you cannot build them again. Ch. 64 · Backups done right (3-2-1) shows the right way. Do not skip it forever.
5. Understand a command before you run it. Almost every command in this manual has an explanation. It is in a fold-out box, or in the chapter that the command points to. Read it. You do not need to memorize it. You learn it so that, one day, a stranger on a forum (or an AI) gives you a command, and you can tell what it does before you paste it into your server. This skill is the real thing that this manual teaches.

Make it yours — change these before you go live

This manual uses example values. The example network is 192.168.1.x. The example server is called homelab. Many readers follow the same text. So many servers start out with the same names, the same ports, and the same default logins. Attackers know this. They scan the internet for those exact defaults. Change the items below, and your server is no longer one of a thousand copies.

The addresses on your home network are not the danger. An address like 192.168.1.220 only works inside your own house. A stranger cannot use it from outside. The dangers are default logins, example passwords, and ports that you open to the internet.

When something breaks

Something will break. This is not a failure. It is part of the hobby. Follow this calm sequence:

1. Nothing that you did today is fatal. Each app on the server runs in its own container. A container is a small box that you can throw away. It holds one app and its files. If an app breaks, the worst case is that you build its box again. This takes ten minutes.
2. Read the error message. Read it fully. Half of all fixes are in the message.
3. Open Ch. 70 · When it breaks: troubleshooting. It collects the common failures and their fixes in one place.
4. Check the logs of the app. The Reference card of each app chapter shows the log command. The chapters that build no container have none. The Home Assistant VM has none.
5. Are you still stuck? Search for the exact error text and the name of the app. You are never the first person with this problem.

Pre-flight checklist

This is the end of Part A. It is the calm before the build. Go through these seven items before you turn the page. Tick each one. Then you have everything you need:

1. You backed up the spare machine, and you agree to erase it. Everything on that disk is deleted in Part B.
2. You have a USB stick of 4 GB or more. 8 GB is safer and easier to find. You agree to erase it.
3. You have an Ethernet cable that is long enough to reach your router. The install sets a fixed wired address. This is a network address that never changes, so you can always find the server. The server does not use Wi-Fi.
4. You have a screen and a keyboard for the server. You need them for about twenty minutes, during the install. A TV with an HDMI cable works as a screen.
5. You have your PC. This is the laptop or desktop that you already own. You use it to control the server from a distance.
6. You have the admin login of your router. It is usually on a sticker on the router.
7. You have a free afternoon for Parts B and C.

Did you tick all seven? Then it is time. Go to Ch. 6 · Install Proxmox. We install Proxmox.

PREPARE THE BIOS

Before you install the operating system, change a few settings in the firmware of the machine. This is the BIOS (also called UEFI setup). You do this one time. You use the screen and keyboard that you plugged in. Two of these settings matter later. First, turn on virtualization. The Home Assistant virtual machine in a later chapter needs it. Second, set the server to turn itself on after a power cut. No one stands next to it to press the button.

This part has no pictures. Each board maker draws its own setup screen. The same setting has a different name on each board. One photo would confuse more readers than it helps. Follow the menu paths below. Read the words on your own screen.

1. Plug a monitor and a keyboard into the server. Turn it on.
2. When the logo of the maker appears, tap the setup key. It is usually DEL or F2. Watch the boot screen. It shows the key for one or two seconds. The one-time boot-menu key is a different key. It is usually F12, and sometimes F11 or DEL. You use it later, to boot from the USB stick. You do not use it now.
3. Turn on virtualization. Look in Advanced → CPU Configuration. On Intel boards, the setting is named Intel Virtualization Technology or Intel VT-x. On AMD boards, it is named SVM Mode or AMD-V. Set it to Enabled. Without it, the Home Assistant VM does not start.
4. Set Restore on AC Power Loss to Power On. It is usually in the Power menu or in APM. The name can differ: "After Power Failure" or "AC Recovery". A server without a screen must start itself after a power cut. If it does not, it stays off until someone visits it.
5. Optional: turn on Wake-on-LAN. It is often named "Power On By PCIe/PCI" or "Resume By LAN", in the Power menu. It lets you wake the server over the network later. Skip it if you cannot find it.
6. Save and exit. The key is usually F10. The machine restarts.

FLASH THE INSTALLER USB

Proxmox is one downloadable file. This file is an ISO, a complete installer in one image. You write the image to a USB stick. The server then starts from the stick and installs itself. You need a spare USB stick of 4 GB or more. 8 GB is safer. A stick that says "2 GB" usually has less space after formatting, so the installer does not fit. Flashing erases the stick.

You do this with the mouse, in a small free app named balenaEtcher. It runs on Windows, Mac, and Linux. By default, it shows only removable drives. This is why it is the safe choice.

1. On your PC, open https://www.proxmox.com/en/downloads.
2. Download the newest Proxmox VE ISO Installer. At the time of writing, it is 9.2.
3. Download balenaEtcher from balena.io/etcher. Open it.
4. Plug in the USB stick.
5. Select Flash from file. Pick the Proxmox ISO that you downloaded.
6. Select Select target. Pick your USB stick. Check the size. The stick is the small drive, a few gigabytes.
7. Select Flash. Wait until it writes and checks the stick. Close the app. Unplug the stick.

balenaEtcher has no picture here. Its window has one row of three large buttons: the image, the target, and Flash. The next button lights up when you fill in the previous one. It is hard to lose your place.

lsblk                                # find your USB stick's name (e.g. sdb)
sudo dd if=~/Downloads/proxmox-ve_9.2-1.iso \
  of=/dev/sdX bs=4M status=progress conv=fsync   # replace sdX with that name

BOOT THE INSTALLER

The server normally starts from its own SSD. This one time, you need it to start from the USB stick. You tell it with the one-time boot menu. The firmware of your board draws this menu. Proxmox does not draw it. So the picture below shows the shape of the menu. It does not show your exact screen.

1. Plug a monitor and a keyboard into the server. Put the USB stick in any port.
2. Turn the server on.
3. When the logo of the maker appears, tap the boot-menu key. It is usually F12, and sometimes F11 or DEL. Watch the boot screen. It shows the key for one or two seconds.
4. In the boot menu, select the USB stick. Choose the entry that starts with UEFI, if it is in the list.
5. The blue Proxmox menu appears. Select Install Proxmox VE (Graphical). Press Enter.

THE INSTALLER SCREENS

The graphical installer is a short wizard. It has six screens. After them, it writes the disk. Go through the screens in order. Each screen has a picture below its step.

1. EULA. Read the license. Select I agree.

   

2. Target harddisk. Select your SSD. It is the only disk in the machine, so you have no choice to make. Keep Options at the default filesystem, ext4. Proxmox uses the whole disk.

   

3. Location and Time Zone. Set Country to your country. Set Time zone to Region/City. Pick yours from the list. Set Keyboard Layout to your keyboard. It is usually U.S. English.

   

4. Administration Password. Set the root password. This is also your login for the web page. Make it strong and save it. Type your email. Proxmox sends server alerts to it later.

   

   This address does not give you working alerts by itself. Proxmox stores it. But a new install has no mail server. Each message goes to a local mailbox on the machine, and nobody opens it. It never reaches your inbox, and nothing reports the failure. Type a real address anyway. Get your real phone alerts later from Ch. 13 · ntfy and Ch. 14 · Uptime Kuma. Those chapters test the alerts when you build them.

1. Management Network. Keep Management interface on the one network card. It is usually already selected. Set Hostname (FQDN), the full name of the machine, to homelab.lan. Set IP (CIDR) to 192.168.1.220/24. Set Gateway to 192.168.1.1. Set DNS Server to 192.168.1.1. The /24 at the end means that all devices with the same first three numbers are on the same network. Keep /24. It is correct for a home network, whatever your own numbers are.

   

2. Summary. Check the disk and the IP one more time. Select Install.

   

timedatectl list-timezones          # print every valid zone name

These are the values on the network screen. Every later chapter uses them:

1. Let the install run. It takes a few minutes.
2. The installer says that it restarts the server. Pull the USB stick out. If the stick stays in, the server starts the installer again.

FIRST START: WEB PAGE AND REPOSITORY FIX

The server now runs without a screen. You can unplug the monitor and the keyboard. From here on, you manage it from the browser of your PC.

1. On your PC, open https://192.168.1.220:8006.
2. The browser shows a "connection is not private" warning. This is the own certificate of Proxmox. It is not a real problem. Select Advanced. Then continue to the address.

   

3. Log in as root. Use the password that you set in the installer.

   

4. A window says "No valid subscription". This is normal for the free version. Select OK.

   

You do the whole fix with buttons in the web page:

1. Go to homelab → Updates → Repositories. The panel lists each package source that the server uses.

   

2. Select the pve-enterprise row. Select Disable. Proxmox marks that repository as disabled in its settings file. You do not need to touch the file. The list can also show a ceph enterprise row. Select it and disable it in the same way.

   

3. Select Add. Pick No-Subscription from the list of known repositories. Select Add.

   

4. Go to homelab → Updates. Select Refresh. A small task window opens. It shows the package lists as they download. Close it when it ends.

   

5. Select Upgrade. It opens a new browser tab and starts at once. You do not need to confirm. Watch the output until it stops and the prompt comes back. Close the tab.

   

One last step finishes the job. A new kernel starts only after a restart. The Updates panel has no restart button. But the summary page of the node has one. Go to homelab → Summary. Select Reboot in the top right corner. You can also type the command. Open homelab → Shell and run:

reboot          # the host comes back in about a minute

for f in pve-enterprise ceph; do                                       # turn OFF the paid repos
  file=/etc/apt/sources.list.d/$f.sources
  [ -f "$file" ] && ! grep -q '^Enabled:' "$file" && printf 'Enabled: no\n' >> "$file"
done
cat > /etc/apt/sources.list.d/proxmox.sources <<'EOF'
Types: deb
URIs: http://download.proxmox.com/debian/pve
Suites: trixie
Components: pve-no-subscription
Signed-By: /usr/share/keyrings/proxmox-archive-keyring.gpg
EOF
apt update && apt full-upgrade -y
reboot

FINISH

1. Check that the web page still loads at https://192.168.1.220:8006 after the upgrade and the restart.
2. Keep the root password and the address 192.168.1.220 in a safe place. You use both all the time.
3. Set up a login without a password from your PC. Then you can type ssh root@192.168.1.220 and no password is asked. See Ch. 9 · SSH & the terminal.
4. Continue with Ch. 7 · The build order. It shows the order to build everything else.

WHEN IT GOES WRONG

These problems happen before the web page works, or because it does not work. So they have no buttons. You type at the console of the server. Plug the monitor and the keyboard in again.

1. The boot-menu key does nothing, and the old system starts. You tapped too late, or "Fast Boot" skips the prompt. Turn the machine off. Tap the key again and again from the moment that you press the power button. It still fails? Open the BIOS setup (usually F2 or DEL). Put the USB stick first in the boot order. This is a temporary change.
2. The Management Network screen shows no usable network card. The machine has only Wi-Fi. The installer of Proxmox offers only wired ports. Wi-Fi is not supported as the link of the server. Turn the machine off. Connect it to the router with a cable. Or use one of the two fixes from Ch. 2 · What you need: a powerline adapter, or a USB-to-Ethernet adapter of about $15. Plug it in and restart the installer, so that it shows.
3. The installer sees no disk. The SATA mode must be AHCI. Open the BIOS setup. Find Storage → SATA Operation. The name can differ for each maker. Select AHCI.
4. After the restart, the installer appears again. The USB stick is still plugged in. Remove it. Restart.
5. https://192.168.1.220:8006 does not load. Plug the monitor and the keyboard in again. Log in at the console as root. Run ip a. The bridge has no address, or a different address? Then you chose the wrong network card, or you mistyped the IP on the network screen. The simplest fix for a beginner is to run the installer again. Type the Management Network screen again with care. This erases the disk again, but the install takes only a few minutes. The command prints the address that you expected? Then the server is fine. The problem is between the server and your PC. Check that you typed https:// and not http://. Check that you typed :8006. Check that your PC is on the same network. Do not install again for this. It takes 45 minutes and changes nothing.
6. apt update prints a 401 for pve-enterprise. You skipped the repository fix, or you did not finish it. Open homelab → Updates → Repositories again. Each enterprise row must show as disabled. A No-Subscription row must be in the list.
7. The web page loads sometimes and not at other times, days or weeks later. Another device on the network got the address of the server. The DHCP pool of the router includes 192.168.1.220 or another fixed address of this manual. Open the admin page of the router. Shrink the DHCP pool so that it ends below .200. Or move the server to an address outside the pool. See the notice about the DHCP range above, before the Management Network step.

REFERENCE CARD

Paste this into homelab → Notes, the Notes panel of the node. The essentials for the host then stay with it. You type these commands. The host has no button for a health check or a log view. A restart of the host stops each container and each VM at the same time. Do it when nobody uses the lab.

## Proxmox VE host — homelab
dashboard https://192.168.1.220:8006 · docs https://pve.proxmox.com/pve-docs/

```sh
# is the web UI running?
systemctl status pveproxy
curl -fsSk https://localhost:8006 >/dev/null && echo OK   # quick health check
# logs (last 50)
journalctl -u pveproxy --no-pager -n 50
# restart the web UI (stop / start / restart)
systemctl stop pveproxy
systemctl start pveproxy
systemctl restart pveproxy
# is there an update? (refresh the package lists)
apt update
# update the host, then reboot (stops every CT and VM — pick a quiet time)
apt update && apt full-upgrade -y && reboot
```

THE ONE RULE — ONE SERVICE, ONE CONTAINER

Proxmox is the operating system of the server (homelab, at 192.168.1.220). Its job is to run small, separate machines on top of one physical box. This manual uses one kind of small machine: the LXC container, or CT for short. Ch. 8 · Containers vs virtual machines explains why.

This is the rule for the whole manual: one service, one container. Each app that you install gets its own container. Nothing is shared. This can look like a waste. It is the opposite. Each app is alone in its own box. So you can start it, stop it, snapshot it, back it up, or break it. Nothing else is affected.

Because of this rule, almost every build in this manual follows the same six steps:

1. Create the container. The wizard guides you. Ch. 10 · The container wizard
2. Turn on nesting and keyctl. These two settings let the container run Docker inside itself. Nesting is one box in the wizard. Keyctl is one command on the host, after the wizard. Ch. 10 · The container wizard
3. Install Docker. This is one command inside the new container. Each app chapter shows that command in its own build block. Ch. 10 · The container wizard explains how to create the container. It does not install Docker.
4. Run the app. Usually this is one docker run command.
5. Set it up. Open the app in a browser. Complete its first-run wizard.
6. Watch it. Add the app to Uptime Kuma as a new monitor. Kuma then checks it and warns you if it goes down. Open the notification settings of that monitor. Turn on your ntfy alert. The same warning then also goes to your phone. Ch. 13 · ntfy Ch. 14 · Uptime Kuma

Learn these six steps one time. Each app chapter is then a variation of them. The app chapters explain only what is different for that app.

WHERE EACH COMMAND RUNS

The most common beginner mistake is to type a command in the wrong place. A command runs in one of three places. Each command block in this manual has a small badge (⌨) with the place. The badge is before the command. Learn the three places now.

You open two of the three places with the mouse, in the Proxmox web page. Open the web page first. You type nothing yet.

These steps assume that Proxmox is installed on the server, and that you set a root password during the install. You did not do this yet? Ch. 6 · Install Proxmox explains it. Come back here after it.

1. Open https://192.168.1.220:8006 in the browser of your PC. The browser shows a warning that the connection is not private. This is normal. It is the own certificate of Proxmox. Ch. 6 · Install Proxmox (section "First start") explains the warning.
2. Log in as the user root. Use the password that you set during the install.

You are told to type commands in two places. You reach the first place now. The second place does not exist yet. This is expected.

1. The host — do this now. In the left tree, click homelab. Then click >_ Shell at the top right. The prompt is root@homelab:~#. It asks for no password. You are already logged in to Proxmox. You use this place most.
2. Inside a container — read this now, do it later. From the same host Shell, you enter a container with pct enter and its number, for example pct enter 106. The command exit brings you back to the host. Do not try it yet. You did not build a container, so there is nothing to enter. The command pct enter 106 shows an error now. The error is correct. You did nothing wrong. Your first container is Ch. 13 · ntfy. The build order in the next section starts there, not with Uptime Kuma. Come back to pct enter after that container exists.

Notice — read now, do later

You cannot do the second step yet. It needs a container. You build your first container in Ch. 13 · ntfy. The build order in the next section starts there. Read it now, so that you know that it exists. Come back after that chapter. Nothing breaks if you wait.

Keep the host Shell open in a tab while you work. It is the door to both places. The >_ Console button of the container is not that door. It opens the login: prompt of the container. Containers that you build with Ch. 10 · The container wizard have no root password. So no login works there.

Compare the badge of a command block with the shell that you are in. Do this before you press Enter. A command can fail with not found or not a block device. In that case, you are almost always in the wrong place.

ssh root@192.168.1.220   # prompt becomes root@homelab:~#

pct enter 100   # now you are inside the container

THE BUILD ORDER

Do not work down the sidebar. Build in this order. Each layer gives you something that the next layer needs.

1. Install Proxmox. This is the server itself: each installer screen and the first login settings. Everything else needs it first. Ch. 6 · Install Proxmox
2. Learn the foundation skills (the rest of Part B). Do these chapters in order before your first app:
   1. Containers and virtual machines Ch. 8 · Containers vs virtual machines: what a container is, and how it differs from a full virtual machine.
   2. SSH and the terminal Ch. 9 · SSH & the terminal: make your SSH key here first. The container wizard asks for it in the next step.
   3. The container wizard Ch. 10 · The container wizard.
   4. Security basics Ch. 11 · Security basics.
   Keep the short routine for after each build Ch. 12 · After every build + common Proxmox tasks near you. You repeat it each time.
3. Build the essential six (Part C), in this order: ntfy Ch. 13 · ntfy, then Uptime Kuma Ch. 14 · Uptime Kuma, then AdGuard Home Ch. 16 · AdGuard Home, then Nginx Proxy Manager Ch. 17 · Nginx Proxy Manager, then Homarr Ch. 18 · Homarr dashboard. Finish with remote access: Tailscale Ch. 19 · Remote access: Tailscale. Beszel Ch. 15 · Beszel is the one optional chapter in Part C. It fits right after Kuma. Build it if you want live resource graphs. Skip it if you run one machine and never check its load. The big win of the whole house comes in the AdGuard chapter. Ads disappear on each device, and you install no software on any of them.
4. Turn on backups before you build anything that you would miss. The last chapter of Part C Ch. 20 · Backups before apps takes about fifteen minutes of clicking. You make one weekly job that covers each container on the server. You also do one restore, to prove with your own hands that it works. Do it here, between the base services and the apps. In Part D, the server starts to hold things that exist nowhere else.
5. Then anything you like. The six services and the backup job are in place. Now choose freely from the app catalog (Part D), media and personal cloud (Part E), or game servers (Part F). These parts do not depend on each other. Build them in the order that you like.

Container or virtual machine

Each computer runs a kernel. The kernel is the program that talks to the hardware (the CPU, the memory, the disk) for all other programs. An LXC container shares the Linux kernel of the Proxmox host. It separates one slice of it. Think of roommates who share one kitchen. It is fast to set up. But everyone must cook the same kind of food, and for a container this means Linux only. A container starts in about a second. It adds very little load. So you can run many of them on the mini-PC at the same time. It shares the kernel of the host, so an LXC can run only Linux.

A virtual machine (VM) acts like a new, separate computer. It is built from nothing each time that it starts. It has its own kernel inside. Think of a whole new kitchen, not a shared one. A VM needs more memory and disk space. It starts more slowly. But it is the only way to run a different operating system. Examples are HAOS of Home Assistant (see Ch. 37 · Home Assistant (preview)) or a Windows system. In this manual, almost everything is an LXC container. A VM appears only where a chapter says so.

What "one container per app" really means

The rule of this manual is one container per app. Each service gets its own box. A problem in one box never touches another. Two details confuse people about this rule. Read both now.

Some apps need a helper

Some apps need a database or a search engine that runs next to them. Examples are Paperless, Karakeep, Penpot, and later Immich. For these apps, "one LXC per app" means that you run the small bundle of the app with Docker Compose inside its one container. It is still one container that you manage. But it is not one single program. These guides give you a compose file. This is a text file that lists the app and its helper in one place. Docker reads the file and starts both together.

The media stack is the exception

The media apps, such as Radarr, qBittorrent, and their relatives, must all read and write the same filesystem. Suppose each app keeps its own copy. Then each movie is stored two times or more, and the 500 GB SSD fills quickly. So, before you build any of them, you make one shared storage folder on the host. You mount it into each of their containers. To mount means that one host folder also shows up inside each container. Ch. 40 · Shared storage first shows exactly how.

MAKE YOUR KEY ON YOUR PC

This part has no buttons. Proxmox is not involved yet. You make the key in a terminal window on your own PC.

ssh-keygen -t ed25519 -C "you@your-pc"

cat ~/.ssh/id_ed25519.pub                            # Mac or Linux
Get-Content $env:USERPROFILE\.ssh\id_ed25519.pub    # Windows PowerShell

PUT YOUR KEY ON THE SERVER

Do this one time, now, for the Proxmox host itself. Ch. 6 · Install Proxmox told you to set up a login without a password to 192.168.1.220. This is that step. Later chapters assume that it is done. Containers are different. The wizard installs the key for you when you create each container (Ch. 10 · The container wizard).

This part has no buttons. You type in the same terminal on your PC. You need the root password of the server. This is the password that you set during the Proxmox install. This is the last time that you type it.

ssh-copy-id root@192.168.1.220

type $env:USERPROFILE\.ssh\id_ed25519.pub | ssh root@192.168.1.220 "mkdir -p ~/.ssh && chmod 700 ~/.ssh && tr -d '\r' >> ~/.ssh/authorized_keys && chmod 600 ~/.ssh/authorized_keys"

ssh root@192.168.1.220

SSH IN, NOT THE WEB CONSOLE

Use the Console of the Proxmox web page for one paste only: to install your key. The console damages long pastes. After that, switch to SSH from your PC for everything else. You repeat this pattern in each app chapter: SSH into a new container, then install Docker. You have no container yet. You build the first one in the next chapter. So your first real use of this pattern is in Part C.

First check which kind of container you built. You built it with a key? This is the default of the wizard. Then it already trusts you. Skip to the pct enter step below. You never need the console paste. You built it with a password instead? Keep reading. Install the key by hand below. Opening the console is the one step here that has a button.

mkdir -p ~/.ssh && chmod 700 ~/.ssh && echo 'ssh-ed25519 AAAA…your-key-here you@your-pc' > ~/.ssh/authorized_keys && chmod 600 ~/.ssh/authorized_keys

ssh root@192.168.1.xxx

Install Docker in the container

You can now use SSH to enter the container. Install Docker in it. Each app chapter needs Docker. The basic command is always the same.

apt update && apt install -y docker.io curl
docker ps                            # confirm Docker is running

ANATOMY OF docker run

Almost each app chapter is one docker run line. The lines differ only in the image name and the numbers. The shape is always the same. Learn it one time here. The app chapters point back to this section.

Docker has no buttons in Proxmox. You type these lines over SSH, or in the shell of the container from the host (pct enter <ID>).

docker run -d --name app --restart=unless-stopped \
  -v /opt/app:/data -p 8080:80 author/image

An update of an app always has the same three steps: pull the new image, remove the old container, and run it again with the same command. The three lines below do this, one line for each step. Do not act on this sentence alone. Use the listing. The data is in the volume, not in the container. So it stays unchanged.

docker pull author/image        # 1. get the new version
docker rm -f app                # 2. remove the old container
docker run -d --name app …      # 3. re-run with the SAME command; the volume keeps your data

REFERENCE CARD

Paste this card in the Proxmox Notes of any container that you reach by SSH. The key locations and the login and file-copy commands then stay one click away. The Notes panel is part of the web page. You type no commands.

1. Copy the card on the right.
2. In the Proxmox web page, click the container in the left tree.
3. Open the Summary tab.
4. Click the pencil icon next to the header of the Notes panel.
5. Paste the card in the editor. Click OK.

## SSH & keys — quick reference
private key `~/.ssh/id_ed25519` (secret) · public key `~/.ssh/id_ed25519.pub` (share) · on Windows both live in `%USERPROFILE%\.ssh\`

```sh
# make a key — once, on your PC
ssh-keygen -t ed25519 -C "you@your-pc"

# print your public key to copy
cat ~/.ssh/id_ed25519.pub                            # Mac or Linux
Get-Content $env:USERPROFILE\.ssh\id_ed25519.pub     # Windows PowerShell

# install your key on the server — once, from your PC
ssh-copy-id root@192.168.1.220                       # Mac or Linux
type $env:USERPROFILE\.ssh\id_ed25519.pub | ssh root@192.168.1.220 "mkdir -p ~/.ssh && chmod 700 ~/.ssh && tr -d '\r' >> ~/.ssh/authorized_keys && chmod 600 ~/.ssh/authorized_keys"   # Windows PowerShell

# log in — no password once your key is installed
ssh root@192.168.1.220                               # the server
ssh root@192.168.1.xxx                               # a container

# copy files over SSH (scp)
scp ./file root@192.168.1.xxx:/root/                 # PC -> container
scp root@192.168.1.xxx:/root/file ./                 # container -> PC

# install your key on a container by hand (in its web console)
mkdir -p ~/.ssh && chmod 700 ~/.ssh && echo 'ssh-ed25519 AAAA…your-key-here you@your-pc' > ~/.ssh/authorized_keys && chmod 600 ~/.ssh/authorized_keys
```

ONE-TIME PREREQUISITE — DOWNLOAD AN OS IMAGE

On a new install, the wizard's Template list is empty. A container needs an operating-system image to start from. Download one Debian image. Every container in this manual uses it, so you do this one time for the whole server. You use only buttons.

1. In the left tree, select homelab. Then select the storage local.

   

2. In the storage menu, select CT Templates.

   

3. Select the Templates button.
4. Type debian-13 in the Search box.

   

5. Select the debian-13-standard row.
6. Select Download at the bottom right.
7. Wait until the download task shows OK. The image now appears in the wizard's Template list.

   

Do this one time only. The image stays in the local storage. Each new container uses the same image. Repeat the download only if you rebuild the server.

pveam update                                # refresh the template list
TMPL=$(pveam available --section system | awk '/debian-13-standard/{print $2}' | tail -1)
pveam download local "$TMPL"                # once per server; harmless to re-run

WORK THROUGH THE EIGHT TABS

In the left tree, select homelab. Then select the blue Create CT button at the top right. Use Next to go through the tabs in order. Leave each field that this chapter does not list at its default value. The defaults are correct for this manual.

GENERAL

1. Keep Node at homelab.
2. Type the CT ID that the app chapter gives you, for example 102. Do not keep the number that the wizard suggests.
3. Type the Hostname, for example adguard.
4. Keep Unprivileged container ticked.
5. Leave Password and Confirm password empty.
6. Paste your public key into SSH public key(s). This is the line from ~/.ssh/id_ed25519.pub. You made the key in Ch. 9 · SSH & the terminal. You have no key yet? Make one first. That chapter exists for this step.

The same tab has the Nesting box that Docker needs. Proxmox ticks it for you. Leave it ticked. The wizard has no keyctl box. Docker needs keyctl too. You set it after the wizard, with one command (see the section "The host command every build needs").

TEMPLATE

1. Select the storage local.
2. Select the debian-13-standard image that you downloaded.

DISKS

1. Select the storage local-lvm.
2. Set Disk size (GiB) to the number that the chapter gives, often 6.

CPU

1. Set Cores to the number that the chapter gives, often 1.

MEMORY

1. Set Memory (MiB) to the number that the chapter gives, for example 1024.
2. Leave Swap (MiB) at its default value.

NETWORK

1. For IPv4, select Static. Do not select DHCP.
2. In IPv4/CIDR, type the fixed address, for example 192.168.1.223/24.
3. In Gateway (IPv4), type your own router's address. On this manual's example network, it is 192.168.1.1. On your network, it can be 10.0.0.1 or another address. Use the address that you wrote down in Ch. 4 · Networking in 10 minutes. Do not copy the address printed here.
4. Leave the IPv6 fields at their defaults.

DNS

1. Leave DNS domain empty. The grey words "use host settings" show that the field is empty. This is correct.
2. In DNS servers, type your own router's address. Use the same address that you typed in Gateway. Do not copy 192.168.1.1 unless it is your router.

CONFIRM

1. Read the summary. Each line shows one setting that you chose.
2. Make sure that Start after created is unticked. It is unticked by default. Do not click it "to make sure". A click ticks it. One host command comes next, before the first start of the container.
3. Select Finish.

The table below says what each field does. The app chapters give only the values.

THE HOST COMMAND EVERY BUILD NEEDS

Docker needs two permission switches on the container: nesting and keyctl. Keyctl lets Docker manage its own login keys. Without it, Docker refuses to start. The wizard ticks nesting for you. The wizard has no keyctl box. The wizard also has no timezone field, so a new container uses UTC. Its logs then show a time that is hours away from your local time.

One command on the host sets nesting, keyctl, and the timezone together. The command also sets "start the container when the server starts". The container's Options tab has boxes for some of these settings. The one command is faster, and it is the same for every chapter. This part has no buttons. Every app chapter that uses Docker runs this command after the wizard and before the first start.

pct set 102 --features nesting=1,keyctl=1 --onboot 1 --timezone host

The first start uses buttons again.

1. In the left tree, select the new container, for example 102 (adguard).
2. Select Start in the toolbar at the top right. The status changes to running.
3. Do not use the container's >_ Console button yet. It opens a login: prompt. You left the password empty, so you cannot log in there.
4. Select homelab → >_ Shell. This is the terminal of the server.
5. Run pct enter 102. Use the ID of your container. You are now inside the container as root. No password is needed. Every later chapter means this when it says "in the container".
6. Run apt update inside the container. The package lists download. This proves that your DNS entry is correct. The error "Temporary failure resolving deb.debian.org" means that DNS is wrong. Fix it now. See WHEN IT GOES WRONG below.

pct start 102
pct enter 102                      # now INSIDE the container

THE ONE-COMMAND ROUTE

You can skip the wizard. One pct create command makes the container with every setting from the eight tabs and from the host command. Each app chapter shows the real command for its own container, in a box named "Prefer the terminal?". This section explains the parts of that command one time. The app chapters point here.

TMPL=$(pveam available --section system | awk '/debian-13-standard/{print $2}' | tail -1)
pveam download local "$TMPL"
pct create 102 local:vztmpl/"$TMPL" \
  --hostname adguard --cores 1 --memory 1024 --rootfs local-lvm:6 \
  --net0 name=eth0,bridge=vmbr0,ip=192.168.1.223/24,gw=192.168.1.1 \
  --nameserver 192.168.1.1 --features nesting=1,keyctl=1 \
  --unprivileged 1 --onboot 1 --timezone host
pct start 102
pct enter 102

WHEN IT GOES WRONG

1. The Next button on the General tab is grey and does nothing. The wizard needs a password or an SSH public key before it lets you continue. It does not say this. Paste your public key into SSH public key(s) (made in Ch. 9 · SSH & the terminal). Next then works. You have no key yet? Make one. That chapter comes first for this reason.
2. The Template list is empty. You skipped the one-time image download, or the image went to a different storage. Select homelab → local → CT Templates. Check for a row debian-13-standard. If it is not there, repeat the first section.
3. Finish fails with "CT 102 already exists" or "volume already exists". That number belongs to an old or half-built container. Use the next free number. Or select the old container and remove it first: More → Remove.
4. Finish fails with a 500 error or "no space left on device". The SSD pool is full. Select homelab → local-lvm → Summary to check. Delete a container that you do not use, or old snapshots. Then run the wizard again.
5. The container starts, but apt update shows "Temporary failure resolving deb.debian.org". The DNS servers field is empty or wrong. Select CT → DNS → Edit. Set DNS servers to 192.168.1.1. Then run pct reboot 102 on the host and try again.
6. The container runs, but its address does not answer. Run pct config 102 on the host to read the address. The usual cause is a typing mistake in IPv4/CIDR or a missing /24. The second cause is an address that another device already uses. To test, stop the container and ping that address from your PC. If anything answers, the address is taken. Pick another one.

REFERENCE CARD

These template commands run on the host, not in a container. They have no buttons. Type them in homelab → >_ Shell when you need them. Paste the card into homelab → Notes, so the download and clean-up lines stay near.

## OS templates — Proxmox host (homelab)
docs https://pve.proxmox.com/pve-docs/pveam.1.html

```sh
# refresh the downloadable template list
pveam update
# which Debian 13 images exist?
pveam available --section system | grep debian-13
# what is already downloaded on this server?
pveam list local
# download the newest Debian 13 image (once per server)
TMPL=$(pveam available --section system | awk '/debian-13-standard/{print $2}' | tail -1)
pveam download local "$TMPL"
# remove a template you no longer need — list first, then remove that exact name
pveam list local
pveam remove <full-NAME-from-the-list-above>   # paste the whole local:vztmpl/… name as printed
```

SECRETS AND ADDRESSES — THE WORDS

A web address such as http://192.168.1.225 is not a secret. A port such as :8080 is also not a secret. They show only where a service is. You can keep them in your Notes. A secret (the general word is credential) is anything that proves that you may enter. If someone copies it, that person has your access.

• Password — you know it. You type it.
• API key or token — a long random text that one service uses to talk to another service by itself (Homarr → AdGuard). It works like a password, but for machines.
• Admin token — for example, the master key of Vaultwarden for its /admin page (see Ch. 22 · Vaultwarden).
• Database password — Immich, Paperless, and Penpot each run a database with its own password.
• Environment variable (env var) — a setting that you give to a container when it starts. You write it as -e NAME=value. Secrets often travel this way.
• .env file (env-file) — a plain file with lines of NAME=value. You point the container at it. You do not type the secrets on the command line.
• plaintext — text that is not encrypted and that a person can read. The problem is a secret in plaintext, where it can leak.

HANDLE A SECRET SAFELY

mkdir -p /opt/app
printf 'ADMIN_TOKEN=%s\n' "$(openssl rand -base64 48)" > /opt/app/.env
chmod 600 /opt/app/.env          # 600 = only the owner (root) can read this file
docker run -d --name app --env-file /opt/app/.env  <the rest of the app's own run line>   # load secrets from the file, not the command line

Then, in the Notes of Proxmox, write only the address and the command. Where a secret goes, write a pointer, not the value: ADMIN_TOKEN=<in /opt/app/.env>. You lose nothing that you need. The address stays. Only the key moves to the locked file.

TURN ON THE LOGIN — AT ONCE

Many self-hosted apps come with authentication turned off. Others leave the setup page open to everyone until you finish it. So, when a service starts, make its admin account and set its login first, before anything else. On a flat home network, "I will set the password later" leaves a window that anyone can walk through. A guide says "set auth"? Treat it as required. This is the practical version of the rule about a separate password for each service in Ch. 5 · Safety rules & passwords.

An app that you never opened before still follows the same four moves:

1. Open the address of the app in your browser as soon as the container answers. The address is on the spec plate at the top of the chapter of that app.
2. The first screen can offer to make an account: "sign up", "create admin", or "first user". Fill it in now, not after dinner. Until you do, that screen is open to everyone on your network.
3. Choose a long password that you use nowhere else. Put it at once in your password manager. Ch. 22 · Vaultwarden builds one on this server.
4. The app can also take you to its dashboard with no login at all. Then open its Settings and look for Users, Authentication, or Security. Switch the login on before you put anything of your own in the app.

One test shows that it worked. Sign out. Reload the page. The app lets you in without any question? Then the login is not on yet.

RUN CONTAINERS UNPRIVILEGED

Each container in this manual is created unprivileged. The box stays ticked in the wizard (see Ch. 10 · The container wizard). This maps the root user of the container to a harmless user without root rights on the host. If an attacker breaks out of a container, the attacker does not get root over your whole server. It costs nothing. It is the biggest reason why a broken app stays a broken app and does not become a broken server. Leave the box ticked. Every guide here depends on it.

ONE FRONT DOOR, THEN CLOSE THE SIDE DOORS

You build Nginx Proxy Manager (CT 103, see Ch. 17 · Nginx Proxy Manager), so that services get real names and HTTPS. But a reverse proxy protects you only if it is the only way in. If not, the raw IP:port stays open next to it. Use NPM to reach sensitive dashboards. Or make them Tailscale-only (see Ch. 19 · Remote access: Tailscale).

This manual does not turn on the Proxmox firewall on purpose. On a home network, it is mostly one more way to lock yourself out of the web page. Each service here already has its own login. This is why "turn on the login at once", above, is a rule and not a suggestion. So assume that anything on your network can still reach the raw IP:port of a container. Treat the login of each app as the real lock. Do not treat the network as the lock.

You want to close the side doors anyway? The switch is at Datacenter → Firewall. Know first what the Proxmox documentation says. When you turn the firewall on, Proxmox still allows the web page (port 8006), SSH (port 22), and the console from the local network of the server. So a PC on the same network does not lose access. A PC on another network does lose access. For example, a PC that you reach through a VPN is on another network. Everything else that you did not allow is refused. This includes your own browser, if it is not on the local network. The safe order is to write the rules that keep your way in first. Turn the firewall on after that.

Start by finding the address of your own PC on the network. The rules will let this address through. On Windows, open Command Prompt and type ipconfig. Read the IPv4 Address line. It looks like 192.168.1.42. On a Mac, it is in System Settings → Network → Wi-Fi → Details. On a Linux desktop, type ip a in a terminal. The list of connected devices in your router also shows the same number.

1. In the Proxmox tree, select Datacenter. Then select Firewall. You see the rule list. The firewall is still off. This is what you want while you write rules.
2. Select Add. Set Direction to in. Set Action to ACCEPT. Set Protocol to tcp. Set Source to the address of your PC from above. Set Dest. port to 8006. This is the port of the Proxmox web page. Select Add.
3. Do it again for SSH. Use the same fields and the same source. Set Dest. port to 22.
4. Check the rule list. It must show both lines, and the Enable box of each line must be ticked. A rule that is in the list but not enabled does nothing.
5. Now turn the firewall on. Go to Datacenter → Firewall → Options. Select the Firewall row. Select Edit. Tick Yes. Confirm.
6. Test it in the same minute, from the same PC. Reload https://192.168.1.220:8006. The page answers? Then you are still in, and the rules work.

None of this means that you open a port to the internet. The rule "no port forwarding" in Ch. 5 · Safety rules & passwords stays. For the SSH side door in particular, Ch. 73 · fail2ban bans an address after many failed logins. A guessing attack then gives up early.

UPDATES — PIN, AND PREFER NOTIFY OVER AUTO

Suppose you pull :latest automatically and without watching. One bad image from the maker can then break a service overnight. Pin the image versions where you can. Set the updater to monitor-only for anything that holds data. A monitor-only updater sends you a message, and you apply the update by hand. Update automatically only the disposable stateless containers. These are containers that hold no data of their own. You can wipe one and start it again, and you lose nothing that you would miss. Ch. 72 · Update notifications has the full setup, including a monitor-only updater that notifies you. The monthly update habit is rule three in Ch. 5 · Safety rules & passwords.

CAP THE LOGS

mkdir -p /etc/docker
echo '{ "log-driver":"json-file", "log-opts":{"max-size":"10m","max-file":"3"} }' > /etc/docker/daemon.json
systemctl restart docker          # logs now cap at 10m x 3 files per container

AFTER EVERY BUILD

Every guide in this manual ends the same way. When an app answers in the browser, run this short routine before you continue. It takes two minutes. It protects you from a container that dies quietly while nobody watches.

1. Select the container in the left tree. Open its Summary tab. Find the Notes panel. Select the pencil icon. Paste in the reference card of the guide. It has the address of the app and its few upkeep commands. The notes stay with the container. Next time that you need them, they are one click away. They are not lost in a browser tab.

   

2. Add an Uptime Kuma monitor that checks the app on a timer. You then catch a failure when it happens. Ch. 14 · Uptime Kuma shows how. Do this only when those chapters exist on your server. This page is the routine for every build. In the first builds, you do not have Ch. 14 · Uptime Kuma or Ch. 18 · Homarr dashboard yet. The build order builds them later in Part C. Skip each step whose app you did not build yet. Come back to it later. The app that you just built works without these steps.
3. Attach your ntfy notification to that monitor. The alert then reaches your phone. It is not only a red dot on a page that you do not look at. You set up ntfy first, in Ch. 13 · ntfy. So each monitor that you add from now on can send to it at once.
4. Add a tile for the app on your dashboard. You then have one page with links to everything. Ch. 18 · Homarr dashboard explains this.
5. Take a snapshot now that the container works (section below). It is your one-click undo for the next risky change.

OPEN A TERMINAL

1. To get a terminal on the host itself: select homelab in the tree. Select >_ Shell at the top right.

   

2. To get a terminal inside a container: in that host Shell, run pct enter 101. Use the ID of the container. It puts you inside as root. No password is needed. Type exit to go back to the host.

   

The host Shell needs no password. You are already logged in to Proxmox. pct enter needs none too. Only opening the Shell is a button. What you type in it is still a command line. This manual shows you each line. Ch. 10 · The container wizard explains how to give the Console a password, if you ever want it. Nothing here needs it.

START, STOP, OR RESTART A CONTAINER

pct start 101     # start container 101
pct shutdown 101  # graceful stop
pct stop 101      # hard stop
pct reboot 101    # stop then start

TAKE A SNAPSHOT BEFORE A RISKY CHANGE

pct snapshot 101 before-update    # take it
pct rollback 101 before-update    # go back to it
pct delsnapshot 101 before-update # remove it

GIVE A CONTAINER MORE DISK, CPU, OR MEMORY

Select the container. Then select Resources. All the limits are in this one panel.

1. More disk: select the Root Disk row → Volume Action → Resize. In Size Increment (GiB), type how many GiB to add. Do not type the new total. Select Resize disk. A disk can only grow. It can never shrink.

   

2. More CPU: select the Cores row → Edit → set the number → OK. It takes effect live.

   

3. More memory: select the Memory row → Edit → set the MiB → OK. It takes effect live. The same dialog has Swap. Leave Swap as it is.

   

Prefer the terminal? — the same task from the host Shell

pct resize 101 rootfs +8G   # add 8 GiB of disk
pct set 101 -cores 4         # set the CPU-core ceiling
pct set 101 -memory 4096     # set the memory ceiling, in MiB

RESTORE A CONTAINER FROM A BACKUP

A container is broken, or you want it back exactly as it was? Restore one of the backups that your backup job made. You built that job in Ch. 20 · Backups before apps. Ch. 64 · Backups done right (3-2-1) goes deeper.

1. In the left tree, select the backup storage. Then select its Backups tab.

   

2. Select the backup that you want. The names have the date. Select Restore.
3. In the dialog, set Storage to local-lvm. This is where the disk of the container lives. If you moved container disks to a real drive, use that drive. Check the CT number. Keep the same number to overwrite the container. Type a free number to restore it next to the old one.
4. Set Privilege Level. It is a row of three choices. It is not a tick box. A privileged container can reach the host machine more directly. This is a bigger security risk if that container is ever attacked. So From Backup is the safe default. It keeps the setting that the container already had. Use it in almost every case. Unprivileged and Privileged force one or the other. Pick one of them only if a guide tells you to.

   

5. Select Restore and confirm. It restores to the same ID? Then it replaces the current container.

ADD A DRIVE AS STORAGE

Method A — a blank whole disk, in one action. This is the quickest way to turn a blank disk into usable Proxmox storage. One wizard formats the disk, mounts it, registers it, and sets the safety flag is_mountpoint for you. This flag stops Proxmox from writing to the wrong place if the drive is ever unplugged. You type no command.

1. Select homelab in the tree. Then select Disks. The panel lists each drive in the server with its size and its use.

   

2. The disk shows an old filesystem? Select its row. Select Wipe Disk. Confirm. This erases the disk.

   

3. A later step says that the disk has no partition table? Select the row. Select Initialize Disk with GPT. It acts at once, with no dialog. The button is grey when the disk already has a table.

   

4. Under Disks, open Directory. Select Create: Directory. Pick the Disk, for example /dev/sda. Set Filesystem to ext4. Give it a Name, for example storage. Leave Add Storage ticked. Select Create.

   

5. Done. It appears as a storage with that name at /mnt/pve/<name>. It is mounted automatically at each start. At first, it allows every content type. To limit it, go to Datacenter → Storage. Select it. Select Edit. Open the Content list. It is a dropdown with tick boxes. Tick what the drive can hold. Untick the rest.

   

Method B — a drive that is already formatted and mounted. Use this after the command-line steps in Ch. 65 · Add an external drive, or to register an existing mount again.

1. Go to Datacenter → Storage → Add → Directory.
2. Set ID to a short name, for example backups. Set Directory to the mount path, for example /srv/backups.

   

3. Open Content. Tick what the drive can hold. For a backup drive, tick only Backup. For a data drive, tick Disk image and Container.
4. Select Add.

One safety flag, is_mountpoint, has no field in this dialog. In this Proxmox version, the web page cannot finish the job. This one line in the host >_ Shell sets it.

pvesm set backups --is_mountpoint 1

The flag makes Proxmox refuse to write when the drive is not mounted. Without it, Proxmox fills the SSD in silence with copies that protect nothing.

MOVE YOUR BACKUP JOB TO THE DRIVE

1. Go to Datacenter → Backup. Select the row of your weekly job. Select Edit. The dialog opens on its General tab.
2. Change Storage from local to your backup drive, for example backups. Only a storage that allows the Backup content type is in this list. This is why the drive section above came first. Leave Schedule and Selection mode as you set them in Ch. 20 · Backups before apps: weekly, all guests.
3. Set Mode to Snapshot. It backs up without a stop of the container. Set Compression to ZSTD. It compresses well and does not make the backup much slower. Leave the other options in that dropdown alone. Both fields are on the same General tab.

   

4. Open the Retention tab. Raise Keep Last from 2 to 5. The drive has room that the SSD did not have. Keep Keep all backups unticked. Select OK.

   

5. Run it one time now against its new home. Select the job. Select Run now. Watch it under Datacenter → Backup or in the Task History of the container. The job list has no result column. The task log is where you read the result.

   

MOVE A FILE TO OR FROM THE SERVER

Sooner or later a chapter asks you to put a file on the server. It can be a document for Paperless, a video for Fireshare, or a world save for a game server. This is the one method that works for all of them. It needs no terminal. Each container speaks SSH. A graphical file manager can open an SSH location like a normal folder. You drag files in and out, the same way as with a USB stick.

1. Find the address of the container. It is on the spec plate at the top of the chapter of the app, for example 192.168.1.229.
2. On Windows: install WinSCP (free). Select New Site. Keep the protocol SFTP. Type the address of the container as Host name. Type root as user name. Select Advanced → SSH → Authentication. Point Private key file at the key that you made in Ch. 9 · SSH & the terminal. WinSCP offers to convert it. Accept. Save. Select Login.
3. On a Mac: Finder cannot open SFTP locations. Install Cyberduck (free). Select Open Connection. Set the type to SFTP (SSH File Transfer Protocol). Type the address of the container as Server. Type root as user name. Under SSH Private Key, choose the key that you made in Ch. 9 · SSH & the terminal. Select Connect.
4. On a Linux desktop: you install nothing. In the file manager, press Ctrl+L. Type sftp://root@192.168.1.229. The address of the container comes after the @. Bookmark it (“Add to Places”). The next time is one click.
5. A window opens with the folders of the container. Drag files in. Drag files out. Double-click to edit. The chapter that sent you here tells you the exact folder where the file must go.

The same method reaches the Proxmox host itself. This is the machine homelab. It is not a container. Some chapters send you here for that. The steps above are the same. Only the address differs. Use root@192.168.1.220 and not the IP of a container. Use the same key that you installed for the host in Ch. 9 · SSH & the terminal.

CHANGE A SETTING ON A DOCKER APP

Many apps in this manual take their settings as extra lines in the docker run command that made them. These lines look like -e NAME=value. Each line is one setting that you give to the app when it starts. One catch surprises everyone one time: to change a setting, you delete the container of the app and create it again with the changed command. A plain restart does not apply a changed -e line.

This sounds destructive. It is not. Your data is not inside the part that you delete. Look at the docker run command of the app. The lines that start with -v plug real folders of the container disk into the app. When you delete the container of the app, those folders stay. The new app finds everything where it was.

1. Open the chapter of the app. Find its docker run command. Copy it to a place where you can edit it. Make your change: add or edit the -e line that you need.
2. Open the shell of the container: homelab → >_ Shell. Then run pct enter 101 (the number of your container).
3. Stop the running app and remove it. Then run your edited command.

docker stop appname            # the app's name — the --name part of its docker run command
docker rm appname              # removes the old container; your data folders stay

4. Paste your edited docker run command from step 1. Run it.
5. Check that it came back. docker ps lists it. After a moment, the web page of the app answers again. It is not in the list? Run docker logs appname --tail 50 to see why it did not start. Ch. 70 · When it breaks: troubleshooting has more.

CREATE THE CONTAINER

Do this task with the mouse in the Proxmox web page. You type nothing. You prefer the command line? The Prefer the terminal? box below does the same task with one pct create command.

1. Open https://192.168.1.220:8006.
2. Click homelab in the left tree.
3. Click the blue Create CT button at the top right.
4. Fill in the tabs as the wizard reference shows. Leave each field that is not listed at its default value.
5. Keep Start after created unticked.

Wizard reference — Create CT 106

Tab → Field	Entry
General → Node	Select homelab.
General → CT ID	Type 106. Do not keep the number that the wizard suggests.
General → Hostname	Type ntfy.
General → Unprivileged container	Keep this box ticked.
General → Nesting	Keep this box ticked. It is ticked by default. The wizard has no box for keyctl, which Docker also needs. The host command after Finish sets it. It is the first line of the next listing.
General → Password / SSH public key	Keep the password empty. Paste your public key in the SSH field: ssh-ed25519 AAAA…your-key-here you@your-pc. With the key, you can run ssh root@192.168.1.227 from your PC. The command pct enter 106 on the host needs no password.
Template → Storage, Template	Select local. Then select debian-13-standard.
Disks → Storage, Disk size	Select local-lvm. Set 6 GiB.
CPU → Cores	Set 1 core.
Memory → Memory (MiB)	Set 1024. Keep Swap at its default.
Network → IPv4	Select Static. Set IPv4/CIDR to 192.168.1.227/24. Set Gateway to 192.168.1.1. Keep IPv6 at its default.
DNS → DNS domain	Keep this field empty. Do not type 192.168.1.1 here.
DNS → DNS servers	Always type 192.168.1.1. Never keep this field empty.
Confirm	Read the summary. Keep Start after created unticked. Select Finish.

What each field does: see Ch. 10 · The container wizard, section "Work through the eight tabs".

The wizard has no box for three settings: the Docker permission keyctl, the timezone, and start at boot. The first command below sets all three. Run these 3 commands on the host. They set the missing settings, start the container, and open its shell. Each part is explained in Ch. 10 · The container wizard, section "The host command every build needs".

pct set 106 --features nesting=1,keyctl=1 --onboot 1 --timezone host
pct start 106
pct enter 106                          # now INSIDE CT 106 — the rest of this page runs here

TMPL=$(pveam available --section system | awk '/debian-13-standard/{print $2}' | tail -1)
pveam download local "$TMPL"          # once per host; harmless to re-run
pct create 106 local:vztmpl/"$TMPL" \
  --hostname ntfy --cores 1 --memory 1024 --rootfs local-lvm:6 \
  --net0 name=eth0,bridge=vmbr0,ip=192.168.1.227/24,gw=192.168.1.1 \
  --nameserver 192.168.1.1 --features nesting=1,keyctl=1 --unprivileged 1 --onboot 1 --timezone host
pct start 106
pct enter 106                      # you are now INSIDE CT 106 — everything below runs here

BUILD

This part has no buttons. These commands run inside CT 106. In the host Shell (homelab → >_ Shell), run pct enter 106. You are already inside from the step above? Then continue. Run each command inside CT 106. Do not run these commands on the Proxmox host or on your PC. Docker does not start? See the entry about Docker in WHEN IT GOES WRONG below.

apt update && apt install -y docker.io curl
docker run -d --name ntfy --restart=unless-stopped -p 80:80 \
  -v /opt/ntfy:/var/cache/ntfy -e NTFY_BASE_URL=http://192.168.1.227 \
  -e NTFY_CACHE_FILE=/var/cache/ntfy/cache.db \
  -e NTFY_AUTH_FILE=/var/cache/ntfy/auth.db -e NTFY_AUTH_DEFAULT_ACCESS=deny-all \
  binwiederhier/ntfy serve
# stop here — the next three commands are interactive or need a value you do not have yet

Notice — the next commands stop and ask you things

Do not paste these as one block. The first command asks you to type a password and waits. It swallows anything that you pasted after it. Run them one at a time.

docker exec -it ntfy ntfy user add --role=admin you

docker exec -it ntfy ntfy token add you

Notice — copy the token before the next line

That command printed a long token. It starts with tk_. Select it and copy it now. The next command writes it to a file exactly as you type it. Suppose you paste the line below without a change. Then you save the six characters tk_... and not your token. Each later alert fails with a 403. Nothing on your phone tells you.

mkdir -p /opt/ntfy && echo "NTFY_TOKEN=tk_YOUR-TOKEN" > /opt/ntfy/.env && chmod 600 /opt/ntfy/.env

Explanation of each part

The Docker install line and the flags -d, --name, --restart, -v, and -p are explained in Ch. 9 · SSH & the terminal, sections "Install Docker in the container" and "Anatomy of docker run". These parts are specific to ntfy:

-p 80:80

Sends port 80 of the container to port 80 of the app. This is the web page and the API of ntfy.

-v /opt/ntfy:/var/cache/ntfy

Links a host folder for the cache and the database files of the app. They stay after a restart.

-e NTFY_BASE_URL=http://192.168.1.227

Tells the app the web address where it can be reached. ntfy uses this address when it builds links in notifications.

-e NTFY_CACHE_FILE=/var/cache/ntfy/cache.db

Sets the file path, inside the container, where sent messages are cached.

-e NTFY_AUTH_FILE=/var/cache/ntfy/auth.db

Sets the file path where user accounts and permissions are stored.

-e NTFY_AUTH_DEFAULT_ACCESS=deny-all

A security setting. By default, nobody can read or write topics without explicit access. This locks the server.

binwiederhier/ntfy serve

The image to run: ntfy, a simple push-notification server. The word 'serve' tells it to start the server.

docker exec -it ntfy ntfy user add --role=admin you

Runs a command inside the running 'ntfy' container. It makes a user named 'you' with admin rights. The -it flags keep the session interactive, so it can ask for a password.

docker exec -it ntfy ntfy token add you

Makes an access token inside the container. A token is a long-lived replacement for a password. It is for the user 'you'. Apps and scripts use this token to log in.

mkdir -p /opt/ntfy && echo "NTFY_TOKEN=tk_..." > /opt/ntfy/.env && chmod 600 /opt/ntfy/.env

Writes the token to a file named .env. It is in the same folder that holds the cache and the auth database of the container. It then locks the file for the owner only. Later chapters and scripts look for the token here. /opt/ntfy is a normal folder. You prefer to see or edit .env with a mouse? Open this folder over SFTP. Ch. 12 · After every build + common Proxmox tasks, section “Move a file to or from the server”, shows how.

USE IT ON YOUR PHONE

Container summary: CT 106/ntfy, 6 GiB, 1 CPU, 1024 MB, 192.168.1.227/24.

docker rm -f ntfy
docker run -d --name ntfy --restart=unless-stopped -p 80:80 \
  -v /opt/ntfy:/var/cache/ntfy -e NTFY_BASE_URL=http://192.168.1.227 \
  -e NTFY_CACHE_FILE=/var/cache/ntfy/cache.db \
  -e NTFY_AUTH_FILE=/var/cache/ntfy/auth.db -e NTFY_AUTH_DEFAULT_ACCESS=deny-all \
  -e NTFY_UPSTREAM_BASE_URL=https://ntfy.sh \
  binwiederhier/ntfy serve

1. Install the ntfy app (author: Philipp Heckel) from the Play Store, or from the App Store on an iPhone.
2. Set your server as the default server. In the app, go to ⚙ Settings → General → Default server. Enter http://192.168.1.227. Type the http:// part.
3. Store your login. Go to Settings → General → Manage users → Add. Enter the server http://192.168.1.227. Enter the user name and the password from ntfy user add (user name you, unless you chose another). The tk_… token is NOT for the phone. The token is for scripts and for the test curl below.
4. Subscribe. On the main screen, tap +. Enter the topic homelab-alerts. The default server is already selected. It is not selected? Tick Use another server and enter the address. Tap Subscribe.
5. Keep delivery reliable (Android only). A self-hosted server cannot use the push service of Google. So the app keeps a small permanent connection. The quiet “Subscription service” notification is normal. Do not remove it. Then go to Android Settings → Apps → ntfy → Battery and select Unrestricted. Without this, the battery manager delays alerts by hours. Away from home, it works when Tailscale is on.
6. Test it. The Build step already installed curl in CT 106. The shell shows curl: command not found? Then run apt install -y curl. Then replace tk_... with the real tk_... text that ntfy token add printed. To print it again at any time, run docker exec -it ntfy ntfy token list.

curl -H "Authorization: Bearer tk_..." -d "hello" http://192.168.1.227/homelab-alerts

NEXT: CONNECT IT TO UPTIME KUMA

Ch. 14 · Uptime Kuma is the next chapter. It watches each service. It must know where to send an alert when a service goes down. This ntfy server is that alert channel. You cannot set it up from here. The dashboard of Kuma does not exist yet. The Kuma chapter shows the whole notification dialog with screenshots, at the point where it works.

Take three values to that chapter: Topic homelab-alerts, Server URL http://192.168.1.227, and the tk_… token that ntfy token add printed. This is the step that the build chapter of each app means when it says “attach your ntfy notification” in its after-build checklist (Ch. 12 · After every build + common Proxmox tasks).

WHEN IT GOES WRONG

1. docker run stops with Error response from daemon: … Bind for 0.0.0.0:80 failed: port is already allocated. Another program already uses port 80 in this CT. Pick a free host port. Change -p 80:80 to -p 8080:80. Change the base URL to match: -e NTFY_BASE_URL=http://192.168.1.227:8080. Then add the server in the app, and in the curl tests, as http://192.168.1.227:8080.
2. The phone app shows a warning icon with Not authorized (401/403). Or a curl test returns HTTP 403 or a JSON error, and no notification arrives. The server uses deny-all, so it blocks anonymous access. In the app, tap the server entry. Sign in as user you with the password that you set. For curl, always send the token (-H "Authorization: Bearer tk_...") or basic auth (-u you:YOURPASSWORD).
3. curl runs without an error, but nothing reaches the phone, and docker logs ntfy shows a 401. The request had the literal text tk_.... tk_... is only a placeholder. List your real token with docker exec -it ntfy ntfy token list. It starts with tk_ and has about 30 more characters. Paste that exact text in the Authorization: Bearer header. You lost it? Make a new one with docker exec -it ntfy ntfy token add you.
4. Notifications arrive at first. Then they stop after the phone was idle for a while. Android puts the app to sleep. Keep the persistent 'instant delivery' notification of ntfy turned on. Set Android Settings → Apps → ntfy → Battery to Unrestricted. Self-hosted servers send over a direct connection, not over Google Firebase. So the app must be allowed to run in the background.

• A download step fails with Temporary failure resolving deb.debian.org, or with another "cannot resolve" message. The container has no working DNS server. It cannot change a name into an address. This is not a typing mistake. It does not fix itself. In the Proxmox page, select this container in the left tree. Open DNS. Select Edit. Type your router address in DNS servers (192.168.1.1 here; use your own). Then run pct reboot 106 in the host shell. Run the failed step again.
• A command fails. You do not know if you are on the server or in the container. Read the prompt. In the container, it ends with the name of the container. On the server, it shows root@homelab. The prompt still shows root@homelab after pct enter? Then the command did not work. Type exit. Run the pct enter line again. Check the prompt before you paste anything else. You can paste a build block on the server by mistake. It seems to work. It installs without an error, and the app even answers. But the app is on the server, and it must not be there.
• How to see that it happened, and how to undo it. The app does not open at the container address (192.168.1.227). It does open at the server address (192.168.1.220) on the same port. Then the app is on the host. To remove it, run docker rm -f ntfy in the host shell. Then run pct enter 106. Check that the prompt changed. Paste the build block again. You lose nothing in the container, because nothing was built there. The first command can show Error: No such container. This is good. It means that the app was never on the host. Do not paste the build block again. Look for another cause.
• The page does not open. The browser spins, or says it cannot connect. Do these checks in order, in the host shell. 1. Is the container running? Run pct status 106. It must say running. If it does not, run pct start 106. 2. Is the container at the address that you typed? Run pct config 106 | grep net0. It shows the real address. A wrong digit in the wizard puts the container at another address, and nothing warns you. 3. Does the app run in the container? Run pct enter 106. Then run docker ps. An empty list means that the app did not start. Run docker ps -a to see that it stopped. Run docker logs to see why. 4. Does the app answer in the container? Run curl -I http://localhost followed by the port of the app. You get a reply here, but nothing from your PC? Then the address or your own network is the problem. The app is fine. Your browser reaches 192.168.1.227 but not the port? Then the app is down. It reaches neither? Then the container is down.
• Docker does not start, or you see Cannot connect to the Docker daemon, a keyring error, or an overlay error. This is the most common failure in these guides. It means that the two container features are off. A later pct set --features can switch them off, also when you set them before. Run this in the host shell, not in the container: pct set 106 --features nesting=1,keyctl=1. Then run pct reboot 106. Then run the failed step again. Type both settings on one line. If you send only one setting, it replaces the pair and switches the other one off.

REFERENCE CARD

Paste this in the Notes of the container in Proxmox (106 → Summary → Notes). It is a reference. It is not a shell command. Before you ever run the update line on this card, compare it with the docker run you actually used at install. The card is a snapshot of the standard build: if you added anything of your own — a device, an extra -e setting, a second folder — it is not on the card, and re-running the card's line drops it. The container comes back up looking healthy with your setting gone.

## ntfy — CT 106
dashboard http://192.168.1.227 · topic homelab-alerts · token in /opt/ntfy/.env · docs https://docs.ntfy.sh/

```sh
# is it running?
docker ps --filter name=ntfy
curl -fsS http://localhost/v1/health >/dev/null && echo OK   # quick health check
# send a test push (replace tk_... with your real token)
curl -H "Authorization: Bearer tk_..." -d "test" http://192.168.1.227/homelab-alerts
# see / rotate tokens
docker exec -it ntfy ntfy token list
# logs (last 50)
docker logs ntfy --tail 50
# stop / start / restart
docker stop ntfy
docker start ntfy
docker restart ntfy
# is there an update? ("Image is up to date" = no)
docker pull binwiederhier/ntfy
# iPhone? the run line below also needs -e NTFY_UPSTREAM_BASE_URL=https://ntfy.sh
# update (accounts + token survive in /opt/ntfy)
docker pull binwiederhier/ntfy && docker rm -f ntfy && docker run -d --name ntfy --restart=unless-stopped -p 80:80 -v /opt/ntfy:/var/cache/ntfy -e NTFY_BASE_URL=http://192.168.1.227 -e NTFY_CACHE_FILE=/var/cache/ntfy/cache.db -e NTFY_AUTH_FILE=/var/cache/ntfy/auth.db -e NTFY_AUTH_DEFAULT_ACCESS=deny-all binwiederhier/ntfy serve
```

CREATE THE CONTAINER

The wizard has no box for three settings: the Docker permission keyctl, the timezone, and start at boot. The first command below sets all three. Run these 3 commands on the host. They set the missing settings, start the container, and open its shell. Each part is explained in Ch. 10 · The container wizard, section "The host command every build needs".

pct set 100 --features nesting=1,keyctl=1 --onboot 1 --timezone host
pct start 100
pct enter 100                          # now INSIDE CT 100 — the rest of this page runs here

TMPL=$(pveam available --section system | awk '/debian-13-standard/{print $2}' | tail -1)
pveam download local "$TMPL"          # once per host; harmless to re-run
pct create 100 local:vztmpl/"$TMPL" \
  --hostname kuma --cores 1 --memory 1024 --rootfs local-lvm:6 \
  --net0 name=eth0,bridge=vmbr0,ip=192.168.1.221/24,gw=192.168.1.1 \
  --nameserver 192.168.1.1 --features nesting=1,keyctl=1 --unprivileged 1 --onboot 1 --timezone host
pct start 100
pct enter 100                      # you are now INSIDE CT 100 — everything below runs here

INSTALL UPTIME KUMA

apt update && apt install -y docker.io curl
docker run -d --name uptime-kuma --restart=unless-stopped -p 3001:3001 \
  -v /opt/uptime-kuma:/app/data louislam/uptime-kuma:2

The docker run command prints an error and does not start? See the entry about Docker in WHEN IT GOES WRONG below.

ADD YOUR MONITORS — IN THE WEB PAGE OF KUMA

When you made the container, Kuma started. The purpose of Kuma is the monitors. You add them with the mouse. Open http://192.168.1.221:3001. Use the IP of the CT, 192.168.1.221. Do not use the host, 192.168.1.220. At the first visit, it asks you to make an admin user name and password.

Do that. You then see an empty dashboard. This empty dashboard is your first self-hosted app. A container that you built now serves its own web page on your network.

First, set up a notification (one time) — the default habit

This manual builds one habit: attach a notification to every monitor. A down-alert then reaches your phone as a push message. Set it up one time here. Tick it for every monitor. You then never miss an outage. You built Ch. 13 · ntfy in the previous chapter. Its server already runs. Point Kuma straight at it.

1. Go to Settings → Notifications → Setup Notification.

   

2. Set Notification Type to ntfy.
3. Set Server URL to http://192.168.1.227 (your ntfy server). Set Topic to homelab-alerts. This is the exact topic that this manual uses everywhere.
4. Set Authentication Method to Access Token. Paste the tk_… token from ntfy. The server uses deny-all, so it needs the token. You lost the token? Open a shell in CT 106 (see the "where these commands run" notice in Ch. 13 · ntfy). Run docker exec -it ntfy ntfy token list. This runs a command inside the running ntfy container and lists its tokens. Copy the tk_… line that it prints.
5. The dialog has two priority fields: Priority and Priority for DOWN-events. Both are already 5, the highest value. Leave both at 5. An outage then reaches your phone as an urgent push message.

   

6. Give it a name. Click Test. A push message arrives on your phone in a few seconds. None arrives? Check the token first.
7. Tick Default enabled and Apply on all existing monitors. This makes each future monitor alert your phone by itself. This is the whole point of the habit.

   

8. Click Save.

Kuma now pushes to your phone through ntfy each time that a service goes down or comes back. You already subscribed the ntfy phone app to the topic homelab-alerts in the previous chapter. So each homelab alert arrives there.

Add a monitor

Click the green Add New Monitor button (top left). These are the fields that matter:

• Monitor Type — the KIND of check (see the table below).
• Friendly Name — the label on your dashboard. Example: Proxmox (homelab).
• The address — a URL for an HTTP check. A Hostname and a Port for the other types.
• Heartbeat Interval — how often to check. 60 seconds is a good value. Use 20 seconds for a service that is important to you.
• Under Notifications, tick your ntfy notification (or Discord). This monitor then really alerts your phone. Make this tick a habit for each monitor that you add.

  

Then click Save. Kuma starts the check at once. The tile turns green when the target answers.

The monitor types that you use

A good starter set for this homelab

Add these five to start. They answer three questions: is the server up, is the game up, and are the remote services up.

WHEN IT GOES WRONG

• You forgot the admin password of Uptime Kuma, and you are locked out of http://192.168.1.221:3001. Inside CT 100, run docker exec -it uptime-kuma npm run reset-password. This opens an interactive prompt inside the running container. Follow the prompts to set a new password. You lose no data. This is the official recovery command of Uptime Kuma.
• The 'Test' button of Discord or ntfy works, but real down-alerts never arrive. You made the notification, but you did not attach it to any monitor. Edit each monitor. Tick its box under Notifications. Or, when you make the notification, turn on 'Default enabled' and 'Apply on all existing monitors'.
• http://192.168.1.221:3001 does not load right after you start the container. At the first start, Uptime Kuma builds its database. This takes about 30 to 60 seconds. Wait. Then run docker logs uptime-kuma --tail 50. Look for a line about listening on port 3001. Make sure that you use the IP of the CT, 192.168.1.221, and not the host, 192.168.1.220.
• A GameDig monitor for Palworld shows 'Down', but the server runs. In our test, GameDig could not read Palworld. Monitor Palworld with a Ping on its IP. Minecraft supports queries. For Minecraft, turn the query on and use the query port.

• A download step fails with Temporary failure resolving deb.debian.org, or with another "cannot resolve" message. The container has no working DNS server. It cannot change a name into an address. This is not a typing mistake. It does not fix itself. In the Proxmox page, select this container in the left tree. Open DNS. Select Edit. Type your router address in DNS servers (192.168.1.1 here; use your own). Then run pct reboot 100 in the host shell. Run the failed step again.
• A command fails. You do not know if you are on the server or in the container. Read the prompt. In the container, it ends with the name of the container. On the server, it shows root@homelab. The prompt still shows root@homelab after pct enter? Then the command did not work. Type exit. Run the pct enter line again. Check the prompt before you paste anything else. You can paste a build block on the server by mistake. It seems to work. It installs without an error, and the app even answers. But the app is on the server, and it must not be there.
• How to see that it happened, and how to undo it. The app does not open at the container address (192.168.1.221). It does open at the server address (192.168.1.220) on the same port. Then the app is on the host. To remove it, run docker rm -f uptime-kuma in the host shell. Then run pct enter 100. Check that the prompt changed. Paste the build block again. You lose nothing in the container, because nothing was built there. The first command can show Error: No such container. This is good. It means that the app was never on the host. Do not paste the build block again. Look for another cause.
• The page does not open. The browser spins, or says it cannot connect. Do these checks in order, in the host shell. 1. Is the container running? Run pct status 100. It must say running. If it does not, run pct start 100. 2. Is the container at the address that you typed? Run pct config 100 | grep net0. It shows the real address. A wrong digit in the wizard puts the container at another address, and nothing warns you. 3. Does the app run in the container? Run pct enter 100. Then run docker ps. An empty list means that the app did not start. Run docker ps -a to see that it stopped. Run docker logs to see why. 4. Does the app answer in the container? Run curl -I http://localhost followed by the port of the app. You get a reply here, but nothing from your PC? Then the address or your own network is the problem. The app is fine. Your browser reaches 192.168.1.221 but not the port? Then the app is down. It reaches neither? Then the container is down.
• Docker does not start, or you see Cannot connect to the Docker daemon, a keyring error, or an overlay error. This is the most common failure in these guides. It means that the two container features are off. A later pct set --features can switch them off, also when you set them before. Run this in the host shell, not in the container: pct set 100 --features nesting=1,keyctl=1. Then run pct reboot 100. Then run the failed step again. Type both settings on one line. If you send only one setting, it replaces the pair and switches the other one off.

REFERENCE CARD

Paste this in 100 → Summary → Notes. The essentials then stay with the container. Before you ever run the update line on this card, compare it with the docker run you actually used at install. The card is a snapshot of the standard build: if you added anything of your own — a device, an extra -e setting, a second folder — it is not on the card, and re-running the card's line drops it. The container comes back up looking healthy with your setting gone.

## Uptime Kuma — CT 100
dashboard http://192.168.1.221:3001 · docs https://github.com/louislam/uptime-kuma/wiki

```sh
# is it running?
docker ps --filter name=uptime-kuma
curl -fsS http://localhost:3001 >/dev/null && echo OK   # quick health check
# logs (last 50)
docker logs uptime-kuma --tail 50
# stop / start / restart
docker stop uptime-kuma
docker start uptime-kuma
docker restart uptime-kuma
# is there an update? ("Image is up to date" = no)
docker pull louislam/uptime-kuma:2
# update (settings survive in /opt/uptime-kuma)
docker pull louislam/uptime-kuma:2 && docker rm -f uptime-kuma && docker run -d --name uptime-kuma --restart=unless-stopped -p 3001:3001 -v /opt/uptime-kuma:/app/data louislam/uptime-kuma:2
```

INSTALL THE HUB

Beszel has two parts. The hub is the dashboard and its database. An agent is one small program on each machine that you want to watch. Run the hub inside CT 100. This is the same container as Ch. 14 · Uptime Kuma. It sits next to Kuma and uses almost nothing.

This is the one planned exception to the rule one service, one container of this manual (Ch. 7 · The build order). These two small monitoring tools use almost no CPU or memory, so they share one box. Each other service in this manual still gets its own container.

This part has no buttons. These commands run inside CT 100. In the host Shell (homelab → >_ Shell), run pct enter 100. You are still inside from the previous section? Then continue.

docker run -d --name beszel --restart=unless-stopped -p 8090:8090 \
  -v /opt/beszel:/beszel_data henrygd/beszel:latest

ADD THE FIRST MACHINE — CT 100 ITSELF

Each agent reads the stats of its host. It sends them to the hub. Start with the machine that already has Docker: CT 100, the box where the hub runs. Its agent mounts the Docker socket. This is a special file that Docker uses to answer the question "which containers run now?". So the agent also draws a graph for each container on the box.

1. Open the hub at http://192.168.1.221:8090.
2. Make the admin account at the first visit.
3. Click Add System. Open the Docker tab. The hub prints the exact beszel-agent command, with the key and the token already filled in.
4. Inside CT 100, paste that docker run command as it is. It reports the stats of the container itself. Through the mounted Docker socket, it also reports each container that runs on it.
5. Next, add the whole server, the Proxmox host, in the section below. That uses the native agent of Beszel, because the manual does not install Docker on the hypervisor.

Notice — adding your PC is optional

You can also watch your own PC. But only if it already runs Docker Desktop. Paste the same docker run line there. The manual never installs Docker on your PC. You do not have Docker Desktop? Then use the native agent installer of Beszel for your operating system (the Binary tab in Add System), exactly as the server host does below.

# copy the EXACT line the hub's "Add System" box gives you — it fills in
# KEY, TOKEN and HUB_URL. Roughly the shape:
docker run -d --name beszel-agent --restart=unless-stopped --network host \
  -v /var/run/docker.sock:/var/run/docker.sock:ro \
  -e KEY="<the key the hub shows>" \
  -e TOKEN="<the token the hub shows>" \
  -e HUB_URL="http://192.168.1.221:8090" \
  -e LISTEN=45876 henrygd/beszel-agent:latest

ADD THE SERVER HOST

Do not install Docker on the hypervisor. Use the binary agent of Beszel on the Proxmox host instead.

1. In the Proxmox web page at https://192.168.1.220:8006, click the node homelab in the left tree. Then click >_ Shell. This opens a shell on the host itself, in the browser.
2. In the hub, open Add System. Click the Binary tab. Copy the whole line. It already has your key and token.
3. root is the account with full rights on a machine. The shell of the Proxmox host already logs you in as root. So you never type sudo here. Paste the line and run it.
4. It asks if you want automatic daily updates. Type y and press Enter.

Prefer the terminal? — SSH instead of the web Shell

You can also reach the host with ssh root@192.168.1.220. Use it in place of the web >_ Shell. It is the same shell. The command below is the same.

curl -sL https://get.beszel.dev -o /tmp/install-agent.sh && chmod +x /tmp/install-agent.sh && \
  /tmp/install-agent.sh -k "<the key the hub shows>" -t "<the token the hub shows>" -url "http://192.168.1.221:8090"

HOW TO USE IT — THE BASICS

Read the graphs. Then let alerts watch the machines for you.

1. Open http://192.168.1.221:8090. Sign in with the admin account. The front page is a table of all machines with live CPU, memory, and disk numbers.
2. Click the name of a system to open its full dashboard. You see graphs for CPU, memory, disk, network, and temperature. The agent can see Docker? Then it also shows a graph for each container.
3. Use the time-range picker at the top. It goes from the last hour to the last 30 days. It shows if a load is a short spike or the new normal.
4. Go back to the systems table. Click the bell icon on a row. Turn on Status to get a message when the machine goes down. Set limits for values such as CPU or disk. Each alert has one slider for the percentage and one slider for the minutes that it must stay above it.
5. To copy the same limits to every machine, pick All Systems in the bell dialog. Tick Overwrite existing alerts.
6. Add a channel under Settings → Notifications. Beszel sends alerts to URLs of a standard format. It supports email and many services, also ntfy. For your ntfy server, type the URL below in the URL box. Replace tk_YOUR-TOKEN with your real token (see Ch. 13 · ntfy). Keep the colon before the token. Keep ?scheme=http, because your server uses plain HTTP, and Beszel uses HTTPS if you leave it out. Then press Test URL and check that the message arrives on your phone. An alert channel that you did not test is the same as no alert channel. Without a channel, alerts show only inside the dashboard.

ntfy://:tk_YOUR-TOKEN@192.168.1.227/homelab-alerts?scheme=http

Notice — a different token format, if the first one fails

The Beszel documentation gives a second format for the case that the first one does not work: generic+http://192.168.1.227/homelab-alerts?@authorization=Bearer+tk_YOUR-TOKEN. Try it if Test URL reports a failure. The email option also works.

WHEN IT GOES WRONG

• An added machine stays grey or red and never turns green (the agent is "not connecting"). With the commands of this chapter, the agent makes an outgoing connection to the hub. It uses HUB_URL. Check that the agent machine can reach the hub address, and that the TOKEN is the one that the hub shows. The old SSH method works the other way. There, the hub connects to port 45876 on the agent machine, and that port must be open.
  Prefer the terminal? — test reachability, and open the port for the SSH method

  From the agent machine, test the hub with curl -I http://192.168.1.221:8090. For the SSH method on a Linux agent with ufw, run sudo ufw allow 45876/tcp. With firewalld, run sudo firewall-cmd --permanent --add-port=45876/tcp && sudo firewall-cmd --reload. To test a port from inside CT 100, run nc -vz followed by the address and the port, for example nc -vz 192.168.1.50 45876. Use the own IP of the agent. 192.168.1.50 is your PC (example). Do not use telnet. The Debian template of this manual does not include it, and you only get command not found. The system stays grey after that? Do not look through the network settings by hand. Make the agent again with the exact command that the Add System screen of the hub shows you now. Remove the old one first: docker rm -f beszel-agent. Then paste the fresh docker run command from the hub.

• The agent process runs, but the system does not connect after you filled in its details by hand in "Add System". In the Add System dialog, the Host / IP field must be the address of the agent machine. This is your PC (example) 192.168.1.50 or the Proxmox host 192.168.1.220. It is not the hub itself, 192.168.1.221. Leave the Port field at 45876. This is the LISTEN value of the agent.
• The machine connects and shows CPU and RAM, but its Docker containers panel is empty. The agent needs read access to the Docker socket. Check that its docker run has -v /var/run/docker.sock:/var/run/docker.sock:ro.
  Prefer the terminal? — make the agent again with the socket mounted

  You started it without that line? Make it again. Run docker rm -f beszel-agent. Then run the full agent command again, with the mount in it.

• Disk use shows 0% or an obviously wrong number. This is common for the binary agent on the host or inside a container. Tell the agent which device is the root disk. Run df -h / (or lsblk). Note the device, for example /dev/sda2.
  Prefer the terminal? — set the FILESYSTEM variable

  For the binary agent on the host, open its service file with nano /etc/systemd/system/beszel-agent.service. You need no sudo. The Proxmox host shell already logs you in as root. Arrow down into the [Service] block. Type a new line: Environment="FILESYSTEM=/dev/sda2". Save and exit (Ctrl-O, Enter, Ctrl-X). You prefer a graphical editor? Open the same file over SFTP instead. See Ch. 12 · After every build + common Proxmox tasks, section "Move a file to or from the server". Then go back to the terminal for the last command. It has no button: systemctl daemon-reload && systemctl restart beszel-agent. For a Docker agent, add -e FILESYSTEM=/dev/sda2. Make the container again in the same way as above.

• The page http://192.168.1.221:8090 shows nothing, or does not load. Check that the hub container is up inside CT 100. docker ps must list beszel. It is not there? Read docker logs beszel --tail 50. Open the page from a device on the same 192.168.1.x network (or over Ch. 19 · Remote access: Tailscale). Make sure that you typed http:// and not https://. The hub serves plain HTTP on port 8090 by default.

• A download step fails with Temporary failure resolving deb.debian.org, or with another "cannot resolve" message. The container has no working DNS server. It cannot change a name into an address. This is not a typing mistake. It does not fix itself. In the Proxmox page, select this container in the left tree. Open DNS. Select Edit. Type your router address in DNS servers (192.168.1.1 here; use your own). Then run pct reboot 100 in the host shell. Run the failed step again.
• A command fails. You do not know if you are on the server or in the container. Read the prompt. In the container, it ends with the name of the container. On the server, it shows root@homelab. The prompt still shows root@homelab after pct enter? Then the command did not work. Type exit. Run the pct enter line again. Check the prompt before you paste anything else. You can paste a build block on the server by mistake. It seems to work. It installs without an error, and the app even answers. But the app is on the server, and it must not be there.
• How to see that it happened, and how to undo it. The app does not open at the container address (192.168.1.221). It does open at the server address (192.168.1.220) on the same port. Then the app is on the host. To remove it, run docker rm -f beszel in the host shell. Then run pct enter 100. Check that the prompt changed. Paste the build block again. You lose nothing in the container, because nothing was built there. The first command can show Error: No such container. This is good. It means that the app was never on the host. Do not paste the build block again. Look for another cause.
• The page does not open. The browser spins, or says it cannot connect. Do these checks in order, in the host shell. 1. Is the container running? Run pct status 100. It must say running. If it does not, run pct start 100. 2. Is the container at the address that you typed? Run pct config 100 | grep net0. It shows the real address. A wrong digit in the wizard puts the container at another address, and nothing warns you. 3. Does the app run in the container? Run pct enter 100. Then run docker ps. An empty list means that the app did not start. Run docker ps -a to see that it stopped. Run docker logs to see why. 4. Does the app answer in the container? Run curl -I http://localhost followed by the port of the app. You get a reply here, but nothing from your PC? Then the address or your own network is the problem. The app is fine. Your browser reaches 192.168.1.221 but not the port? Then the app is down. It reaches neither? Then the container is down.
• Docker does not start, or you see Cannot connect to the Docker daemon, a keyring error, or an overlay error. This is the most common failure in these guides. It means that the two container features are off. A later pct set --features can switch them off, also when you set them before. Run this in the host shell, not in the container: pct set 100 --features nesting=1,keyctl=1. Then run pct reboot 100. Then run the failed step again. Type both settings on one line. If you send only one setting, it replaces the pair and switches the other one off.

REFERENCE CARD

Paste this in Proxmox under 100 → Summary → Notes. It is a note for your future self. It is not a shell command. The hub is a Docker container. The agent of the server is a normal installed program. You start and stop it with systemctl. Before you ever run the update line on this card, compare it with the docker run you actually used at install. The card is a snapshot of the standard build: if you added anything of your own — a device, an extra -e setting, a second folder — it is not on the card, and re-running the card's line drops it. The container comes back up looking healthy with your setting gone.

## Beszel — hub (Docker, CT 100) + agents
dashboard http://192.168.1.221:8090 · docs https://beszel.dev/guide/getting-started

```sh
# --- HUB: Docker container inside CT 100 ---
# is it running?
docker ps --filter name=beszel
curl -fsS http://localhost:8090 >/dev/null && echo OK   # quick health check
# logs (last 50)
docker logs beszel --tail 50
# stop / start / restart
docker stop beszel
docker start beszel
docker restart beszel
# is there an update? ("Image is up to date" = no)
docker pull henrygd/beszel:latest
# update (data survives in /opt/beszel)
docker pull henrygd/beszel:latest && docker rm -f beszel && docker run -d --name beszel --restart=unless-stopped -p 8090:8090 -v /opt/beszel:/beszel_data henrygd/beszel:latest

# --- AGENT on the server: native binary (systemd) ---
systemctl status beszel-agent
journalctl -u beszel-agent -n 50 --no-pager
systemctl restart beszel-agent
# update (daily auto-update was enabled at install; to force one now)
/opt/beszel-agent/beszel-agent update && systemctl restart beszel-agent

# --- AGENT in a Docker container (your PC, or CT 100 itself) ---
docker restart beszel-agent
docker logs beszel-agent --tail 50
```

CREATE THE CONTAINER

You do this task with the mouse, in the Proxmox web page. You type nothing. You prefer the command line? The box below does the same task with one pct create command.

1. On your PC, open https://192.168.1.220:8006.
2. Click homelab in the left tree.
3. Click the blue Create CT button at the top right.
4. Fill in the tabs as the table shows. Keep each field that is not listed at its default value.

What each field does: see Ch. 10 · The container wizard, section "Work through the eight tabs".

The wizard has no box for three settings: the Docker permission keyctl, the timezone, and start at boot. The first command below sets all three. Run these 3 commands on the host. They set the missing settings, start the container, and open its shell. Each part is explained in Ch. 10 · The container wizard, section "The host command every build needs".

pct set 102 --features nesting=1,keyctl=1 --onboot 1 --timezone host
pct start 102
pct enter 102                          # now INSIDE CT 102 — the rest of this page runs here

TMPL=$(pveam available --section system | awk '/debian-13-standard/{print $2}' | tail -1)
pveam download local "$TMPL"          # once per host; harmless to re-run
pct create 102 local:vztmpl/"$TMPL" \
  --hostname adguard --cores 1 --memory 1024 --rootfs local-lvm:6 \
  --net0 name=eth0,bridge=vmbr0,ip=192.168.1.223/24,gw=192.168.1.1 \
  --nameserver 192.168.1.1 --features nesting=1,keyctl=1 --unprivileged 1 --onboot 1 --timezone host
pct start 102
pct enter 102                      # you are now INSIDE CT 102 — everything below runs here

INSTALL ADGUARD

This part has no buttons. These commands run inside CT 102. In the host Shell (homelab → >_ Shell), run pct enter 102. You are still inside from the previous section? Then continue. Opening the host Shell is the one step with the mouse. You type everything after it.

1. Open a root shell inside the container. The easiest way is pct enter 102 on the server (192.168.1.220).
2. Check that port 53 is free. AdGuard needs port 53 for DNS. The command ss -lntup | grep ':53 ' prints nothing? Then the port is free. Go to the next step. It prints a line with systemd-resolved? Then run the second block below. A new Debian 13 container has no systemd-resolved, so you usually skip it.
3. Install Docker. Start AdGuard.

ss -lntup | grep ':53 '
apt update && apt install -y docker.io curl
docker run -d --name adguardhome --restart=unless-stopped \
  -v /opt/adguard/work:/opt/adguardhome/work -v /opt/adguard/conf:/opt/adguardhome/conf \
  -p 53:53/tcp -p 53:53/udp -p 80:80/tcp -p 3000:3000/tcp adguard/adguardhome

systemctl disable --now systemd-resolved; rm -f /etc/resolv.conf; echo "nameserver 192.168.1.1" > /etc/resolv.conf

The two -v volumes keep your settings and filter data after updates. The run command opens three ports:

• -p 53:53/tcp -p 53:53/udp — port 53, the DNS port. It is open on both protocols, because DNS uses both.
• -p 3000:3000/tcp — the one-time setup wizard.
• -p 80:80/tcp — the dashboard that you use after the wizard.

SET UP AND POINT THE HOUSE AT IT

1. Open http://192.168.1.223:3000 to start the first-run wizard.
2. Set the admin web interface to port 80. Set DNS to port 53.

1. Make your admin login on the next step of the wizard.

1. When the wizard ends, the dashboard moves to http://192.168.1.223. It no longer uses :3000.

1. Add a blocklist. Go to Filters → DNS blocklists → Add blocklist → Choose from the list. Tick the box next to OISD Blocklist Big. This is the exact text in the list. Then click the Save button at the bottom of that box. The tick alone changes nothing. You close the box in another way? Then the choice is lost, and nothing tells you.
2. Check that it worked. The DNS blocklists page now shows a row OISD Blocklist Big, with a rule count next to it. The count is a big number, not zero. No row, or a count of zero, means that the Save did not happen. Do step 5 again. Later, devices use AdGuard. Then the figure Blocked by filters on the Dashboard goes above zero. This is the second proof that blocking works.

1. Set the resolver under Settings → DNS settings. Set the Upstream DNS servers to https://dns.cloudflare.com/dns-query. Click Apply.

1. On the admin page of your router (192.168.1.1), find the DHCP or LAN settings. The field is usually named “DNS server”. Set the DNS server that the router gives to devices to 192.168.1.223. Keep a second DNS empty. The router does not save with an empty field? Then enter 192.168.1.223 again. Do not enter a public DNS there. If you do, devices bypass AdGuard. Save the change. You never opened the admin page of your router? Type the gateway address that you wrote down in Ch. 6 · Install Proxmox in a browser on any machine at home. It is the same number, for example 192.168.1.1. It asks for a user name and a password. Nobody changed them? Then they are on a sticker on the router, usually under it. Often the user is admin, with a password that is unique for your router. The sticker is gone? The support page of your internet provider lists the default for your model. You are not locked out. This page is on your own network. It is not on the internet.

1. Your router does not allow this change? Then set 192.168.1.223 as the DNS on each device by hand. On Windows: Settings → Network & Internet → your connection → Edit DNS. On an iPhone: Settings → Wi-Fi → (i) next to your network → Configure DNS → Manual. On Android: do not use Private DNS. That box accepts only a host name, not an address. Open the Wi-Fi network, edit it, and open Advanced options → IP settings. Set it to Static. Fill in the address, the gateway, and put 192.168.1.223 in DNS 1. The menu names are a little different on each Android version.
2. Devices use AdGuard only after they connect to Wi-Fi again, or after you restart them.

HOW TO USE IT — THE BASICS

AdGuard Home blocks ads by itself. Use these steps for the usual tasks.

1. Open http://192.168.1.223. Log in with the account from the setup wizard.
2. Read the Dashboard: the total DNS queries, the percentage Blocked by filters, the top domains, and the top clients.
3. A site does not work? Open the Query Log in the top menu. Search for the name of the site. Blocked entries are red.

1. Let that site through. There is no Unblock button on the row. Do not look for one. At the right end of the red row, click the ⋮ control (three dots, one above the other). A small menu opens. Choose Unblock. Do not choose Unblock for this client only. That is a different item. It affects only one device. Then reload the page on the device.

1. Block a domain. Find it in the Query Log and click Block. Or add a rule such as ||example.com^ under Filters → Custom filtering rules.

1. Pause all blocking for a short time. Click Disable protection on the Dashboard. Select a duration. Protection starts again by itself.

WHEN IT GOES WRONG

The container does not start, or docker logs adguardhome shows listen tcp 0.0.0.0:53: bind: address already in use (also seen as error while creating listener: cannot listen on 53). Another program on the host already holds DNS port 53. Run ss -lntup | grep ':53 ' to see which program it is. It is usually systemd-resolved, the DNS helper of Debian. Free the port and make the container again. Run systemctl disable --now systemd-resolved; rm -f /etc/resolv.conf; echo "nameserver 192.168.1.1" > /etc/resolv.conf; docker rm -f adguardhome. Then run the docker run … command again.

After the setup wizard, the browser cannot reach the dashboard at http://192.168.1.223:3000 any more (connection refused or timed out). This is expected. Port 3000 is only the one-time wizard. You set the admin interface to port 80, so the dashboard moved. Open http://192.168.1.223 (no :3000). Your login is the one that you made in the wizard.

The DNS of the router is set to 192.168.1.223, but ads still show, and the Query Log stays empty for that device. The device still uses its old DNS. Restart it, or turn Wi-Fi off and on, to renew the DHCP lease. Ads stay in a browser? Turn off the setting “Secure DNS” or “DNS over HTTPS” of the browser (Chrome: Settings → Privacy and security → Security; Firefox: Settings → Privacy & Security → DNS over HTTPS). It bypasses AdGuard. You know that it works when the lookups of the device show in the Query Log of AdGuard.

The whole house loses internet (nothing resolves) after you point the router at AdGuard. Sites fail with “server not found”. The house now depends on this container. If it is down, or if its upstream is not set, all DNS fails. Restart it with docker restart adguardhome. Then check docker logs adguardhome --tail 50. Make sure that an Upstream DNS server (https://dns.cloudflare.com/dns-query) is set under Settings → DNS settings. For an emergency bypass, set the DNS of the router back to 192.168.1.1 or 1.1.1.1 for the time being, until AdGuard works again.

• A download step fails with Temporary failure resolving deb.debian.org, or with another "cannot resolve" message. The container has no working DNS server. It cannot change a name into an address. This is not a typing mistake. It does not fix itself. In the Proxmox page, select this container in the left tree. Open DNS. Select Edit. Type your router address in DNS servers (192.168.1.1 here; use your own). Then run pct reboot 102 in the host shell. Run the failed step again.
• A command fails. You do not know if you are on the server or in the container. Read the prompt. In the container, it ends with the name of the container. On the server, it shows root@homelab. The prompt still shows root@homelab after pct enter? Then the command did not work. Type exit. Run the pct enter line again. Check the prompt before you paste anything else. You can paste a build block on the server by mistake. It seems to work. It installs without an error, and the app even answers. But the app is on the server, and it must not be there.
• How to see that it happened, and how to undo it. The app does not open at the container address (192.168.1.223). It does open at the server address (192.168.1.220) on the same port. Then the app is on the host. To remove it, run docker rm -f adguardhome in the host shell. Then run pct enter 102. Check that the prompt changed. Paste the build block again. You lose nothing in the container, because nothing was built there. The first command can show Error: No such container. This is good. It means that the app was never on the host. Do not paste the build block again. Look for another cause.
• The page does not open. The browser spins, or says it cannot connect. Do these checks in order, in the host shell. 1. Is the container running? Run pct status 102. It must say running. If it does not, run pct start 102. 2. Is the container at the address that you typed? Run pct config 102 | grep net0. It shows the real address. A wrong digit in the wizard puts the container at another address, and nothing warns you. 3. Does the app run in the container? Run pct enter 102. Then run docker ps. An empty list means that the app did not start. Run docker ps -a to see that it stopped. Run docker logs to see why. 4. Does the app answer in the container? Run curl -I http://localhost followed by the port of the app. You get a reply here, but nothing from your PC? Then the address or your own network is the problem. The app is fine. Your browser reaches 192.168.1.223 but not the port? Then the app is down. It reaches neither? Then the container is down.
• Docker does not start, or you see Cannot connect to the Docker daemon, a keyring error, or an overlay error. This is the most common failure in these guides. It means that the two container features are off. A later pct set --features can switch them off, also when you set them before. Run this in the host shell, not in the container: pct set 102 --features nesting=1,keyctl=1. Then run pct reboot 102. Then run the failed step again. Type both settings on one line. If you send only one setting, it replaces the pair and switches the other one off.

REFERENCE CARD

Paste this in Proxmox under 102 → Summary → Notes. It is a note for your future self. It is not a shell command. Before you ever run the update line on this card, compare it with the docker run you actually used at install. The card is a snapshot of the standard build: if you added anything of your own — a device, an extra -e setting, a second folder — it is not on the card, and re-running the card's line drops it. The container comes back up looking healthy with your setting gone.

## AdGuard Home — CT 102
dashboard http://192.168.1.223 · DNS 192.168.1.223 · docs https://github.com/AdguardTeam/AdGuardHome/wiki

```sh
# is it running?
docker ps --filter name=adguardhome
curl -fsS http://localhost:80 >/dev/null && echo OK   # dashboard health (port 80, after setup)
nslookup google.com 192.168.1.223   # is DNS answering? (if 'command not found': apt install -y dnsutils)
# logs (last 50)
docker logs adguardhome --tail 50
# stop / start / restart  (restart fixes a DNS outage fast)
docker stop adguardhome
docker start adguardhome
docker restart adguardhome
# is there an update? ("Image is up to date" = no)
docker pull adguard/adguardhome
# update (settings survive in /opt/adguard)
docker pull adguard/adguardhome && docker rm -f adguardhome && docker run -d --name adguardhome \
  --restart=unless-stopped -v /opt/adguard/work:/opt/adguardhome/work -v /opt/adguard/conf:/opt/adguardhome/conf \
  -p 53:53/tcp -p 53:53/udp -p 80:80/tcp -p 3000:3000/tcp adguard/adguardhome
```

CREATE THE CONTAINER

Do this task with the mouse in the Proxmox web page. You type nothing yet. You prefer the command line? The box below the table does the same task with one pct create command.

1. Open https://192.168.1.220:8006.
2. Click homelab in the left tree.
3. Click the blue Create CT button at the top right.
4. Fill in each tab as the reference shows. Leave each field that is not listed at its default value.

Wizard reference — Create CT 103

Tab → Field	Entry
General → Node	Select homelab.
General → CT ID	Type 103. Do not keep the number that the wizard suggests.
General → Hostname	Type npm.
General → Unprivileged container	Keep this box ticked.
General → Nesting	Keep this box ticked. It is ticked by default. The wizard has no box for keyctl, which Docker also needs. The host command after Finish sets it. It is the first line of the next listing.
General → Password / SSH public key	Keep the password empty. Paste your public key in the SSH field: ssh-ed25519 AAAA…your-key-here you@your-pc. With the key, you can run ssh root@192.168.1.224 from your PC. The command pct enter 103 on the host needs no password.
Template → Storage, Template	Select local. Then select debian-13-standard.
Disks → Storage, Disk size	Select local-lvm. Set 6 GiB.
CPU → Cores	Set 1 core.
Memory → Memory (MiB)	Set 1024. Keep Swap at its default.
Network → IPv4	Select Static. Set IPv4/CIDR to 192.168.1.224/24. Set Gateway to 192.168.1.1. Keep IPv6 at its default.
DNS → DNS domain	Keep this field empty. Do not type 192.168.1.1 here.
DNS → DNS servers	Always type 192.168.1.1. Never keep this field empty.
Confirm	Read the summary. Keep Start after created unticked. Select Finish.

What each field does: see Ch. 10 · The container wizard, section "Work through the eight tabs".

The wizard has no box for three settings: the Docker permission keyctl, the timezone, and start at boot. The first command below sets all three. Run these 3 commands on the host. They set the missing settings, start the container, and open its shell. Each part is explained in Ch. 10 · The container wizard, section "The host command every build needs".

pct set 103 --features nesting=1,keyctl=1 --onboot 1 --timezone host
pct start 103
pct enter 103                          # now INSIDE CT 103 — the rest of this page runs here

TMPL=$(pveam available --section system | awk '/debian-13-standard/{print $2}' | tail -1)
pveam download local "$TMPL"          # once per host; harmless to re-run
pct create 103 local:vztmpl/"$TMPL" \
  --hostname npm --cores 1 --memory 1024 --rootfs local-lvm:6 \
  --net0 name=eth0,bridge=vmbr0,ip=192.168.1.224/24,gw=192.168.1.1 \
  --nameserver 192.168.1.1 --features nesting=1,keyctl=1 --unprivileged 1 --onboot 1 --timezone host
pct start 103
pct enter 103                      # you are now INSIDE CT 103 — everything below runs here

BUILD

This part has no buttons. You type commands in the shell of the container. Docker, its images, and its volumes have no equivalent in the Proxmox web page. The web page manages only the container that holds them.

1. Open homelab → >_ Shell. Run pct enter 103. This puts you inside the container as root, with no password.
2. Type the commands on the right in that container shell.

apt update && apt install -y docker.io curl   # installs Docker + curl for the health check below
docker run -d --name npm --restart=unless-stopped -p 80:80 -p 443:443 -p 81:81 \
  -v /opt/npm/data:/data -v /opt/npm/letsencrypt:/etc/letsencrypt jc21/nginx-proxy-manager:latest

SET UP

At the first visit, NPM shows a one-time Setup screen. It asks you to make your own admin account. (You run an older image and get a login page instead? Sign in with the default admin@example.com and changeme. Then change both at once under the user menu.) In both cases, you end with your own admin login.

1. Open http://192.168.1.224:81. The admin page does not load in the first minute after docker run? Wait 1 to 2 minutes. NPM builds its database at the first start, before the admin page is available.
2. Type your full name, the email address that you want to log in with, and a password. Send the form to make your own admin account.

1. To add a proxy host, go to Hosts → Proxy Hosts → Add Proxy Host.

1. Fill in the four boxes. Set Domain Names to kuma.home. Set Scheme to http. Set Forward Hostname / IP to 192.168.1.221. Set Forward Port to 3001. This is what kuma.home → 192.168.1.221:3001 means. The Domain Names box turns each name into a small tag. After you type kuma.home, press Enter, so that it becomes a tag. Do this before you go to the next box. You skip it? Then the box still shows the text, but it did not save it, and Save fails or ignores it. Uptime Kuma (Ch. 14 · Uptime Kuma) already runs from earlier in Part C. So it is a safe one to practise on.
2. Click Save.

1. Make the name resolvable. You do this one time for ALL .home names. In AdGuard (http://192.168.1.223, see Ch. 16 · AdGuard Home), go to Filters → DNS rewrites. Click Add DNS rewrite. In the top box (domain or wildcard), type *.home. In the bottom box (the answer), type 192.168.1.224. Click Save. This one wildcard rule sends each current and future something.home name to NPM. You do not come back here for each service.

1. Open http://kuma.home in a browser. You see the Uptime Kuma dashboard answer, exactly as if you typed http://192.168.1.221:3001. When it loads, the proxy host and the DNS rewrite both work.

Add each other service in the same way. Use one proxy host for each row of the table below. For a service that you build later, the steps are the same. For example, Ch. 22 · Vaultwarden becomes vault.home → 192.168.1.225:8000. You add it when its container exists.

nslookup anything.home 192.168.1.223   # must answer 192.168.1.224

nslookup is part of Windows and macOS. On a Linux PC, first install it with sudo apt install -y dnsutils (Debian or Ubuntu). A common mistake is to type the IP in both boxes. The top box takes the name.

FORWARD PORTS: EVERY SERVICE IN THIS MANUAL

This is the rule: the Forward Hostname and the Forward Port in NPM are exactly the IP and the port of the dashboard URL of the service. You can open it in a browser tab? Then NPM forwards to that pair. This table collects all of them. It is generated from the guides.

Notice — a proxy host for Proxmox itself needs two extra settings

To reach proxmox.home, set Scheme to https, not http. Proxmox speaks only HTTPS on port 8006. Set Forward to 192.168.1.220, port 8006. Turn Websockets Support ON in the same dialog. Without it, the page loads, but each console or Shell window is a black screen. Proxmox uses its own certificate that nobody verified. NPM accepts it, so you see no extra warning here. Note: the connection of the browser to NPM is plain http. So the root login crosses your network without encryption. This is acceptable on a trusted home network. You do not accept it? Use the direct address https://192.168.1.220:8006, or wait for the real-domain certificate step below.

Notice — about the HTTPS certificate

Let's Encrypt cannot give you a real, trusted certificate for a made-up .home name, because it is not a real domain. The Vaultwarden browser extension and the phone apps must trust the certificate. For that, use a real subdomain that you own. For example, use vault.yourdomain.com as the proxy host. Rewrite it to 192.168.1.224 on your network (split-horizon). Then ask for a certificate with DNS Challenge → Cloudflare, if the DNS of your domain is at Cloudflare. If not, pick the DNS provider that holds your domain from the same list. A pure *.home setup needs no domain. But then you must tell each phone and laptop by hand to trust the own certificate of NPM. This is a separate chore for many devices, and this manual does not cover it. Choose the route that suits you.

WHEN IT GOES WRONG

1. Right after docker run, http://192.168.1.224:81 shows “connection refused”, a blank page, or 502 Bad Gateway. This is normal at the very first start. NPM makes keys and builds its database. This takes 1 to 2 minutes. Wait, then reload. Watch the progress with docker logs npm --tail 50 inside CT 103. Reload when it stops logging start-up activity. Make sure that you use port 81 (admin), not port 80.
2. The request for a Let's Encrypt certificate for a .home name fails (“Internal Error”, the HTTP challenge times out, or “DNS problem: NXDOMAIN”). Let's Encrypt cannot give a trusted certificate for a made-up internal name such as vault.home. Leave those LAN-only hosts on plain HTTP. Or use a real domain that you own, for example vault.yourdomain.com. Then ask for the certificate with SSL → Request a new certificate → Use a DNS Challenge → Cloudflare. Paste a Cloudflare API token.
3. On the current image, a request for a certificate with a DNS challenge (Cloudflare or another provider) fails. The error is about a missing or broken certbot DNS plugin. A recent NPM update changed how it talks to Cloudflare and other DNS providers to ask for certificates. Follow the official page https://nginxproxymanager.com/certbot/ and enter your plugin credentials again. The error stays? Try again after docker restart npm.
4. A proxied app loads, but live features break (real-time sync in Vaultwarden, or 502 Bad Gateway on the proxy host). Edit the Proxy Host. Open the Details tab. Turn on Websockets Support. Also check that the Scheme (http or https) and the Forward Port are exactly how that container is exposed on its host IP. If not, the proxy returns 502.
5. Each something.home address suddenly refuses to connect, but the services still work. NPM itself is down or restarts. Each .home name goes through it. So when it is not reachable, each proxied name fails at the same time, although nothing is wrong with the service behind it. Confirm it with docker ps --filter name=npm in CT 103. It is not in the list? Run docker start npm (or docker restart npm). While you wait, reach each service directly at its raw IP and port from the table above. That path never depends on NPM.

• A download step fails with Temporary failure resolving deb.debian.org, or with another "cannot resolve" message. The container has no working DNS server. It cannot change a name into an address. This is not a typing mistake. It does not fix itself. In the Proxmox page, select this container in the left tree. Open DNS. Select Edit. Type your router address in DNS servers (192.168.1.1 here; use your own). Then run pct reboot 103 in the host shell. Run the failed step again.
• A command fails. You do not know if you are on the server or in the container. Read the prompt. In the container, it ends with the name of the container. On the server, it shows root@homelab. The prompt still shows root@homelab after pct enter? Then the command did not work. Type exit. Run the pct enter line again. Check the prompt before you paste anything else. You can paste a build block on the server by mistake. It seems to work. It installs without an error, and the app even answers. But the app is on the server, and it must not be there.
• How to see that it happened, and how to undo it. The app does not open at the container address (192.168.1.224). It does open at the server address (192.168.1.220) on the same port. Then the app is on the host. To remove it, run docker rm -f npm in the host shell. Then run pct enter 103. Check that the prompt changed. Paste the build block again. You lose nothing in the container, because nothing was built there. The first command can show Error: No such container. This is good. It means that the app was never on the host. Do not paste the build block again. Look for another cause.
• The page does not open. The browser spins, or says it cannot connect. Do these checks in order, in the host shell. 1. Is the container running? Run pct status 103. It must say running. If it does not, run pct start 103. 2. Is the container at the address that you typed? Run pct config 103 | grep net0. It shows the real address. A wrong digit in the wizard puts the container at another address, and nothing warns you. 3. Does the app run in the container? Run pct enter 103. Then run docker ps. An empty list means that the app did not start. Run docker ps -a to see that it stopped. Run docker logs to see why. 4. Does the app answer in the container? Run curl -I http://localhost followed by the port of the app. You get a reply here, but nothing from your PC? Then the address or your own network is the problem. The app is fine. Your browser reaches 192.168.1.224 but not the port? Then the app is down. It reaches neither? Then the container is down.
• Docker does not start, or you see Cannot connect to the Docker daemon, a keyring error, or an overlay error. This is the most common failure in these guides. It means that the two container features are off. A later pct set --features can switch them off, also when you set them before. Run this in the host shell, not in the container: pct set 103 --features nesting=1,keyctl=1. Then run pct reboot 103. Then run the failed step again. Type both settings on one line. If you send only one setting, it replaces the pair and switches the other one off.

REFERENCE CARD

Paste this in 103 → Summary → Notes in Proxmox. The key facts and the update steps then stay with the container. Before you ever run the update line on this card, compare it with the docker run you actually used at install. The card is a snapshot of the standard build: if you added anything of your own — a device, an extra -e setting, a second folder — it is not on the card, and re-running the card's line drops it. The container comes back up looking healthy with your setting gone.

## NPM — CT 103
dashboard http://192.168.1.224:81 (proxies serve :80/:443) · docs https://nginxproxymanager.com/guide/

```sh
# is it running?
docker ps --filter name=npm
curl -fsS http://localhost:81 >/dev/null && echo OK   # quick health check
# names resolve via AdGuard rewrite: *.home -> 192.168.1.224
# logs (last 50)
docker logs npm --tail 50
# stop / start / restart
docker stop npm
docker start npm
docker restart npm
# is there an update? ("Image is up to date" = no)
docker pull jc21/nginx-proxy-manager:latest
# update (settings survive in /opt/npm)
docker pull jc21/nginx-proxy-manager:latest && docker rm -f npm && docker run -d --name npm \
  --restart=unless-stopped -p 80:80 -p 443:443 -p 81:81 \
  -v /opt/npm/data:/data -v /opt/npm/letsencrypt:/etc/letsencrypt jc21/nginx-proxy-manager:latest
```

CREATE THE CONTAINER

Do this task with the mouse in the Proxmox web page.

1. Open https://192.168.1.220:8006.
2. Click homelab in the left tree.
3. Click the blue Create CT button at the top right.
4. Fill in the General tab: the CT ID, the hostname, and the rest, as the reference shows.
5. Fill in the other tabs as the reference shows. Use Next to move between tabs. Leave each field that is not listed at its default.

Wizard reference — Create CT 105

Tab → Field	Entry
General → Node	Select homelab.
General → CT ID	Type 105. Do not keep the number that the wizard suggests.
General → Hostname	Type homarr.
General → Unprivileged container	Keep this box ticked.
General → Nesting	Keep this box ticked. It is ticked by default. The wizard has no box for keyctl, which Docker also needs. The host command after Finish sets it. It is the first line of the next listing.
General → Password / SSH public key	Keep the password empty. Paste your public key in the SSH field: ssh-ed25519 AAAA…your-key-here you@your-pc. With the key, you can run ssh root@192.168.1.226 from your PC. The command pct enter 105 on the host needs no password.
Template → Storage, Template	Select local. Then select debian-13-standard.
Disks → Storage, Disk size	Select local-lvm. Set 6 GiB.
CPU → Cores	Set 1 core.
Memory → Memory (MiB)	Set 1024. Keep Swap at its default.
Network → IPv4	Select Static. Set IPv4/CIDR to 192.168.1.226/24. Set Gateway to 192.168.1.1. Keep IPv6 at its default.
DNS → DNS domain	Keep this field empty. Do not type 192.168.1.1 here.
DNS → DNS servers	Always type 192.168.1.1. Never keep this field empty.
Confirm	Read the summary. Keep Start after created unticked. Select Finish.

What each field does: see Ch. 10 · The container wizard, section "Work through the eight tabs".

The wizard has no box for three settings: the Docker permission keyctl, the timezone, and start at boot. The first command below sets all three. Run these 3 commands on the host. They set the missing settings, start the container, and open its shell. Each part is explained in Ch. 10 · The container wizard, section "The host command every build needs".

pct set 105 --features nesting=1,keyctl=1 --onboot 1 --timezone host
pct start 105
pct enter 105                          # now INSIDE CT 105 — the rest of this page runs here

timedatectl list-timezones

TMPL=$(pveam available --section system | awk '/debian-13-standard/{print $2}' | tail -1)
pveam download local "$TMPL"          # once per host; harmless to re-run
pct create 105 local:vztmpl/"$TMPL" \
  --hostname homarr --cores 1 --memory 1024 --rootfs local-lvm:6 \
  --net0 name=eth0,bridge=vmbr0,ip=192.168.1.226/24,gw=192.168.1.1 \
  --nameserver 192.168.1.1 --features nesting=1,keyctl=1 --unprivileged 1 --onboot 1 --timezone host
pct start 105
pct enter 105                      # you are now INSIDE CT 105 — everything below runs here

BUILD

This part has no buttons. These commands run inside CT 105. In the host Shell (homelab → >_ Shell), run pct enter 105. You are still inside from the previous section? Then continue.

apt update && apt install -y docker.io curl
KEY=$(openssl rand -hex 32)        # required; SAVE the printed value
docker run -d --name homarr --restart=unless-stopped -v /opt/homarr:/appdata \
  -e SECRET_ENCRYPTION_KEY="$KEY" -p 7575:7575 ghcr.io/homarr-labs/homarr:latest
echo "SAVE: $KEY"

openssl rand -hex 32 makes the SECRET_ENCRYPTION_KEY that Homarr uses to encrypt the API keys that you give it. This key must stay the same. If it changes, Homarr cannot decrypt those keys after a restart. This is why you save the printed value.

SET IT UP

A new Homarr page is empty. Make a board. Register each service as an “app”. Then place tiles on the grid. You do all of this in the own web page of Homarr.

1. Open http://192.168.1.226:7575. What you see depends on whether you already made the admin account in the BUILD section above. You never opened this page? Then Homarr runs a one-time onboarding. Select Start from scratch. Continue with step 2. You already made the account? Then the onboarding is finished and gone, and you get a plain login page. This is expected. Nothing is broken. Sign in with that user name and password. Then go to step 3.

   

2. You are still in the onboarding? Make the admin account with a user name and a password. Keep the other settings at their defaults.

   

3. Go to Manage → Boards. Click New board. Give it a name, for example home.

   

4. Go to Manage → Apps. Click New app. Enter a name. Type the name of the service in the icon search to pick an icon. Homarr has thousands. Enter the URL that you use in the browser, for example http://192.168.1.226:PORT. You forgot the port of a service? The chapter of that service has it. Do not use localhost.

   

5. Click Open board. Click Edit mode in the header of the board. Click Add item. Select App.

   

6. The new tile is empty. Open its menu with the three dots. Select Edit item. Choose your app.

   

7. Drag a tile to move it. Use the small arrow in the bottom right corner to change its size.

   

8. Click Exit edit mode. This button saves your layout.

   

1. For live-status widgets (the Ch. 43 · Radarr queue, the Ch. 16 · AdGuard Home block percentage), first go to Manage → Integrations. Select the type of integration. Then fill in what that service asks for. Radarr and Sonarr ask for a URL and an API key. AdGuard Home asks for a URL and your AdGuard admin user name and password. There is no read-only option for any of the three. Click Test connection and create.

   

2. Open the board in edit mode again. Use Add item to place the widget that fits the integration. Select your integration in the options of the widget.

   

WHEN IT GOES WRONG

• The container starts, then stops at once or restarts again and again. Soon it is gone from docker ps. — The SECRET_ENCRYPTION_KEY is missing, or it is not a valid hex string of 64 characters. Check the reason with docker logs homarr. Run openssl rand -hex 32 to get a new value of 64 characters. Save it. Then make the container again in the same way as in the next item. Run docker rm -f homarr. Then run docker run again, with everything the same except -e SECRET_ENCRYPTION_KEY="thatvalue", which holds your new value.
• After an update or after you made the container again, you are logged out, boards look empty, or each integration shows a decrypt error. — You made the container again with a different SECRET_ENCRYPTION_KEY. So Homarr cannot decrypt the saved settings. Run docker rm -f homarr. Then run docker run again with the exact key that you saved earlier. It is the value that echo "SAVE: $KEY" printed. The key is really lost? Then you cannot recover the encrypted data. You must set up the integrations again.
• The Docker widget is empty, or it lists only one container named ‘homarr’. Your other services never appear. — This is expected. This manual does not mount the Docker socket. Even with the socket, Homarr sees only the own Docker of CT 105. Each other service runs in a separate CT. Do not use the Docker widget for them. Add each service under Manage → Integrations. Use its address on your network (for example http://192.168.1.226:PORT) and its API key or admin login. These integrations drive the live-status widgets.
• A tile shows a service as ‘offline’, but it opens correctly in your own browser. — The health check of Homarr runs from inside CT 105, on the server side. It does not run from your PC. Give the tile the exact URL that CT 105 can reach: the IP on your network and the correct port, the correct scheme (http or https), and never localhost. Inside the container, localhost means Homarr itself.

INSTALL TAILSCALE ON THE HOST

curl -fsSL https://tailscale.com/install.sh | sh
tailscale up
# copy the printed URL into your PC/phone browser (the server has no screen), sign in — the server joins your tailnet with a 100.x.y.z address

You can now reach Proxmox at https://100.x.y.z:8006, and use SSH, from any device on your tailnet, from anywhere.

REACH THE WHOLE LAN — SUBNET ROUTER

echo 'net.ipv4.ip_forward=1' | tee /etc/sysctl.d/99-tailscale.conf && echo 'net.ipv6.conf.all.forwarding=1' | tee -a /etc/sysctl.d/99-tailscale.conf && sysctl -p /etc/sysctl.d/99-tailscale.conf
tailscale set --advertise-routes=192.168.1.0/24
# then approve the route: https://login.tailscale.com/admin/machines → click the server → Subnets → Edit → tick 192.168.1.0/24 → Save

REACH YOUR .home NAMES FROM ANYWHERE

This step needs Ch. 17 · Nginx Proxy Manager, with its wildcard DNS rule. You entered that rule in the AdGuard web page. It sends each .home name to NPM. One more setting then makes each .home name work on each tailnet device, at home and away:

1. Open the DNS page of the admin console. Click Nameservers. Click Add nameserver. Click Custom.
2. Set the nameserver to 192.168.1.223 (AdGuard). Turn on Restrict to domain (“Split DNS”). Set the domain to home. Click Save.
3. On the phone, turn the Tailscale app ON. Android: also check Settings → Network & Internet → Private DNS. The value must be Automatic. A custom provider bypasses AdGuard, and .home names stop to resolve on Wi-Fi. iPhone: there is no such setting. Skip this step. Go to the notice below.

WHEN IT GOES WRONG

You approved the subnet, and you can ping the 100.x address of the server. But devices of the LAN at 192.168.1.x do not open.

The device that you connect from must also accept the advertised routes. On a Linux PC, run tailscale up --accept-routes. On the Tailscale app for iPhone, Android, or Windows, turn on “Use Tailscale subnets” in its settings. On mobile, this setting is usually on when the route is approved.

tailscale up prints “Warning: IP forwarding is disabled, subnet routes / exit node won't work”. Or traffic does not route.

IP forwarding is not on. Run echo 'net.ipv4.ip_forward=1' | tee /etc/sysctl.d/99-tailscale.conf && echo 'net.ipv6.conf.all.forwarding=1' | tee -a /etc/sysctl.d/99-tailscale.conf && sysctl -p /etc/sysctl.d/99-tailscale.conf. Then run your tailscale set … command again.

The route shows in the admin console, but it stays grey or says “awaiting approval”. Remote devices cannot reach the LAN.

You advertised the route, but you did not approve it. Open the machines page of the admin console. Click the server. Open its Subnets section. Click Edit. Tick 192.168.1.0/24. Click Save.

You run tailscale up again, and it fails with “these settings would be changed… re-run with the missing flags or add --reset”.

Tailscale keeps the flags of your last run. List each flag that you use, each time. For example: tailscale up --advertise-routes=192.168.1.0/24 --advertise-exit-node. Or use tailscale set to change one setting. Or add --reset, to set the settings that you do not list back to their defaults.

You do not know the 100.x address of the server. Or https://100.x.y.z:8006 does not load.

Run tailscale ip -4 on the server. It prints its tailnet address. Make sure that the Tailscale app on your laptop or phone is connected with the same account. Use https:// and port 8006. Then accept the warning of the browser about the certificate that Proxmox made itself.

All worked for months. Now nothing at home is reachable, and the admin console lists the server as Expired.

The device key expired. You must sign in again from the machine itself. Open homelab → >_ Shell on your home network (or plug in a screen). Run tailscale up. Open the printed URL. Sign in. Then turn off key expiry for that machine in the console, so that it cannot happen again.

REFERENCE CARD

## Tailscale — on the HOST
dashboard https://login.tailscale.com/admin/machines · docs https://tailscale.com/kb

```sh
# is it running?
systemctl status tailscaled
tailscale status                    # who's on the mesh + connection type
tailscale ip -4                     # this machine's tailnet address
# logs (last 50)
journalctl -u tailscaled -n 50 --no-pager
# stop / start / restart
systemctl stop tailscaled
systemctl start tailscaled
systemctl restart tailscaled
# is there an update? (prints "up to date" or installs the new build)
tailscale update
# change one setting without touching the others
tailscale set --advertise-routes=192.168.1.0/24
tailscale set --advertise-exit-node
```

MAKE THE WEEKLY JOB

This task uses only the web page. The job is at the Datacenter level. It is not on one container. One job covers each guest on the server. A guest is the word of Proxmox for each container or virtual machine that it runs. It also covers the containers that you did not build yet.

vzdump --all --mode snapshot --storage local --compress zstd   # back up every guest, right now
cat /etc/pve/jobs.cfg                                        # the scheduled job, as the GUI saved it

RUN IT ONCE, NOW

Do not wait until Sunday to find out if the job works. Run it by hand. Watch it finish.

THE RESTORE DRILL — ONCE, TODAY

A backup that you never restored is not a backup. It is a hope. A job can write archives, report success, and still make useless files. For example, a file is cut off, a storage was full, or the container was already broken. You find out at the worst moment, unless you find out now. This drill takes about five minutes. It never overwrites anything. You restore into a new ID, and you delete it when you are done. It needs one precaution. It is step 6. A restored container is a copy of the original, byte for byte. This includes its network address. So you give the copy its own address before you switch it on. Do that step, and the live container does not notice anything. Skip it, and you knock the original off the network for as long as the drill takes.

WHAT THIS COVERS — AND WHAT IT DOES NOT

WHEN IT GOES WRONG

The run ends in TASK ERROR: job errors, but most of the archives were written.

The job is fine. One guest is broken. All means all. A container whose disk is missing fails its own archive and marks the whole task as failed. Examples are a creation that did not finish, or a disk that you deleted by hand. Scroll the log for the line ERROR: Backup of VM <id> failed. It names the guest and the reason (for example no such logical volume pve/vm-105-disk-0). The summary line near the end then says INFO: Backup job finished with errors and not finished successfully. Each other guest still shows Finished Backup of VM <id>. Their archives are really in homelab → local → Backups. Fix or delete the broken container. Do not touch the job.

Run now is grey, or a click does nothing.

You did not select a job row. Run now, Edit, and Remove all start disabled. They wake up only when you click a row in the table. A disabled button of Proxmox swallows clicks in silence. It does not complain. Click the row of the job first. Then click the button.

The Storage dropdown in the backup job dialog is empty, or it does not list the storage that you want.

A storage can hold backups only if its content types include Backup. On a new install, only local has it. local-lvm, where the container disks live, cannot hold archives. Add it under Datacenter → Storage → Edit → Content. Or use local, as this chapter does.

The CT field turns red: This CT ID is already in use.

Something already has that number. It is usually a container from an earlier drill. Pick another free number, such as 198. Or clean up the old one first. Select it in the tree. Stop it. Then More → Remove. The dialog does not let you go on while the number is taken. This is the guard that you want.

Remove is grey in the More menu, and you cannot delete CT 199.

Proxmox refuses to destroy a container that runs. Click Shutdown. Wait until the status says stopped. Remove then works. A stuck container does not shut down? Use Stop. It is a throw-away container, so a hard stop costs nothing.

The backup finishes, but the SSD fills up.

Check Keep Last on the job. With no retention, Proxmox keeps each archive for ever. 2 is the value of this chapter. You can also delete old archives by hand from homelab → local → Backups. Select a row. Click Remove.

REFERENCE CARD

Paste this in the own Notes panel of the server: homelab → Notes → Edit. The node has its own Notes tab in the menu on the left. Containers show their notes on the Summary tab. The card is then on screen when you need it.

## Backups — the weekly safety net
job: Datacenter → Backup · `sun 03:00` · storage `local` · All guests · Snapshot · Keep Last 2
docs https://pve.proxmox.com/wiki/Backup_and_Restore

```sh
# did it run? (archives 'local' holds, newest first)
ls -lht /var/lib/vz/dump/ | head
cat /etc/pve/jobs.cfg                  # the scheduled job as saved
# run the same backup right now
vzdump --all --mode snapshot --storage local --compress zstd
vzdump 100 --mode snapshot --storage local --compress zstd   # one guest only
# RESTORE — always into a NEW, unused id (never over a live container)
# list the archives first and copy a REAL filename — DATE below is a placeholder, not a name
ls /var/lib/vz/dump/vzdump-lxc-100-*.tar.zst
pct restore 199 /var/lib/vz/dump/vzdump-lxc-100-DATE.tar.zst --storage local-lvm
# the copy inherits the original's MAC + IP — re-address it BEFORE starting it
pct set 199 -net0 name=eth0,bridge=vmbr0,ip=dhcp
pct start 199
pct stop 199
pct destroy 199
```

Same-SSD copy only: guards against mistakes, NOT a dead disk.
Real 3-2-1 (second drive + off-site) is the Backups-done-right chapter in Part G — EDIT this job there, do not add a second one.
Test one restore every 3 months.

A MENU, NOT A CHECKLIST

Part D has seventeen apps. This number frightens people. They think that they must build all seventeen. You do not. A healthy homelab runs five to eight apps. These are the apps that replace a service that you paid for, or a habit that annoyed you. The other nine or ten stay on the menu until the day that you really want them.

So read this part like a menu, not like a to-do list. Each app in it is optional, works alone, and is safe to skip. Each app earns its container by answering one question: what does it give me that I do not have already? An app does not answer that for you today? Close the chapter and go on. You do no harm. Nothing later in the manual depends on it.

The rest of this page gives you three tools to pick well. A decision table compares each app of Part D with what it replaces and how hard it is. A RAM budget tells you how many apps you can run at the same time. Three ready starter menus give you a short list, if you prefer a list to building your own.

THE DECISION TABLE

The table lists each app of Part D, easy first and involved last. Scan the "Replaces" column for a paid service or a habit that you want to drop. Check the "Get it if" line to confirm that it fits. Read "Difficulty" with honesty before you give an evening to an app. The RAM column is the limit that you set in the container wizard. The next section explains what that number really costs you. One row is different. The number for authentik has (floor). This means a minimum that the app needs only to run. It is not a limit that it can grow into. Give it less, and it breaks. It does not only run tighter.

YOUR RAM BUDGET

The machine has 16 GB of RAM. After Parts B and C, you have about 13 GB of real free space for Part D and later. Part B and C are Proxmox itself, the essential six, and remote access. The backup job uses no RAM. This is enough for a comfortable homelab. It is not enough for all seventeen apps at the same time. RAM is the one resource that you must budget.

This is a worked example: a stack of four apps to "own your data", added up by its caps:

Five gigabytes of limits out of your thirteen. In practice, this stack idles near 2 GB, because the caps are the worst case. You can run this stack and still have room for several more apps. The heavy apps fill the budget fast. The container of Ch. 28 · Penpot starts at 2 GB. Plan to raise it to 4 GB when you use it for real. Ch. 37 · Home Assistant (preview) has a cap of 4 GB. Ch. 52 · Immich in Part E has a cap of 8 GB alone. Run one or two of those. Do not run all of them.

THREE STARTER MENUS

You prefer a short list to building your own? Pick one of these. Each one is a small, coherent set that solves one kind of problem. Build it. Live with it. Add from the table above when you know what you miss.

Whichever menu you pick, the routine is the same each time. Build the container. Run the app. Then do the routine after each build Ch. 12 · After every build + common Proxmox tasks. The full checklist of that chapter has five quick steps: a Notes card, a health monitor, an alert, a dashboard tile, and a snapshot. Then look at Beszel Ch. 15 · Beszel. Decide if you add the next app.

CREATE THE CONTAINER

You do this task with the mouse, in the Proxmox web page. You type nothing. You prefer the command line? The box below the table does the same task with one pct create command.

1. On your PC, open https://192.168.1.220:8006.

   

2. Click homelab in the left tree.

   

3. Click the blue Create CT button at the top right.

   

4. Fill in the tabs as the table shows. Keep each field that is not listed at its default value.