UGREEN NAS Migration Implementation Plan
Quelle: pkr-lab/pkr-lab-docs/capulus/capulus-core/archiv/superpowers/plans/2026-05-26-ugreen-nas-migration.md
UGREEN NAS Migration Implementation Plan
For agentic workers: REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (
- [ ]) syntax for tracking.
Goal: Alle NAS-Rollen aus ugreen-paperless ins home-server-Repo migrieren, sodass UGREEN NAS + Home-Server aus einem einzigen Repo betrieben werden.
Architecture: Separates Playbook ansible/ugreen-nas.yml für den NAS; gemeinsames Inventory capulus-ansible/inventory/hosts.yml; NAS-Variablen isoliert in capulus-ansible/host_vars/ugreen-nas/. Rollen werden 1:1 aus /home/ubuntu/git/ugreen-paperless/roles/ kopiert; Umbenennung von node-exporter → node_exporter_nas und day-pilot → day_pilot. Node-Exporter-Metriken des NAS werden per VMStaticScrape CRD in den bestehenden k8s-Monitoring-Stack integriert.
Tech Stack: Ansible 2.14+, Docker Compose v2, VictoriaMetrics Operator (VMStaticScrape CRD), Ansible Vault
Datei-Übersicht
| Aktion | Pfad |
|---|---|
| Modify | capulus-ansible/inventory/hosts.yml |
| Create | capulus-ansible/host_vars/ugreen-nas/vars.yml |
| Create | capulus-ansible/host_vars/ugreen-nas/vault.yml |
| Copy | capulus-ansible/roles/paperless/ (von ugreen-paperless) |
| Copy+Rename | capulus-ansible/roles/node_exporter_nas/ (von ugreen-paperless/roles/node-exporter) |
| Copy | capulus-ansible/roles/opencode/ |
| Copy | capulus-ansible/roles/tinyteller/ |
| Copy+Rename | capulus-ansible/roles/day_pilot/ (von ugreen-paperless/roles/day-pilot) |
| Create | ansible/ugreen-nas.yml |
| Modify | Makefile |
| Create | argocd/apps/tech/monitoring/ugreen-nas-scrape.yaml |
| Modify | capulus-ansible/group_vars/all.yml |
| Modify | CLAUDE.md |
Task 1: Inventory und host_vars anlegen
Files:
-
Modify:
capulus-ansible/inventory/hosts.yml -
Create:
capulus-ansible/host_vars/ugreen-nas/vars.yml -
Create:
capulus-ansible/host_vars/ugreen-nas/vault.yml -
Schritt 1: Lint-Baseline erfassen
cd /home/ubuntu/git/home-server
yamllint -c .yamllint ansible/ argocd/ 2>&1 | head -20
ansible-lint ansible/ 2>&1 | tail -5
Erwartung: Kein Fehler (Baseline für Vergleich).
- Schritt 2: ugreen-nas zum Inventory hinzufügen
Datei: capulus-ansible/inventory/hosts.yml
Ersetze den Block ab all: so:
# ============================================================
# Inventory
# ============================================================
#
# `homeservers` runs the full k3s/ArgoCD/Semaphore stack.
# Targets under `semaphore_targets` get the Semaphore SSH public key
# pushed into authorized_keys so the UI can run playbooks against them.
# `homeservers` is also a member of `semaphore_targets` so Semaphore
# can deploy this very repo against the home-server itself (recursive
# "Deploy Home Server" template).
#
# `ugreen_nas` hosts the Paperless-NGX stack via Docker Compose.
# ============================================================
all:
children:
homeservers:
hosts:
homeserver:
ansible_host: 192.168.178.94
ansible_user: ubuntu
ugreen_nas:
hosts:
ugreen-nas:
ansible_host: jays-ugreen
ansible_user: ubuntu
semaphore_targets:
hosts:
homeserver:
ugreen-nas:
- Schritt 3: host_vars Verzeichnis und vars.yml anlegen
Erstelle capulus-ansible/host_vars/ugreen-nas/vars.yml:
---
# ---- Paperless-NGX ------------------------------------------
paperless_base_dir: /opt/paperless
paperless_http_port: 8000
paperless_ai_enabled: false
paperless_admin_user: admin
paperless_admin_email: [email protected]
paperless_admin_password: "{{ vault_paperless_admin_password }}"
paperless_db_password: "{{ vault_paperless_db_password }}"
paperless_secret_key: "{{ vault_paperless_secret_key }}"
# ---- Node Exporter / cAdvisor -------------------------------
node_exporter_base_dir: /opt/node-exporter
cadvisor_port: 18080
# ---- OpenCode -----------------------------------------------
opencode_install_dir: /opt/opencode
opencode_persist_dir: /opt/opencode/persist
opencode_port: 4096
opencode_build_local_image: false
opencode_git_repo: ""
opencode_git_username: "{{ vault_opencode_git_username | default('') }}"
opencode_git_password: "{{ vault_opencode_git_password | default('') }}"
opencode_github_token: "{{ vault_opencode_github_token | default('') }}"
opencode_server_auth_enabled: false
# ---- TinyTeller ---------------------------------------------
tinyteller_base_dir: /opt/tinyteller
tinyteller_frontend_port: 3002
tinyteller_backend_port: 3004
tinyteller_cors_origin: "http://ugreen-nas:3002"
# ---- Day Pilot ----------------------------------------------
day_pilot_base_dir: /opt/day-pilot
day_pilot_frontend_port: 3003
day_pilot_backend_port: 8001
day_pilot_timezone: "Europe/Berlin"
day_pilot_openai_api_key: "{{ vault_day_pilot_openai_api_key | default('') }}"
day_pilot_github_token: "{{ vault_day_pilot_github_token | default('') }}"
- Schritt 4: vault.yml Platzhalter-Datei anlegen
Erstelle capulus-ansible/host_vars/ugreen-nas/vault.yml:
---
# Diese Datei MUSS mit ansible-vault encrypt_string verschlüsselt werden.
# Workflow:
# ansible-vault encrypt_string 'WERT' --name 'vault_VARIABLENNAME'
# => !vault |-Block in diese Datei einfügen
#
# Pflicht-Secrets (ohne diese startet das Playbook nicht sinnvoll):
vault_paperless_db_password: "CHANGE_ME"
vault_paperless_admin_password: "CHANGE_ME"
vault_paperless_secret_key: "CHANGE_ME"
#
# Optional — nur setzen wenn die Services genutzt werden:
# vault_opencode_git_username: ""
# vault_opencode_git_password: ""
# vault_opencode_github_token: ""
# vault_day_pilot_openai_api_key: ""
# vault_day_pilot_github_token: ""
- Schritt 5: Lint prüfen
yamllint -c .yamllint capulus-ansible/inventory/hosts.yml capulus-ansible/host_vars/
Erwartung: Keine Fehler.
- Schritt 6: Committen
git add capulus-ansible/inventory/hosts.yml capulus-ansible/host_vars/
git commit -m "feat(nas): add ugreen-nas to inventory and host_vars"
Task 2: Rolle paperless migrieren
Files:
-
Create:
capulus-ansible/roles/paperless/(komplett von ugreen-paperless) -
Schritt 1: Rolle kopieren
cp -r /home/ubuntu/git/ugreen-paperless/roles/paperless \
/home/ubuntu/git/home-server/ansible/roles/paperless
- Schritt 2: Lint prüfen
cd /home/ubuntu/git/home-server
yamllint -c .yamllint capulus-ansible/roles/paperless/
ansible-lint capulus-ansible/roles/paperless/ 2>&1 | grep -E 'error|warning' | head -20
Erwartung: Keine Fehler (die Rolle kommt aus einem bereits gepflegten Repo).
- Schritt 3: Committen
git add capulus-ansible/roles/paperless/
git commit -m "feat(nas): migrate paperless role from ugreen-paperless"
Task 3: Rolle node_exporter_nas migrieren
Files:
- Create:
capulus-ansible/roles/node_exporter_nas/(von ugreen-paperless/roles/node-exporter, umbenannt)
Die Rolle behält ihren internen Inhalt unverändert, nur der Verzeichnisname ändert sich um Konflikte mit zukünftigen cluster-seitigen node-exporter-Rollen zu vermeiden.
- Schritt 1: Rolle kopieren und umbenennen
cp -r /home/ubuntu/git/ugreen-paperless/roles/node-exporter \
/home/ubuntu/git/home-server/ansible/roles/node_exporter_nas
- Schritt 2: Lint prüfen
cd /home/ubuntu/git/home-server
yamllint -c .yamllint capulus-ansible/roles/node_exporter_nas/
ansible-lint capulus-ansible/roles/node_exporter_nas/ 2>&1 | grep -E 'error|warning' | head -20
Erwartung: Keine Fehler.
- Schritt 3: Committen
git add capulus-ansible/roles/node_exporter_nas/
git commit -m "feat(nas): migrate node-exporter role as node_exporter_nas"
Task 4: Rolle opencode migrieren
Files:
-
Create:
capulus-ansible/roles/opencode/(von ugreen-paperless) -
Schritt 1: Rolle kopieren
cp -r /home/ubuntu/git/ugreen-paperless/roles/opencode \
/home/ubuntu/git/home-server/ansible/roles/opencode
- Schritt 2: Lint prüfen
cd /home/ubuntu/git/home-server
yamllint -c .yamllint capulus-ansible/roles/opencode/
ansible-lint capulus-ansible/roles/opencode/ 2>&1 | grep -E 'error|warning' | head -20
Erwartung: Keine Fehler.
- Schritt 3: Committen
git add capulus-ansible/roles/opencode/
git commit -m "feat(nas): migrate opencode role from ugreen-paperless"
Task 5: Rolle tinyteller migrieren
Files:
-
Create:
capulus-ansible/roles/tinyteller/(von ugreen-paperless) -
Schritt 1: Rolle kopieren
cp -r /home/ubuntu/git/ugreen-paperless/roles/tinyteller \
/home/ubuntu/git/home-server/ansible/roles/tinyteller
- Schritt 2: Lint prüfen
cd /home/ubuntu/git/home-server
yamllint -c .yamllint capulus-ansible/roles/tinyteller/
ansible-lint capulus-ansible/roles/tinyteller/ 2>&1 | grep -E 'error|warning' | head -20
Erwartung: Keine Fehler.
- Schritt 3: Committen
git add capulus-ansible/roles/tinyteller/
git commit -m "feat(nas): migrate tinyteller role from ugreen-paperless"
Task 6: Rolle day_pilot migrieren
Files:
- Create:
capulus-ansible/roles/day_pilot/(von ugreen-paperless/roles/day-pilot, umbenannt)
Der Bindestrich im Rollennamen ist in Ansible zulässig, aber Unterstriche sind Konvention für dieses Repo (vgl. semaphore_bootstrap, semaphore_secrets).
- Schritt 1: Rolle kopieren und umbenennen
cp -r /home/ubuntu/git/ugreen-paperless/roles/day-pilot \
/home/ubuntu/git/home-server/ansible/roles/day_pilot
- Schritt 2: Lint prüfen
cd /home/ubuntu/git/home-server
yamllint -c .yamllint capulus-ansible/roles/day_pilot/
ansible-lint capulus-ansible/roles/day_pilot/ 2>&1 | grep -E 'error|warning' | head -20
Erwartung: Keine Fehler.
- Schritt 3: Committen
git add capulus-ansible/roles/day_pilot/
git commit -m "feat(nas): migrate day-pilot role as day_pilot"
Task 7: Playbook ansible/ugreen-nas.yml anlegen
Files:
-
Create:
ansible/ugreen-nas.yml -
Schritt 1: Playbook erstellen
Erstelle ansible/ugreen-nas.yml:
---
# ============================================================
# NAS Playbook — deployt Docker-Compose-basierte Dienste auf
# dem UGREEN NAS (jays-ugreen / 192.168.178.118).
#
# Run with:
# make nas
# Dry-run:
# make nas-check
# ============================================================
- name: Deploy NAS services
hosts: ugreen_nas
become: true
roles:
- role: paperless
tags: [paperless]
- role: node_exporter_nas
tags: [node-exporter]
- role: opencode
tags: [opencode]
- role: tinyteller
tags: [tinyteller]
- role: day_pilot
tags: [day-pilot]
- Schritt 2: Syntax-Check
cd /home/ubuntu/git/home-server
ansible-playbook -i inventory/hosts.yml ansible/ugreen-nas.yml \
--syntax-check 2>&1
Erwartung: playbook: ansible/ugreen-nas.yml — keine Fehler.
- Schritt 3: Lint
yamllint -c .yamllint ansible/ugreen-nas.yml
ansible-lint ansible/ugreen-nas.yml 2>&1 | grep -E 'error|warning' | head -20
Erwartung: Keine Fehler.
- Schritt 4: Committen
git add ansible/ugreen-nas.yml
git commit -m "feat(nas): add ugreen-nas.yml playbook"
Task 8: Makefile erweitern
Files:
-
Modify:
Makefile -
Schritt 1: NAS-Variablen und Targets hinzufügen
Füge folgende Zeilen in das Makefile ein — direkt nach der Zeile VAULT_OPTS ?= --ask-vault-pass:
NAS_PLAYBOOK := $(ANSIBLE_DIR)/ugreen-nas.yml
Füge nach dem semaphore-bootstrap-local-Target folgende Targets ein:
.PHONY: nas nas-check
nas: ## Deploy all services on the UGREEN NAS.
ansible-playbook -i $(INVENTORY) $(NAS_PLAYBOOK) $(VAULT_OPTS)
nas-check: ## Dry-run the NAS playbook (no changes applied).
ansible-playbook -i $(INVENTORY) $(NAS_PLAYBOOK) --check --diff $(VAULT_OPTS)
- Schritt 2: Hilfetarget prüfen
make help
Erwartung: nas und nas-check erscheinen in der Ausgabe.
- Schritt 3: Committen
git add Makefile
git commit -m "feat(nas): add make nas and nas-check targets"
Task 9: NAS-Monitoring in k8s-Stack integrieren
Files:
- Create:
argocd/apps/tech/monitoring/ugreen-nas-scrape.yaml
VMAgent (via victoria-metrics-k8s-stack) hat selectAllByDefault: true und picked VMStaticScrape-CRDs aus allen Namespaces automatisch auf.
- Schritt 1: VMStaticScrape-Manifest erstellen
Erstelle argocd/apps/tech/monitoring/ugreen-nas-scrape.yaml:
---
apiVersion: operator.victoriametrics.com/v1beta1
kind: VMStaticScrape
metadata:
name: ugreen-nas-node-exporter
namespace: monitoring
spec:
jobName: ugreen-nas-node-exporter
targetEndpoints:
- targets:
- "jays-ugreen:9100"
labels:
job: node-exporter
instance: ugreen-nas
---
apiVersion: operator.victoriametrics.com/v1beta1
kind: VMStaticScrape
metadata:
name: ugreen-nas-cadvisor
namespace: monitoring
spec:
jobName: ugreen-nas-cadvisor
targetEndpoints:
- targets:
- "jays-ugreen:18080"
labels:
job: cadvisor
instance: ugreen-nas
- Schritt 2: YAML-Lint
yamllint -c .yamllint argocd/apps/tech/monitoring/ugreen-nas-scrape.yaml
Erwartung: Keine Fehler.
- Schritt 3: Committen
git add argocd/apps/tech/monitoring/ugreen-nas-scrape.yaml
git commit -m "feat(monitoring): add VMStaticScrape for ugreen-nas node-exporter and cadvisor"
Task 10: Semaphore-Konfiguration anpassen
Files:
- Modify:
capulus-ansible/group_vars/all.yml
Das bestehende ugreen-paperless-Projekt in semaphore_projects zeigt auf das alte Repo. Es wird auf das home-server-Repo umgestellt und das Template auf ansible/ugreen-nas.yml geändert.
- Schritt 1: semaphore_projects in group_vars/all.yml anpassen
Ersetze den Block des ugreen-paperless-Projekts in capulus-ansible/group_vars/all.yml:
Alter Block:
- name: ugreen-paperless
description: "Deploy Paperless-ngx on the UGREEN NAS."
repository:
name: ugreen-paperless-git
url: "https://github.com/Jaydee94/ugreen-paperless.git"
branch: main
inventories:
- name: ugreen-nas
type: static
ssh_key: semaphore-ssh-key
content: |
[ugreen-nas]
ugreen ansible_host=192.168.178.118
templates:
- name: "Deploy ugreen-paperless"
playbook: ugreen-paperless.yml
inventory: ugreen-nas
vault_key: vault-password
description: "Provision Paperless-ngx stack on the UGREEN NAS."
Neuer Block:
- name: ugreen-nas
description: "Deploy Docker-Compose-Dienste auf dem UGREEN NAS."
repository:
name: home-server-git
url: "{{ argocd_repo_url }}"
branch: main
inventories:
- name: ugreen-nas
type: static
ssh_key: semaphore-ssh-key
content: |
[ugreen_nas]
ugreen-nas ansible_host=192.168.178.118
templates:
- name: "Deploy UGREEN NAS"
playbook: ansible/ugreen-nas.yml
inventory: ugreen-nas
vault_key: vault-password
description: "Paperless-NGX, OpenCode, TinyTeller, Day Pilot auf dem NAS."
- Schritt 2: Lint
yamllint -c .yamllint capulus-ansible/group_vars/all.yml
Erwartung: Keine Fehler.
- Schritt 3: Committen
git add capulus-ansible/group_vars/all.yml
git commit -m "feat(semaphore): update ugreen-paperless project to use home-server repo"
Task 11: CLAUDE.md aktualisieren
Files:
-
Modify:
CLAUDE.md -
Schritt 1: Neue Architektur in CLAUDE.md ergänzen
Im Abschnitt ## Architecture in der root CLAUDE.md den Kommentar zu ugreen-paperless-Repo im Semaphore-Abschnitt (semaphore_projects) aktualisieren: ugreen-paperless (https://github.com/Jaydee94/ugreen-paperless.git) → ugreen-nas (dieses Repo, NAS-Playbook).
Außerdem im Abschnitt ## Commands folgende Zeilen hinzufügen:
make nas # Deploy alle Services auf dem UGREEN NAS
make nas-check # Dry-run des NAS-Playbooks
Und im Abschnitt ## Service URLs den NAS ergänzen:
| Paperless-NGX | http://jays-ugreen:8000 | NAS (Docker Compose) |
| OpenCode | http://jays-ugreen:4096 | NAS (Docker Compose) |
| TinyTeller | http://jays-ugreen:3002 | NAS (Docker Compose) |
| Day Pilot | http://jays-ugreen:3003 | NAS (Docker Compose) |
- Schritt 2: Committen
git add CLAUDE.md
git commit -m "docs: update CLAUDE.md with ugreen-nas architecture and commands"
Task 12: Gesamtvalidierung
- Schritt 1: Vollständigen Lint laufen lassen
cd /home/ubuntu/git/home-server
yamllint -c .yamllint ansible/ argocd/
ansible-lint ansible/
Erwartung: Keine Fehler.
- Schritt 2: Syntax-Check beider Playbooks
ansible-playbook -i inventory/hosts.yml site.yml --syntax-check
ansible-playbook -i inventory/hosts.yml ansible/ugreen-nas.yml --syntax-check
Erwartung: Beide zeigen playbook: ... ohne Fehler.
- Schritt 3: Rollen-Liste prüfen
ls capulus-ansible/roles/
Erwartung: paperless node_exporter_nas opencode tinyteller day_pilot sind vorhanden (neben den bestehenden Rollen).
- Schritt 4: Branch pushen
git push -u origin feat/ugreen-nas-migration