From e6ab0676414ee085e863dcc526b9d1696c32536e Mon Sep 17 00:00:00 2001 From: ilia Date: Tue, 30 Dec 2025 23:12:38 -0500 Subject: [PATCH] Add gpu, qbit and vikunja notes (#2) Reviewed-on: https://git.levkin.ca/ilia/homelab-notes/pulls/2 --- .markdownlint-cli2.yaml | 2 + proxmox1/gpu-passthrough-notes.md | 146 ++++++++++++++++ qBit/qBit-notes.md | 183 ++++++++++++++++++++ vikunja-lxc/vikunja-notes.md | 276 ++++++++++++++++++++++++++++++ 4 files changed, 607 insertions(+) create mode 100644 proxmox1/gpu-passthrough-notes.md create mode 100644 qBit/qBit-notes.md create mode 100644 vikunja-lxc/vikunja-notes.md diff --git a/.markdownlint-cli2.yaml b/.markdownlint-cli2.yaml index b596eda..a468f70 100644 --- a/.markdownlint-cli2.yaml +++ b/.markdownlint-cli2.yaml @@ -2,3 +2,5 @@ # Notes repo: long lines (IPs, commands, URLs) are common. config: MD013: false + # Notes often use inline citation tokens like [web:123] (not real reference-style links). + MD052: false diff --git a/proxmox1/gpu-passthrough-notes.md b/proxmox1/gpu-passthrough-notes.md new file mode 100644 index 0000000..ad7a48a --- /dev/null +++ b/proxmox1/gpu-passthrough-notes.md @@ -0,0 +1,146 @@ +# GPU Passthrough (VFIO) Notes + +Host/guest checklist for GPU passthrough (or virtual GPU) when building Debian VMs in Proxmox / virt-manager style setups. + +--- + +## Host: Pick GPU and enable passthrough + +List GPUs on the host: + +```bash +lspci | egrep -i 'vga|3d|display' +``` + +Note the PCI ID of the card you want to pass, e.g. `0000:01:00.0`. + +On the host, enable IOMMU and passthrough (Proxmox/virt-manager style): + +- Add appropriate kernel params (example Intel): + +```text +intel_iommu=on iommu=pt +``` + +- Reboot and verify: + +```bash +dmesg | egrep -i 'iommu|dmar' +``` + +Bind the GPU to `vfio` (or equivalent passthrough driver) on the host so the VM can own it exclusively. + +--- + +## Host: Create the VM with a VGA/GPU device + +Create a new VM (Proxmox or virt-manager): + +- **Firmware**: UEFI/OVMF if possible +- **Machine type**: Q35/modern +- **CPU**: host-passthrough (or similar) + +Add GPU to the VM: + +- Add PCI device: select your GPU (and its audio function if present) +- For a purely virtual GPU instead (no passthrough), pick Virtio GPU or QXL as the display adapter + +Add display channel: + +- If you want a normal graphical console, use SPICE (virt-manager) or Proxmox’s standard console display +- Add a Channel (spice) device for clipboard/resize when using SPICE + +--- + +## Guest: Verify what GPU the VM sees + +Inside the guest OS (your Debian VM): + +```bash +lspci | egrep -i 'vga|3d|display' +lsmod | egrep 'nvidia|amdgpu|radeon|virtio_gpu' +``` + +Interpretation: + +- `NVIDIA Corporation ...` → real NVIDIA passthrough +- `Advanced Micro Devices, Inc. [AMD/ATI] ...` → AMD passthrough +- `Red Hat, Inc. Virtio GPU` or `QXL` → virtual GPU only + +--- + +## Guest: Install and test drivers + +### If NVIDIA passthrough + +Install driver and tools: + +```bash +sudo apt update +sudo apt install nvidia-driver-535 nvidia-smi +``` + +(Adjust version to what Debian suggests.) + +Test: + +```bash +nvidia-smi +watch -n 1 nvidia-smi +``` + +The watch line must be `watch -n 1 nvidia-smi`. + +Quick 3D check: + +```bash +sudo apt install mesa-utils +glxgears +``` + +GPU utilization should rise in `nvidia-smi` while `glxgears` runs. + +### If AMD passthrough + +Inspect and ensure `amdgpu` is used: + +```bash +sudo lshw -c video +lsmod | grep amdgpu +``` + +Install tools: + +```bash +sudo apt install mesa-utils +# optionally: +sudo apt install amdgpu-tools # or ROCm SMI tools if available +``` + +Monitor: + +```bash +watch -n 1 sudo amd-smi +``` + +(Or the ROCm SMI CLI in your distro.) + +### If only Virtio/QXL is present + +- You have a virtual GPU, not the physical one. +- You can still use `glxgears` and basic acceleration, but host GPU usage is not controlled directly from inside this VM. +- To use the physical card, change the VM to PCI passthrough as above. + +--- + +## Guest: Console and SPICE/GUI behavior + +- With SPICE display and the spice channel present, dynamic resolution and clipboard should work once guest tools are installed. +- If a graphical display manager (e.g. LightDM) misbehaves, you can force a TTY-only boot: + +```bash +sudo systemctl set-default multi-user.target +sudo systemctl disable --now lightdm.service +``` + +This gives you a reliable text console, and you can work purely over SSH for GPU workloads. diff --git a/qBit/qBit-notes.md b/qBit/qBit-notes.md new file mode 100644 index 0000000..264b227 --- /dev/null +++ b/qBit/qBit-notes.md @@ -0,0 +1,183 @@ +# qbit-debian / qBittorrent + WireGuard Notes + +Last updated: 2025-12-28 + +Debian VM dedicated to qBittorrent (`qbittorrent-nox`) with Web UI and local-only access, plus groundwork for self-hosted WireGuard. + +--- + +## Host Overview + +- **VM name:** `qbit-debian` +- **OS:** Debian 12 (bookworm) +- **Role:** Headless BitTorrent client with Web UI +- **Primary services:** + - `qbittorrent-nox` (Web UI on port 8080) [web:146] + - WireGuard tooling installed (`wireguard`, `wireguard-tools`) [web:145][web:154] + +--- + +## qBittorrent Installation & Launch + +### Install qbittorrent-nox + +```bash +apt update +apt install -y qbittorrent-nox +``` + +- `qbittorrent-nox` is the headless/server variant with a Web UI only. [web:153] + +### First run & legal notice workaround + +Problem: first launch blocks on an interactive legal notice prompt, which leaves the process in `T` (stopped) state. + +Workaround using `screen`: + +```bash +apt install -y screen +pkill -9 qbittorrent-nox +screen -S qbit -d -m bash +screen -S qbit -X stuff "qbittorrent-nox\n" +sleep 2 +screen -S qbit -X stuff "y\n" +``` + +After acceptance, `qbittorrent-nox` runs normally in the background and can later be daemonized with `qbittorrent-nox -d` once the legal notice has been accepted at least once. [web:153][web:150] + +--- + +## Web UI Access + +### Port and address + +- Default Web UI port: **8080**. [web:143][web:146] +- Default bind address: all interfaces (`0.0.0.0`), so it is reachable at: + +```text +http://:8080 +``` + +Example in this setup: + +```text +http://10.0.10.91:8080 +``` + +### Login + +- Default credentials on first run: + - Username: `admin` + - Password: `adminadmin` [web:142] +- Change these immediately in **Tools → Options → Web UI** once logged in. + +--- + +## Core qBittorrent Configuration + +### 1. Web UI security + +Inside the Web UI: + +- Go to **Tools → Options → Web UI**. +- Change: + - **Username**: set custom admin user. + - **Password**: set strong password. +- Keep protocol as HTTP and listen only on LAN IP; HTTPS termination can be handled later via Caddy if ever exposed externally. [web:143] + +Current design choice: + +- **Web UI is LAN-only**, accessed via private address (`10.0.10.91:8080`), **not** exposed to the public internet. +- No reverse proxy / TLS used yet; avoids CSRF and exposure concerns mentioned in containerized setups. [web:142][web:149] + +### 2. Download locations + +Within **Tools → Options → Downloads**: + +- **Default save path:** pointed to VM-mounted storage (e.g. TrueNAS share), such as: + +```text +/data/Downloads +``` + +- **Keep incomplete torrents in:** optional subfolder, e.g.: + +```text +/data/Downloads/incomplete +``` + +- Ensure the mount has appropriate permissions for the `qbittorrent-nox` user to read/write; issues in other setups often stem from permission mismatches. [web:147] + +### 3. Testing with legal Linux ISOs + +Use official torrents for testing: + +- Debian images and torrents: [debian.org/download](https://www.debian.org/download) [web:150] +- ArchWiki and other docs confirm Web UI default at `http://HOST_IP:8080` for verification. [web:146] + +Add a magnet link or `.torrent` via **Add Torrent** in the Web UI and confirm files appear under `/data/Downloads`. + +--- + +## Process & Port Verification + +### Check process + +```bash +ps aux | grep qbittorrent +``` + +- Healthy process should show state `S` or similar, **not** `T` (stopped). + +### Check Web UI port + +```bash +ss -tlnp | grep 8080 +``` + +Expected output (example): + +```text +LISTEN 0 50 *:8080 : users:(("qbittorrent-nox",pid=XXXX,fd=YY)) +``` + +Confirms `qbittorrent-nox` is listening on port 8080 on all interfaces. [web:143][web:146] + +--- + +## WireGuard (On This VM Only – Current Status) + +WireGuard is installed but not yet fully configured for production use. + +### Install commands used + +```bash +apt update +apt install -y wireguard wireguard-tools +``` + +This pulls kernel module support and user-space tools on Debian 12. [web:145][web:154] + +Planned role: + +- Eventually act as **self-hosted VPN endpoint** for: + - Mobile access into the home lab / TrueNAS. + - Potential routing of qBittorrent traffic through a VPN tunnel. + +Current state: + +- No persistent `/etc/wireguard/wg0.conf` finalized yet. +- No peers configured; service not yet enabled with `systemctl enable wg-quick@wg0`. [web:145][web:154] + +--- + +## Design Decisions & Notes + +- qBittorrent is intentionally **not** reverse-proxied yet; all access is via LAN IP and HTTP on port 8080 for simplicity during initial setup. [web:143][web:142] +- Legal notice for `qbittorrent-nox` required an interactive acceptance once; `screen` was used to handle this on a headless VM. [web:153][web:150] +- WireGuard is colocated on `qbit-debian` for now; may later be moved to a dedicated container/VM as a centralized VPN gateway. +- When/if exposing the Web UI externally, plan is to: + - Put it behind Caddy with HTTPS and access controls. + - Restrict exposure to VPN subnets rather than the open internet. + +--- diff --git a/vikunja-lxc/vikunja-notes.md b/vikunja-lxc/vikunja-notes.md new file mode 100644 index 0000000..a30585a --- /dev/null +++ b/vikunja-lxc/vikunja-notes.md @@ -0,0 +1,276 @@ +# Vikunja Self‑Hosted Setup (Debian LXC on Proxmox) + +## Overview + +Self‑hosted Vikunja instance running in a Debian LXC on Proxmox, using Docker and Postgres 18 as the database. + +Accessible at: `http://:3456/` (example: `http://10.0.10.159:3456/`). + +## Proxmox / LXC + +- **Proxmox**: LXC container, unprivileged, Debian 12 (bookworm) +- **Network** + - Bridge: `vmbr0` + - IPv4: DHCP (container gets `10.0.10.x` from LAN) + +### DNS troubleshooting + +Initial apt errors (“Temporary failure resolving `deb.debian.org` / `security.debian.org`”) were due to no route + bad DNS in the container. + +Fixed by: + +- Setting the container’s network device to bridge `vmbr0` with IPv4 DHCP and restarting the LXC. +- Ensuring `/etc/resolv.conf` has working nameservers (router IP or `1.1.1.1`, `8.8.8.8`). + +### Backups + +Use Proxmox container backups/snapshots on a schedule; this captures OS, Docker, DB, and Vikunja files. + +## Inside the LXC + +### System updates + +Run periodically to keep Debian secure. + +```bash +apt update +apt full-upgrade -y +reboot +``` + +### Docker installation (from Debian repos) + +Clean up any broken Docker repo (if present) to avoid `NO_PUBKEY` errors from an incomplete `download.docker.com` setup: + +```bash +rm /etc/apt/sources.list.d/docker.list 2>/dev/null || true +apt update +``` + +Install Docker from Debian: + +```bash +apt install -y docker.io +systemctl enable --now docker +docker --version +``` + +Install Docker Compose v2 plugin binary (official GitHub release): + +```bash +mkdir -p /root/.docker/cli-plugins/ +curl -SL https://github.com/docker/compose/releases/download/v2.29.2/docker-compose-linux-x86_64 \ + -o /root/.docker/cli-plugins/docker-compose +chmod +x /root/.docker/cli-plugins/docker-compose +docker compose version +``` + +## Vikunja + Postgres layout + +All Vikunja‑related files live under `/opt/vikunja/`: + +- `docker-compose.yml` — main stack definition +- `files/` — Vikunja attachments/uploads +- `db/` — Postgres data directory (mounted to `/var/lib/postgresql`) + +Create directories and set permissions: + +```bash +mkdir -p /opt/vikunja/files +mkdir -p /opt/vikunja/db +chown -R 1000:1000 /opt/vikunja/files # vikunja user in container +chown -R 999:999 /opt/vikunja/db # postgres user in container +``` + +## Docker Compose configuration + +File: `/opt/vikunja/docker-compose.yml` + +```yaml +services: + db: + image: postgres:18 + container_name: vikunja-db + environment: + POSTGRES_USER: vikunja + POSTGRES_PASSWORD: changeme # change to a strong password + POSTGRES_DB: vikunja + volumes: + # Postgres 18+ expects a mount at /var/lib/postgresql, + # not /var/lib/postgresql/data + - /opt/vikunja/db:/var/lib/postgresql + restart: unless-stopped + healthcheck: + test: ["CMD-SHELL", "pg_isready -h localhost -U $${POSTGRES_USER}"] + interval: 2s + start_period: 30s + + vikunja: + image: vikunja/vikunja + container_name: vikunja + depends_on: + db: + condition: service_healthy + environment: + VIKUNJA_SERVICE_PUBLICURL: http://10.0.10.159:3456/ + VIKUNJA_DATABASE_TYPE: postgres + VIKUNJA_DATABASE_HOST: db + VIKUNJA_DATABASE_USER: vikunja + VIKUNJA_DATABASE_PASSWORD: changeme + VIKUNJA_DATABASE_DATABASE: vikunja + VIKUNJA_SERVICE_JWTSECRET: + volumes: + - /opt/vikunja/files:/app/vikunja/files + ports: + - "3456:3456" + restart: unless-stopped +``` + +Replace: + +- `10.0.10.159` with your LXC IP (or domain if you add a reverse proxy). +- `` with a strong hex string: + +```bash +openssl rand -hex 32 +``` + +`VIKUNJA_SERVICE_JWTSECRET` signs login tokens; keep it stable across restarts. + +## Important notes / workarounds + +### Postgres 18+ mount change + +Mounting `/opt/vikunja/db` to `/var/lib/postgresql/data` with Postgres 18 caused repeated errors about data in `/var/lib/postgresql/data` (unused mount/volume) and restarts. + +For a fresh instance, fix with: + +```bash +cd /opt/vikunja +docker compose down +rm -rf /opt/vikunja/db/* +chown -R 999:999 /opt/vikunja/db +# ensure compose mounts /opt/vikunja/db:/var/lib/postgresql +docker compose up -d +``` + +### DB password mismatch + +If `docker logs vikunja` shows: + +```text +pq: password authentication failed for user "vikunja" +``` + +Check that in `docker-compose.yml`: + +- `POSTGRES_USER` == `VIKUNJA_DATABASE_USER` +- `POSTGRES_PASSWORD` == `VIKUNJA_DATABASE_PASSWORD` +- `POSTGRES_DB` == `VIKUNJA_DATABASE_DATABASE` + +For a new setup, it may be simpler to wipe `/opt/vikunja/db/*` and restart with matching credentials. + +## Starting / stopping the stack + +From `/opt/vikunja`: + +```bash +cd /opt/vikunja +docker compose up -d # start or update +docker compose down # stop +docker ps # status +docker logs vikunja # app logs +docker logs vikunja-db # DB logs +``` + +After `up -d`, go to `http://:3456/` and create the first user; that account becomes the admin for its projects. + +## Quick troubleshooting checklist + +### No network / apt errors in LXC + +```bash +ip a +ip route +ping -c 3 1.1.1.1 +ping -c 3 deb.debian.org +``` + +- No IP / no default route → fix bridge/IPv4 config (`vmbr0` + DHCP) in Proxmox and restart LXC. +- IP works but hostnames fail → fix DNS (`/etc/resolv.conf`, Proxmox DNS). + +### Postgres keeps restarting with mount error + +- Confirm volume is `/opt/vikunja/db:/var/lib/postgresql`. +- For an empty instance, clear the directory and restart as above. + +### Vikunja keeps restarting + +Check `docker logs vikunja`: + +- DB auth error → fix credentials; reset DB if necessary. +- Other config errors → verify env vars (DB host/type, public URL, JWT secret). + +## Data and backups + +Per Vikunja docs, back up: + +- DB data: `/opt/vikunja/db` +- Files: `/opt/vikunja/files` + +### Proxmox backups + +Schedule regular container backups so the whole LXC (OS + data) can be restored. + +### Optional DB dumps + +```bash +mkdir -p /opt/vikunja/pg-dumps +crontab -e +``` + +Add: + +```cron +0 3 * * * docker exec vikunja-db pg_dump -U vikunja vikunja > /opt/vikunja/pg-dumps/vikunja-$(date +\%F).sql +``` + +Ensure `/opt/vikunja/pg-dumps` is included in backups. + +## Usage notes / structure + +### Projects (namespaces) + +Projects in the sidebar: + +- Family +- Personal +- Properties +- Levkin (business) + +Each project is its own list/board with multiple views (List, Gantt, Table, Kanban). Tasks are added via the “Add a task…” bar at the top of each project. + +### Labels + +Current labels: + +- **Context**: `@home`, `@computer`, `@call`, `@errands` +- **Areas**: Finance, Health, Legal, Maintenance, Deep +- **People**: Izik, Zane, Zoey +- **Properties**: `#122`, `#153`, `#284`, `#45`, `#6`, `5`, `15` + +Suggestions: + +- Normalize properties, e.g. `P-122`, `P-153`, etc. +- Add time/energy labels like `5min`, `15min`, “Low energy”, “High energy” for better filtering. + +Use filters to combine labels (e.g. `@computer` + Deep, `P-122` + Maintenance). + +## Useful links + +- Docs: `https://vikunja.io/docs/` +- Config options: `https://vikunja.io/docs/config-options/` +- Docker walkthrough: `https://vikunja.io/docs/docker-walkthrough/` +- Full Docker example: `https://vikunja.io/docs/full-docker-example/` +- What to back up: `https://vikunja.io/docs/what-to-backup/` +- Community: `https://community.vikunja.io/`