potatium/START_HIER.md

🥔 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:

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:

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; <LXC-IP> durch die echte Adresse ersetzen.
3. Aus dem Verzeichnis, in dem das ZIP liegt, ausführen:

scp Potatium_Starterkit_2026-10-24.zip potatium@<LXC-IP>:/home/potatium/
ssh potatium@<LXC-IP>

Du landest nun als normaler Benutzer potatium auf dem LXC. Passwortloses SSH konfigurieren wir nach dem erfolgreichen Basischeck.

4. Archiv ins Workdir entpacken

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

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:

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

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:

ssh -L 8080:127.0.0.1:8080 potatium@<LXC-IP>

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:

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

<DEINE-GIT-SSH-URL> 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:

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:

Host potatium-dev
    HostName <LXC-IP>
    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

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.