Skip to content

Atlas Ruling — FLAG-023 VPS Setup Plan (Architecture Baseline)

Make the VPS boring, local, reproducible, and hard to misuse.

1. OS Hardening — Required Baseline

Required before engine ever runs: - Create dedicated non-root deploy user - Disable root SSH login - Disable password SSH authentication (SSH keys only) - UFW enabled — allow inbound SSH only - Install fail2ban - Fully update packages - Set correct timezone + NTP - Confirm filesystem has enough free space for DB + backups + logs

Optional later: unattended-upgrades, Hetzner network firewall (belt-and-suspenders), auditd

Ruling: Required baseline = non-root user + SSH hardening + UFW + fail2ban + patch current packages.

2. Python Environment

Use: system Python + venv. Do not use conda. Do not use pyenv unless Orion has a specific reason.

  • Ubuntu 24.04 system Python
  • One project-local .venv
  • Pin Python version explicitly in project docs + environment setup
  • Lock dependencies with requirements file

3. Repo Deployment Method

Use: git clone from GitHub with a deploy key (read-only).

  • Not rsync. Not manual file copy.
  • No personal GitHub token on the box.
  • Deployment model: Orion delivers → Katja applies to main → server pulls from repo.

4. Database Migration

Ruling: Migrate existing data only if source DB passes integrity checks. Otherwise start from last clean recoverable backup. Do NOT carry forward known-corrupt state.

Safe procedure: 1. Stop all engine activity on local machine 2. Identify last clean DB artifact 3. Run PRAGMA integrity_check + PRAGMA wal_checkpoint(TRUNCATE) 4. Copy .db (and only if needed, consistent WAL/shm state) 5. On VPS: run PRAGMA integrity_check + PRAGMA journal_mode=WAL + PRAGMA wal_checkpoint(TRUNCATE) again

Rule: Only migrate a DB that has passed integrity cleanly. Trust beats nostalgia.

5. Process Management

Use: systemd.

Required: - Dedicated unit file - Working directory set explicitly - venv path explicit - stdout/stderr to journald - Restart=on-failure with small restart delay - Engine still fails closed on startup gate failures — no blind crash loop

6. Config File / Secrets Handling

Use: systemd EnvironmentFile + restricted permissions.

  • Secrets separated from main config where practical
  • Environment file readable only by deploy user / root
  • Never commit secrets into repo
  • Document exactly which variables are expected
  • Strategy/config values stay in YAML; secrets move to environment variables

7. SSH Key Security

Ruling: Generate a new ED25519 key with passphrase for server administration. Do not use the current no-passphrase key as the long-term admin key. Retire old key after transition.

8. Network / Firewall

Inbound: SSH (port 22) only
Outbound: as needed (GitHub, XRPL endpoints, package installs, backups)

No public dashboard, no public app ports, no inbound DB access. UFW on host is mandatory. Hetzner network-level firewall optional but fine to add.

9. Monitoring

Ruling: Manual logs + backup verification + basic service state is enough for initial VPS phase.

Required before live sessions on VPS: - Ability to inspect journald logs - Disk usage check - DB backup success/failure visibility - Simple "engine running / not running" visibility

Later: cron health check, alerting hooks, lightweight status dashboard. No full observability stack yet.

10. Migration Sequencing (confirmed + refined)

  1. Finish FLAG-048
  2. Run one meaningful validating local session on corrected anchor logic
  3. If signal behaves credibly, migrate to VPS
  4. Pursue clean sessions / Phase 7.4 on the VPS

Rule: Local validation first, migration second. Do not let the existence of the server rush the sequence.

11. Additional Architecture Rules

A. Engine is sole DB writer — permanent rule.
B. Analysis reads from copied artifacts — prefer DB snapshots, not the live file.
C. Backups are first-class — pre/post-session backups mandatory on VPS too.
D. No SMB / shared network filesystem in the runtime path — DB lives on local SSD. No exceptions.
E. One engine instance only — no accidental duplicate runners.

/opt/neo/
  repo/
  venv/
  runtime/
    db/
    backups/
    logs/
    exports/
  config/
    env/
    yaml/

Code separate from runtime state. Backups separate from live DB. Configs explicit.

13. Final Ruling Summary

Domain Decision
OS Ubuntu 24.04 LTS — harden minimally but correctly
Python System Python + venv
Repo git clone via deploy key
DB Migrate only from clean state — integrity checks before and after
Process systemd
Secrets EnvironmentFile with restricted permissions
SSH New passphrase-protected ED25519 key
Firewall SSH only inbound
Monitoring Lightweight, manual-first
Sequence Validate FLAG-048 locally first → migrate → clean-session proof on VPS

The VPS should not be clever. It should be stable.

— Atlas (CSO)
2026-04-22

Next: Orion and Vesper add implementation/audit notes. Atlas will review final deltas before first command execution if needed.