# 🥔 Potatium: Schritt-für-Schritt-Start auf Ubuntu 26.04 LTS **Arbeitsannahme:** unprivilegierter Proxmox-LXC mit **Ubuntu Server 26.04 LTS**, nicht 26.10. Development-Maschine heißt `potatium-dev`, Linux-Benutzer `potatium`, Git-Monorepo liegt in `/home/potatium/src/potatium`. **Dies ist der einzige verbindliche Projektpfad; ein zweites `workdir` wird nicht genutzt.** Das hier ist ein **funktionsfähiges Entwicklungsgerüst**, noch keine Blockchain und keine echte Wallet. > **Die Reihenfolge ist wichtig:** LXC → erstmalig SSH/Basiszugang → ZIP übertragen/entpacken → Ubuntu-Setup-Skript → Prüfskript → Git → VS Code/Codex → Architektur-/Protokollentscheidungen → eigentliche Entwicklung. ## 1. Proxmox-LXC erstellen (Proxmox-Weboberfläche) | Einstellung | Wert | |---|---| | Template | Ubuntu **26.04 LTS** amd64, idealerweise 26.04.1 | | Hostname | `potatium-dev` | | Typ | **Unprivileged** | | CPU / RAM / Disk | 4 vCPU / 4 GiB / 40 GiB | | Netzwerk | internes LAN, Bridge wie gewohnt, stabile IP über DHCP-Reservierung oder statische Adresse | | Features | Standard, **kein Nesting/Docker nötig** | | SSH / Port-Freigaben | ausschließlich internes LAN / VPN; keine externe 8080-Freigabe | **Wichtig:** Die 4 vCPU sind für Entwicklung und Mehrprozess-Tests gedacht, nicht die spätere Mindesthardware eines Miners. Snapshot/Backup des LXC nach Basisinstallation vorsehen. ## 2. Im Proxmox-Console-Terminal als root den Erstzugang vorbereiten Die Bootstrap-Dateien können noch nicht auf dem LXC sein. Darum einmalig diese kurzen Befehle direkt in der LXC-Konsole ausführen: ```bash apt update apt install -y openssh-server sudo unzip adduser potatium usermod -aG sudo potatium systemctl enable --now ssh ``` `adduser` fragt dich interaktiv nach einem vorläufigen Benutzerpasswort. Lege dieses selbst fest (nicht in Chat/Git veröffentlichen!). Falls Benutzer `potatium` bereits vorhanden ist, den `adduser`-Schritt überspringen. Sicherstellen, dass der LXC eine erreichbare IP hat: ```bash hostname -I ``` **Falls SSH-Passwortauthentifizierung im Container deaktiviert ist:** Statt sie global unsicher freizuschalten, über die Proxmox-Konsole den öffentlichen SSH-Schlüssel unter `/home/potatium/.ssh/authorized_keys` für Benutzer `potatium` hinterlegen (Eigentümer `potatium`, Rechte `.ssh` = 700, `authorized_keys` = 600). Niemals einen privaten Schlüssel kopieren. ## 3. Das ZIP vom lokalen Rechner auf den LXC kopieren 1. `Potatium_Starterkit_2026-10-24.zip` hier herunterladen. 2. Auf deinem lokalen Mac/PC ein Terminal öffnen; `` durch die echte Adresse ersetzen. 3. Aus dem Verzeichnis, in dem das ZIP liegt, ausführen: ```bash scp Potatium_Starterkit_2026-10-24.zip potatium@:/home/potatium/ ssh potatium@ ``` Du landest nun als normaler Benutzer `potatium` auf dem LXC. Passwortloses SSH konfigurieren wir nach dem erfolgreichen Basischeck. ## 4. Archiv ins Workdir entpacken ```bash mkdir -p ~/src unzip -n ~/Potatium_Starterkit_2026-10-24.zip -d ~/src cd ~/src/potatium ls -la ``` Das ZIP enthält bereits den Ordner `potatium/` mit allen Dateien. **Nichts händisch nachbauen.** `-n` verhindert, dass ein erneutes Entpacken vorhandene Dateien überschreibt. ## 5. Ubuntu automatisch einrichten ```bash sudo bash scripts/setup_ubuntu26.sh ``` Dieses Skript: - prüft **Ubuntu 26.04 LTS**, installiert SSH/Git/Compiler/Basispakete; - sorgt für Benutzer `potatium` und `~/src`; - installiert **Go 1.27.3** für amd64 bzw. arm64 aus offiziellen Go-Archiven mit eingebauter SHA-256-Prüfung; - überschreibt eine andere vorhandene `/usr/local/go`-Installation ausdrücklich **nicht**. Eine erneute Anmeldung kann für geänderte Gruppenrechte hilfreich sein. Danach im Projektordner: ```bash cd ~/src/potatium bash scripts/bootstrap_workdir.sh bash scripts/doctor.sh ``` **Verzeichnisstruktur:** Das ZIP bringt sie schon mit; `bootstrap_workdir.sh` ergänzt fehlende Verzeichnisse wiederholbar und lässt existierende Dateien unverändert. Das Prüftool führt u. a. Go-Tests und `go vet` aus. `go.mod` verwendet für den allerersten lokalen Build den vorläufigen Modulnamen `potatium.local/potatium`. Sobald das private Remote bekannt ist, kann Codex den Modulnamen und alle zugehörigen Imports in einem konsistenten Commit umstellen. ## 6. Testweise die WebGUI-Vorschau öffnen ```bash cd ~/src/potatium make run-ui ``` Die Vorschau lauscht **nur auf 127.0.0.1:8080 im LXC**. Zum Anzeigen vom lokalen Rechner entweder später die VS-Code-Portweiterleitung für Port 8080 verwenden oder ein SSH-Tunnel in einem zweiten lokalen Terminal öffnen: ```bash ssh -L 8080:127.0.0.1:8080 potatium@ ``` Danach im lokalen Browser `http://127.0.0.1:8080` öffnen. **Wichtig:** Schaltflächen sind absichtlich deaktiviert. Keine echte Wallet, keine Coins, keine Blockchain! Abbrechen mit `Ctrl+C` im laufenden Go-Terminal. ## 7. Git-Repository anlegen Beim eigenen Git-Dienst deiner Wahl ein **neues privates, leeres** Repository `potatium` erstellen. Nicht zusätzlich README, Lizenz oder `.gitignore` initialisieren lassen, da diese bereits im ZIP vorliegen. Noch keine öffentliche Zugänglichkeit erforderlich. **Im LXC als `potatium`:** ```bash cd ~/src/potatium # Bereits angelegtes Git-Verzeichnis beibehalten; andernfalls neu initialisieren: test -d .git || git init -b main git branch -M main git config user.name "DEIN-GIT-NAME" git config user.email "DEINE-GIT-EMAIL" # Der SSH-Host-Alias "gitea" wurde bereits getestet. if git remote get-url origin >/dev/null 2>&1; then git remote set-url origin git@gitea:michael/potatium.git else git remote add origin git@gitea:michael/potatium.git fi # Vorher prüfen, dass keine privaten Schlüssel oder Secrets enthalten sind: git status --short git add . git diff --cached --stat git commit -m "chore: initialize Potatium project scaffold" git push -u origin main ``` `` ist die echte SSH-Clone-URL deines neuen Repos und **kein** wörtlich auszuführender Platzhalter. Wenn noch kein Git-SSH-Schlüssel existiert, vor dem Push einen separaten Schlüssel erzeugen und dessen öffentlichen Teil auf dem Git-Server hinterlegen: ```bash ssh-keygen -t ed25519 -f ~/.ssh/id_ed25519 -C "potatium-dev git" cat ~/.ssh/id_ed25519.pub ``` Bei bestehendem `~/.ssh/id_ed25519` nicht überschreiben! Stattdessen bestehenden Schlüssel verwenden oder einen separaten mit anderem Dateinamen und `~/.ssh/config`-Hostzuordnung erzeugen. Auch den Server-Fingerprint beim ersten SSH-Kontakt sorgfältig prüfen. **Nie** privaten Key, Seed oder Token ins Git pushen. Optional: Über `git status` sicherstellen, dass `bin/`, `.local-data/`, Secrets und `.env` ignoriert sind. Bis zur Architekturentscheidung noch kein produktives `mainnet`. ## 8. Lokalen Rechner mit VS Code verbinden 1. Auf Mac/PC **Visual Studio Code** installieren. 2. VS-Code-Erweiterung **Remote - SSH** installieren. 3. Optional auf dem Mac `ssh-keygen -t ed25519` ausführen (nur falls noch kein SSH-Schlüssel existiert); den **öffentlichen** Schlüssel am LXC hinterlegen. 4. Lokale Datei `~/.ssh/config` ergänzen: ```ssh-config Host potatium-dev HostName User potatium IdentityFile ~/.ssh/id_ed25519 ``` 5. In VS Code Befehl **Remote-SSH: Connect to Host...** → `potatium-dev`. 6. Auf dem Remote-Host Ordner `/home/potatium/src/potatium` öffnen. 7. Erweiterungen **Go** und **OpenAI Codex** installieren bzw. in der Remote-SSH-Sitzung nutzbar machen; über dein ChatGPT-Konto anmelden, sofern für deinen Plan verfügbar. 8. Integriertes Terminal: `bash scripts/doctor.sh`; anschließend Aufgabe **Potatium: Wallet Vorschau** wählen und **Port 8080 weiterleiten**. Die offizielle OpenAI-Erweiterung wird im VS-Code-Marktplatz als Codex angeboten. Die Datei `AGENTS.md` enthält verbindliche Arbeitsregeln für Codex. ## 9. Codex starten Datei `handoff/STARTPROMPT_VSCODE_CODEX.md` öffnen, **den Prompt-Text nach dem Trenner** kopieren und im Codex-Panel senden. Codex soll erst Repo und Tests überprüfen, offene Architekturfragen dokumentieren und dann kleine implementierbare Entwicklungsaufgaben planen. Nicht als Erstes „schreib die komplette Blockchain“ beauftragen: Kryptografie, State-Determinismus, Wallet und Lottery benötigen belastbare Entscheidungen und Tests. ## 10. ChatGPT-Projekt (optional, wenn du es weiter nutzen möchtest) Für das separate ChatGPT-Projekt **Potatium** den Text aus `handoff/CHATGPT_PROJEKTANWEISUNGEN.md` in die Projektanweisungen kopieren. Er ist unter **8.000 Zeichen**. Als Dateien `docs/PROJEKTPLAN.md`, `docs/PROTOKOLL_ENTWURF.md`, das ausgewählte Logo und gegebenenfalls weitere technische Dokumente hinzufügen. Für das Arbeiten in VS Code/Codex ist **keine weitere Information aus diesem Chat erforderlich**. Nötige Informationen sind im Git-Repository versioniert. Bei neuen verbindlichen Entscheidungen die Markdown-Dokumentation aktualisieren und committen. ## 11. Was du tatsächlich nach dem LXC-Start benötigst - Zugriff auf deine Proxmox-Oberfläche (für LXC, Snapshot und Konsole). - Eine interne LXC-IP und SSH-Zugang / **eigene** SSH-Schlüssel. - Das ZIP aus dieser Antwort. - Ein privates **leeres** Remote-Git-Repository samt SSH-Clone-URL und Zugriffsschlüssel. - VS Code samt Remote-SSH, Go und Codex auf deinem lokalen Rechner. - Zugriff auf offizielle Paket-/Go-Downloads aus dem LXC. - Später für PoP-Tests ein Raspberry Pi oder vergleichbar alter PC (anfangs nicht nötig). **Noch nicht benötigt:** Datenbankserver, Docker, externe Domain, HTTPS-Reverse-Proxy, Coin-Listing, echte Guthaben, ASIC/GPU, vier zusätzliche physische Server. ## 12. Minimaler Funktionstest / erwartete Ausgaben ```bash cd ~/src/potatium go version # go1.27.3 linux/amd64 oder linux/arm64 go test ./... # erfolgreiche Tests, mit CLI-Paketen ohne Tests go vet ./... # ohne Fehlermeldung make build # erzeugt 3 Placeholder-Binaries in bin/ ./bin/potatium-miner # meldet explizit: noch kein Mining ./bin/potatium-cli # meldet explizit: keine echte Wallet make run-ui # localhost:8080, statische WebGUI-Vorschau ``` Nach diesem Check ist **M0 technisch startbereit**. Für M1: `docs/PROTOKOLL_ENTWURF.md` und `docs/decisions/` gemeinsam mit Codex konkretisieren, bevor die ersten echten Ledger- und Wallet-Funktionen umgesetzt werden.