Files
kaoyan/docs/superpowers/plans/2026-10-11-debian-server.md
T

4.3 KiB
Raw Blame History

Debian server implementation plan

For agentic workers: Use superpowers:executing-plans to implement this plan inline, with a fresh whole-branch reviewer.

Goal: Run the existing workbench continuously on the user's Debian 12 server with MariaDB, a managed proxy pool, randomized pacing, and preserved collected data.

Architecture: Keep SQLite as the local default. Add a MySQL database adapter behind the existing Database interface, Linux credential encryption and fixed systemd pool management. Serve the single-worker application on loopback behind authenticated HTTPS.

Tech Stack: Python 3.11+, FastAPI, PyMySQL, cryptography, React, MariaDB 10.11, systemd, Nginx, proxy_pool, dedicated Redis.

Spec: ../specs/2026-10-11-debian-server-design.md

Global Constraints

  • Preserve the currently running Windows collection.
  • Never print or commit cookies, encryption keys, database passwords, or access passwords.
  • Reuse SSH connections; do not alter existing databases or unrelated services.
  • Random request bounds: 0.3–60 seconds; server proxy rotation: 100 successful requests.
  • No automated captcha solving; no inherited login verification after migration.

Review Focus

  • Same-name cookies across CHSI domains must survive encrypted migration.
  • Normalized department names and special-plan score rules must match SQLite results.
  • Failed migrations must not leave a partly imported database; source remains untouched.
  • Automatic rotation must not split the SSO binding and access proof across proxies.
  • Manual pause and login-wait states must survive service restart without automatic resumption.

Task 1: Random pacing and proxy rotation

Files: studio/settings.py, studio/network.py, studio/auth.py, tests/test_server_features.py.

  • Add failing tests for varied bounded delays, invalid bounds, automatic route changes, and pinned verification.
  • Implement interval maximum and proxy rotation settings, actual request route/count reporting, and route pinning during auth verification.
  • Run network and auth tests, then commit.

Task 2: MariaDB backend and migration

Files: studio/mysql_database.py, studio/migrate.py, studio/api.py, tests/test_mysql.py, pyproject.toml.

  • Write tests against a real isolated MariaDB database for upserts, historical scopes, favorites, jobs, and atomic migration.
  • Implement MySQLDatabase.connection(), preserving the existing Database API; load private database configuration through STUDIO_DATABASE_CONFIG.
  • Implement migrate_sqlite(source, target) preserving IDs, logs and unit keys and rejecting nonempty targets.
  • Verify all existing tests and real MariaDB integration tests, then commit.

Task 3: Linux operation and user interface

Files: studio/auth.py, studio/linux_pool.py, studio/pool_service.py, studio/__main__.py, studio/api.py, frontend/src/App.tsx, frontend/src/types.ts.

  • Add failing tests for Linux vault roundtrip/permissions, server host filtering, and interrupted-task recovery selection.
  • Implement encrypted Linux storage, explicit manual-cookie login instructions, Linux systemd pool controls, configured hosts/data directory, and opt-in restart resumption.
  • Add interval range, rotation settings and counters to the UI; use capability metadata for platform instructions.
  • Run full backend tests and frontend tests/build, then commit.

Task 4: Provision, migrate, and deploy

Files: deploy/*, docs/debian-deployment.md, README.md.

  • Prepare reproducible systemd, Nginx and private configuration templates with rollback and backup instructions.
  • Provision independent MariaDB account/database, dedicated loopback Redis, proxy pool and workbench services.
  • Transfer online SQLite backup and credentials through SSH without exposing secrets; verify migrated data and server login.
  • Validate authenticated IP HTTPS, browser workflows, proxy API/scheduler and restart persistence; preserve the manually paused migrated task and report its actual login state.
  • Fresh reviewer checks the whole branch; fix material findings and verify again. Publish the deployment branch to the user's repository.

External follow-up

  • User changes CDN origin to HTTPS 443; verify public domain access afterward. Authenticated IP HTTPS access is already available.