# Troubleshoots and Updates

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

# 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](https://docs.portainer.io/start/upgrade)

##### Updating Portainer

1. SSH to main Portainer machine (Overseer)
2. Run Following Commands

```bash
docker stop portainer
```

```bash
docker rm portainer
```

```bash
docker pull portainer/portainer-ce:lts
```

```bash
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

```bash
docker stop portainer_agent
```

```bash
docker rm portainer_agent
```

```bash
docker pull portainer/agent:lts
```

```bash
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 Authentik

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

[Authentik Documentation](https://docs.goauthentik.io/install-config/upgrade/)

1. Take a snapshot of Overseer vm
2. Navigate to Authentik Directory

```bash
cd /docker/authentik
```

3. Backup Database

```bash
docker exec -t authentik_postgresql_1 pg_dumpall -c -U postgres > authentik_backup.sql
```

4. Download the latest docker-compose.yml file

```bash
wget -O docker-compose.yml https://goauthentik.io/docker-compose.yml
```

5. Ensure .env is all set and has following variables in it

```bash
touch .env
```

```yaml
PG_PASS=your_database_password
PG_USER=authentik
PG_DB=authentik
AUTHENTIK_SECRET_KEY=your_secret_key
AUTHENTIK_TAG=latest
```

6. Pull the Latest image and apply the updates

```bash
docker compose pull
docker compose up -d
```

7. Check the status

```bash
docker compose ps
```

8. 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:

```bash
docker image prune -a
```

# Update Docker Compose Tool

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

1. Add Docker GPG Key

```bash
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
```

2. Add Docker Repository

```bash
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
```

3. Install Docker Compose

```bash
sudo apt-get update
sudo apt-get install docker-compose-plugin
```

To check the version

```bash
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

```bash
df -h
```

2. Check volume group for free space

```bash
sudo vgdisplay
```

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

#### Expanding filesystem roof

1. Extend logical volume

```bash
sudo lvextend -l +100%FREE /dev/ubuntu-vg/ubuntu-lv
```

This will add remaining space to the root system

2. Resize filesystem

```bash
sudo resize2fs /dev/ubuntu-vg/ubuntu-lv
```

3. Verify disk size and usage

```bash
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

```bash
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

2. Fix GPT/ Partition Table

```bash
sudo gdisk /dev/sda
# Press 'v' to verify, then 'w' to write fixes
```

3. Resize the partition

```bash
sudo parted /dev/sda
(parted) resizepart 3 100%
(parted) quit
```

4. Reload partition table

```bash
sudo partprobe /dev/sda
```

5. Resize physical volume

```bash
sudo pvresize /dev/sda3
```

6. Check VG Free Space

```bash
sudo vgdisplay
```

7. Expand Logical Volume

```bash
sudo lvextend -l +100%FREE /dev/ubuntu-vg/ubuntu-lv
```

9. Resize Filesystem

```bash
sudo resize2fs /dev/ubuntu-vg/ubuntu-lv
```

At the end verify to make sure its actually resized

```bash
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:

```bash
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:

- `/auth/token`
- `/auth/authorize`
- `/api/*`

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:

- The original hostname
- The original protocol (HTTPS)
- The real client IP

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
```

4. Log in normally

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

<span style="white-space: pre-wrap;">Paperless watches the import folder using **inotify**, which only reacts to *new* events:</span>

- <span style="white-space: pre-wrap;">a file is **created**</span>
- <span style="white-space: pre-wrap;">a file is **modified**</span>
- <span style="white-space: pre-wrap;">a file is **moved into** the folder</span>

<span style="white-space: pre-wrap;">If the files were already in the folder **before** Paperless started watching, no event fires — so Paperless never notices them.</span>

1. <span style="white-space: pre-wrap;">Make sure the files are visible inside the container by running following command inside a VM</span>

```bash
docker exec -it paperless-webserver-1 ls -l /usr/src/paperless/consume
```

2. <span style="white-space: pre-wrap;">Trigger Paperless to Notice Files by running touch command</span>

```bash
sudo touch /mnt/nas/Import/*.pdf
```

3. Also, it might be optional but good idea to restart webserver

```bash
docker restart paperless-webserver-1
```

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

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