Troubleshoots and Updates

Guides for Troubleshooting software and ways to update specific system that are running in homelab.

Updating Guide

Updating Guide

Updating Portainer on Docker Standalone

This guide will walk you trough updating Portainer in terminal. Always match the agent version to the Portainer Server version. In other words, when you're installing or updating to Portainer 2.27.9 make sure all of the agents are also on version 2.27.9.

To update to the latest version of Portainer Server, use the following commands to stop then remove the old version. Your other applications/containers will not be removed.

Portainer Documentation

Updating Portainer
  1. SSH to main Portainer machine (Overseer)
  2. Run Following Commands
docker stop portainer
docker rm portainer
docker pull portainer/portainer-ce:lts
docker run -d -p 8000:8000 -p 9443:9443 --name=portainer --restart=always -v /var/run/docker.sock:/var/run/docker.sock -v portainer_data:/data portainer/portainer-ce:lts

This will stop and remove old version and reinstalled new on. The newest version of Portainer will now be deployed on your system, using the persistent data from the previous version, and will also upgrade the Portainer database to the new version.

Updating Portainer Agent

  1. SSH to vms that run portainer agents (External vm, Internal vm)
  2. Run Following Commands
docker stop portainer_agent
docker rm portainer_agent
docker pull portainer/agent:lts
docker run -d -p 9001:9001 --name portainer_agent --restart=always -v /var/run/docker.sock:/var/run/docker.sock -v /var/lib/docker/volumes:/var/lib/docker/volumes portainer/agent:lts

Updating Guide

Updating Authentik

This is extended guide to updating Authentik software. Read trough official Authentik documentation before running updates.

Authentik Documentation

  1. Take a snapshot of Overseer vm
  2. Navigate to Authentik Directory
cd /docker/authentik
  1. Backup Database
docker exec -t authentik_postgresql_1 pg_dumpall -c -U postgres > authentik_backup.sql
  1. Download the latest docker-compose.yml file
wget -O docker-compose.yml https://goauthentik.io/docker-compose.yml
  1. Ensure .env is all set and has following variables in it
touch .env
PG_PASS=your_database_password
PG_USER=authentik
PG_DB=authentik
AUTHENTIK_SECRET_KEY=your_secret_key
AUTHENTIK_TAG=latest
  1. Pull the Latest image and apply the updates
docker compose pull
docker compose up -d
  1. Check the status
docker compose ps
  1. Login to Authentik and make sure everything is up to date, and everything is working properly

Optional:

If there is an error due to space when downloading or installing the image run a clean up command: 

docker image prune -a

Updating Guide

Update Docker Compose Tool

To update Docker Compose to new v2 version follow these steps:

  1. Add Docker GPG Key
sudo apt-get update
sudo apt-get install ca-certificates curl gnupg
sudo install -m 0755 -d /etc/apt/keyrings
curl -fsSL https://download.docker.com/linux/ubuntu/gpg | sudo gpg --dearmor -o /etc/apt/keyrings/docker.gpg
sudo chmod a+r /etc/apt/keyrings/docker.gpg
  1. Add Docker Repository
echo \
  "deb [arch=$(dpkg --print-architecture) signed-by=/etc/apt/keyrings/docker.gpg] \
  https://download.docker.com/linux/ubuntu \
  $(lsb_release -cs) stable" | \
  sudo tee /etc/apt/sources.list.d/docker.list > /dev/null
  1. Install Docker Compose
sudo apt-get update
sudo apt-get install docker-compose-plugin

 

To check the version

docker compose version

 

Expanding VM Filesystem Size

If the VM hits the size limit, but there is more space allocated, or you allocated the space. These steps will help with expanding the size of the volume.

Checking the Size

  1. Check Disk Usage to see which disk is affected
df -h
  1. Check volume group for free space
sudo vgdisplay

If there is no space, you will need to allocate more trough Hypervisor

Expanding filesystem roof

  1. Extend logical volume
sudo lvextend -l +100%FREE /dev/ubuntu-vg/ubuntu-lv

This will add remaining space to the root system

  1. Resize filesystem
sudo resize2fs /dev/ubuntu-vg/ubuntu-lv
  1. Verify disk size and usage
df -h /

Fix GPT/ Partition Table

If you run into problem where even after expanding filesystem roof it still stays at original number we might need to fix gpt/ partition table. Usually after running command below we would get following message.

  1. Check Disk size vs Partition Size
sudo fdisk -l /dev/sda


GPT PMBR size mismatch (67108863 != 134217727) will be corrected by write.
The backup GPT table is not on the end of the device

  1. Fix GPT/ Partition Table
sudo gdisk /dev/sda
# Press 'v' to verify, then 'w' to write fixes
  1. Resize the partition
sudo parted /dev/sda
(parted) resizepart 3 100%
(parted) quit
  1. Reload partition table
sudo partprobe /dev/sda
  1. Resize physical volume
sudo pvresize /dev/sda3
  1. Check VG Free Space
sudo vgdisplay
  1. Expand Logical Volume
sudo lvextend -l +100%FREE /dev/ubuntu-vg/ubuntu-lv
  1. Resize Filesystem
sudo resize2fs /dev/ubuntu-vg/ubuntu-lv

At the end verify to make sure its actually resized

df -h /

 

Fixing Home Assistant /auth/token Errors Behind Nginx Proxy Manager

This guide explains exactly what to do when Home Assistant shows:

Login attempt or request with invalid authentication.
Requested URL: '/auth/token'

This error happens when Nginx Proxy Manager blocks or alters Home Assistant’s OAuth callback, especially when using Authentik, OIDC, or Basic Auth.


Set the External URL in Home Assistant

In Home Assistant:

  1. Go to Settings → System → Network
  2. Set External URL to:
https://overseer.cyberpaw.org

Why:
Home Assistant validates OAuth requests against this URL. If it doesn’t match the domain used through NPM, HA rejects /auth/token.

Disable “Block Common Exploits” in NPM

In Nginx Proxy Manager:

  1. Go to Hosts → Proxy Hosts
  2. Edit your Home Assistant proxy host
  3. Open the SSL tab
  4. Uncheck:
Block Common Exploits

Why:
This option blocks or modifies legitimate OAuth POST requests to:

This is the #1 cause of the /auth/token error.

Correct SSL Tab Settings

In the same proxy host → SSL tab:

  1. Turn ON:
    1. Force SSL
    2. HTTP/2 Support
    3. Websockets Support
  2. Turn OFF:
    1. HSTS Enabled
    2. HSTS Subdomains

Why:
WebSockets are required for HA. HSTS can cause redirect loops or break local access.

Add Required Headers (Advanced Tab)

In the same proxy host → Advanced tab, add:

proxy_set_header Host $host;
proxy_set_header X-Real-IP $remote_addr;
proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
proxy_set_header X-Forwarded-Proto $scheme;
proxy_set_header X-Forwarded-Host $host;

Why:
Home Assistant must know:

Missing headers = HA rejects the OAuth callback.

Ensure No Path Rewrites or Blocking

Make sure NPM is not rewriting or protecting:

/auth/*
/api/*

If using Basic Auth, do NOT protect these paths.

Why:
OIDC and Authentik rely on these endpoints. If NPM intercepts or rewrites them, HA sees an invalid request.

Test the Login Flow Properly

  1. Close all HA tabs
  2. Open a private/incognito window
  3. Visit:
https://overseer.cyberpaw.org
  1. Log in normally

Paperless NGX

Paperless NGX

What to Do When Files in the Import Folder Don’t Show Up

Sometimes you drop documents into your Import folder, but nothing appears in the Paperless dashboard. This usually isn’t a bug — it’s just how Paperless watches for new files. Here’s a quick guide to diagnose and fix it.

Paperless watches the import folder using inotify, which only reacts to new events:

If the files were already in the folder before Paperless started watching, no event fires — so Paperless never notices them.

  1. Make sure the files are visible inside the container by running following command inside a VM
docker exec -it paperless-webserver-1 ls -l /usr/src/paperless/consume
  1. Trigger Paperless to Notice Files by running touch command
sudo touch /mnt/nas/Import/*.pdf
  1. Also, it might be optional but good idea to restart webserver 
docker restart paperless-webserver-1

 

Premissions matter. If paperlerless can't write to the folder, imports will fail. To check permissions:

docker exec -it paperless-webserver-1 touch /usr/src/paperless/consume/test.txt