abssctl Requirements & Project Plan
Note
The canonical requirements live in docs/requirements/abssctl-app-specs.txt.
This page includes that document so it is visible in the Sphinx build.
1Actual Budget Multi‑Instance Sync Server Admin CLI (abssctl)
2
3Document: Requirements & Project Plan
4File Name: abssctl-app-specs.txt
5Doc Version: v1.0‑draft‑5
6Date: 2025‑10‑05
7Maintainer(s): Ken Robinson ("DocCyblade") + collaborators
8License: MIT
9Canonical Runtime Target: TurnKey Linux Node.js v18 appliance (Debian base) — https://www.turnkeylinux.org/nodejs
10
11
12Naming
13Project: Actual Budget Multi‑Instance Sync Server Admin CLI
14CLI executable: abssctl (Actual Budget Sync Server ConTroL)
15
16-----------------------------------------------------------------------
170) Executive Summary
18Deliver a single Python‑based CLI, abssctl, that installs, configures, and manages multiple instances of the Actual Budget Sync Server on TurnKey Linux (Node.js v18). The CLI will be idempotent, auditable, and packaged for easy installation (PyPI/pipx), with first‑class docs (man pages + --help) and shell autocompletion.
19
20v1.0 Goals
21- One cohesive CLI to create → run → upgrade/rollback multi‑instance Actual Budget Sync server instances
22- Predictable filesystem layout, systemd service management, and nginx reverse‑proxy wiring per instance.
23- Per‑instance domain & port overrides; **HTTPS by default** using TurnKey’s system cert/key (or Let’s Encrypt if present); per‑instance/custom TLS supported.
24- Version manager for Actual Budget Sync Server (via npm) with list-versions and check-for-updates.
25- Doctor/health checks and support bundle for troubleshooting.
26- Robust documentation: README.rst, CHANGELOG.rst in project root for GitHub, detailed docs and developer doc source under /docs. Man pages are generated from source via Sphinx (build location finalized in ADR-002).
27
28Non‑Goals for v1.0
29- Migration importers from older tooling (explicitly not required).
30- Cross‑OS support; v1 targets TurnKey Linux Node.js appliance only.
31- Let’s Encrypt automation; other reverse proxies; web GUI; container images.
32
33-----------------------------------------------------------------------
341) Scope
35
361.1 In‑Scope (v1.0)
371. Language & Tooling: Python 3.11+ (type‑hinted), packaged for PyPI and pipx; dev on macOS (Visual Studio Code), runtime on TKL Node.js v18.
382. Actual Server lifecycle: install specific versions under /srv/app/vX.Y.Z, manage /srv/app/current symlink.
393. Instance lifecycle: create/list/show/env/start/stop/restart/enable/disable/status/logs/delete/rename/set‑fqdn/set‑port/set‑version.
404. System integration: generate/manage systemd unit per instance and nginx vhost per instance.
415. Version operations: list-versions (npm), check-for-updates (stable), install-version, switch-version, uninstall-version (safety checks).
426. Health & Support: doctor (validates environment/ports/services/nginx), support-bundle (configs + logs + checks).
437. Docs & UX: comprehensive --help, man pages, reStructuredText docs, and shell completion (Bash/Zsh/Fish/PowerShell); document sources are in reStructuredText.
448. Security model: dedicated service user (default actual-sync) with least privileges; strict file perms.
459. Global behaviors: --dry-run for all mutating commands, --quiet/--verbose logging levels, stable exit codes (0 success; 2 validation; 3 environment; 4 systemd/nginx errors), and --json for read‑only listings.
46
471.2 Out‑of‑Scope (v1.0)
48- Automated certificate issuance, non‑nginx proxies, clustering/HA, backup scheduling, Windows/macOS support.
49
50-----------------------------------------------------------------------
512) Success Criteria & KPIs
52- Fresh‑start TTV: From clean TKL Node.js v18 to one running instance behind nginx in ≤ 5 minutes using three commands: install-version, instance create, instance start.
53- Idempotency: Re‑running commands yields no destructive side‑effects; safe for automation.
54- Reliability: Verified upgrade & rollback across the current + 10 prior stable releases using the Manual Integration Test Protocol (ADR-030).
55- Docs: man abssctl renders, and abssctl --help covers basic commands/options with reference to man abssctl for full detail and examples; autocomplete works on Bash & Zsh.
56- Observability: doctor produces a clear pass/fail summary; support-bundle is complete and redacted.
57
58-----------------------------------------------------------------------
593) Personas
60- Admin‑Operator (primary): Installs and manages instances on TKL; prefers clear, safe, auditable operations.
61- Contributor (secondary): Adds features; maintains tests and docs.
62
63-----------------------------------------------------------------------
644) Architecture Overview
65
664.1 Components
67- CLI Core (abssctl) — command parsing, validation, logging, dry‑run engine, error taxonomy.
68- Providers — pluggable modules for:
69 - Version provider (npm registry lookup & installer).
70 - Service provider (systemd unit templating & control).
71 - Proxy provider (nginx vhost templating & control).
72- State Store — registry under /var/lib/abssctl/registry/{instances.yml,ports.yml}; global config at /etc/abssctl/config.yml; locks at /run/abssctl.lock and /run/abssctl/<instance>.lock.
73
744.2 Filesystem Layout (authoritative)
75/srv/backups/ # Backups root (owned by actual-sync:root 0750)
76 <instance>/ # Per-instance backup dir
77 YYYYMMDD-HHMMSS-<instance>-<shortid>.tar.{zst|gz} # backup archive (algorithm auto per ADR-021)
78 YYYYMMDD-HHMMSS-<instance>-<shortid>.sha256 # checksum file
79 manifest-<instance>.json # optional per-instance cache (derived from global)
80 backups.json # Global index of all backups (authoritative metadata)
81/srv/app/ # Actual server versions
82 v25.7.1/
83 v25.8.0/
84 current -> v25.8.0 # symlink to version of choice
85/srv/<instance>/ # Instance home
86 data/ # Actual config.json + data
87/etc/abssctl/
88 config.yml # Global defaults (config-only)
89/var/lib/abssctl/registry/
90 instances.yml # Instance registry (name, domain, port, version_binding, data_dir,...)
91 ports.yml # (optional) Reserved/allocated port registry to avoid collisions
92/etc/systemd/system/
93 <instance>-actual.service
94/etc/nginx/sites-available/
95 <instance>.conf
96/etc/nginx/sites-enabled/
97 <instance>.conf -> ../sites-available/<instance>.conf
98/var/log/abssctl/
99 abssctl.log, doctor.log, operations.jsonl
100/usr/share/abssctl/
101 VERSION # PKG_VERSION/PKG_COMPAT metadata
102/usr/local/bin/abssctl # CLI entrypoint (pipx installs here typically)
103
104
1054.3 Users & Permissions
106- Dedicated service user: actual-sync owns /srv/* trees; systemd units run as this user.
107- CLI requires root/sudo for mutating system changes; read‑only commands may run unprivileged.
108
1094.4 External Dependencies
110- Node.js v18 environment via TKL Node.js appliance.
111- npm available for Actual Budget Sync Server installation.
112- systemd & nginx present and enabled.
113
114
115-----------------------------------------------------------------------
1165) Detailed Functional Requirements
117
1185.1 Global Commands
119- abssctl version
120 Prints CLI Script-Version and package PKG_VERSION/PKG_COMPAT, and copyright notices.
121- abssctl doctor [--fix] [--verbose]
122 Validates: python/env, node/npm versions, npm reachability, presence of required tools (tar, zstd), service user & directory perms, free port scan, systemd unit status, nginx site syntax (no reload), instance TCP health checks. --fix performs non‑destructive remediation (create user, dirs, perms) where safe. Outputs summary to stdout and a JSON report with --json; exit code non‑zero on failures.
123- abssctl support-bundle [--no-redact] [--out PATH]
124 Collects configs, logs, versions, doctor output into a tarball; redacts sensitive paths by default can include if requested. Supports --json to print bundle metadata (path, size, redaction status).
125- abssctl backup create <instance> [--message|-m <text>] [--label <str>] [--data-only] [--out-dir PATH] [--compression {auto,zstd,gzip,none}] [--compression-level N] [--json]
126 Creates a point-in-time backup archive for the specified instance, recording a free‑text message and metadata into the global index. Default contents include the instance data dir, systemd unit, and nginx vhost. Writes a checksum alongside the archive.
127- abssctl backup list [<instance>] [--json]
128 Lists known backups from the metadata index; optionally filtered to a single instance. Shows id, timestamp, size, reason, and message.
129- abssctl backup verify [<backup-id>|--all]
130 Verifies archive presence and checksum; marks missing/corrupted entries in the index.
131- abssctl backup reconcile [--instance <name>|--all] [--dry-run]
132 Scans the filesystem under /srv/backups/ to detect archives not in the index (add) or index entries whose files are missing (mark as missing); can write changes or show a dry‑run.
133- abssctl backup prune [--keep N|--older-than <DURATION>] [--dry-run] - Removes old archives per simple policies; always updates the index. Disabled unless flags are provided.
134- abssctl list-versions [--latest N] [--include-prerelease=false]
135 Lists 10 recent versions from npm; clearly marks versions already installed locally. Supports --json for automation; clearly marks installed vs available.
136- abssctl check-for-updates
137 Compares installed vs available stable releases; suggests upgrades.
138- abssctl tls verify [--instance X] [--cert PATH --key PATH --chain PATH]
139 Validates TLS paths, key↔cert match, expiry (<30d warn), and permissions; never prints PEM bodies.
140- abssctl tls install --instance X --cert PATH --key PATH [--chain PATH]
141 Copies cert/key into standard locations with correct perms, updates vhost, tests with nginx -t, and reloads on success; prompts unless --yes.
142- abssctl tls use-system --instance X
143 Switches the instance back to system defaults (prefers Let’s Encrypt live certs if present, else TKL defaults).
144- abssctl install-version <X.Y.Z>
145 Installs Actual into /srv/app/vX.Y.Z; verifies integrity; does not switch running instances unless --set-current.
146- abssctl switch-version <X.Y.Z> [--restart=rolling|all|none]
147 Moves /srv/app/current and optionally restarts instances bound to current.
148- abssctl uninstall-version <X.Y.Z> [--force]
149 Removes version if no instance depends on it (or --force with warning).
150- Safety prompts: For sensitive operations (install-version, switch-version, uninstall-version, instance rename, instance delete, instance set-version), the CLI prompts to run backup create first. Use --no-backup to skip, or --backup-message <text> to annotate the backup.
151
1525.2 Instance Management
153- Note: On version changes, renames, or deletions, abssctl will offer to create a backup via backup create and annotate it with an auto‑generated reason (e.g., pre-switch-version) plus any user --message provided. Use --no-backup to bypass.
154- abssctl instance create <name> [--port <p>] [--domain <fqdn>] [--version <X.Y.Z>|current] [--data-dir /path] [--no-start] [--ssl-cert ssl.pem] [--ssl-key ssl.key]
155 Creates instance dir structure, writes minimal config.json, generates systemd & nginx, reserves port, starts service. Enforces <name> to match [a-z0-9-]+ and be unique. Optionally specify SSL cert/key otherwise default will be used
156- abssctl instance list [--long]
157 Shows instances with version binding (e.g., current->v25.8.0 or pinned), service state, domain & port. Supports --json for scripts.
158- abssctl instance show <name>
159 Displays resolved settings: paths, env, version binding, service & proxy locations, health summary, next steps.
160- abssctl instance env <name>
161 Prints environment variables (e.g., ACTUAL_DATA_DIR, config path) suitable for export.
162- abssctl instance set-fqdn <name> <fqdn>
163 Idempotently updates nginx vhost (syntax check + reload); zero‑downtime where possible.
164- abssctl instance set-port <name> <p>
165 Validates port availability; rewrites service & config; safe restart.
166- abssctl instance set-version <name> <X.Y.Z|current>
167 Binds instance to a specific version or current; safe restart.
168- abssctl instance rename <old> <new>
169 Atomically renames directories, units, vhosts, and registry entries; validates name/port collisions.
170- abssctl instance delete <name> [--purge-data]
171 Stops and disables service, removes system files; preserves data unless --purge-data.
172- abssctl start|stop|restart|enable|disable|status|logs <name>
173 Thin, friendly wrappers for systemd/journalctl with clear output.
174
175
1765.3 Reverse Proxy (nginx)
177- One vhost per instance; **HTTPS enabled by default** using system cert (or Let’s Encrypt if present); can be disabled or overridden per instance.
178- Sensible defaults: upstream 127.0.0.1:<port>, proxy headers, timeouts, gzip, body size (configurable).
179- On set-domain, re‑render (or rename) vhost safely, run nginx -t, then reload.
180- Graceful reload policy: prefer nginx reload over restart; on syntax failure, do not change symlinks and surface a clear error (exit code 4).
181- All changes follow ADR-032: write temp → atomic rename, validate with nginx -t, only then reload; rollback on failure.
182- TLS defaults: /etc/ssl/private/cert.pem and /etc/ssl/private/cert.key on TKL; if Let’s Encrypt live certs exist for the server_name, prefer those. Manage via
183 abssctl tls {verify,install,use-system}.
184
1855.4 Version Management (npm)
186- Default npm package name is configurable (default: @actual-app/sync-server); registry URL override supported.
187- Verify integrity (npm shasum) and record installs in a local manifest under /srv/app/.
188- list-versions annotates installed entries; optional --json output for scripting.
189
1905.5 Configuration & State
191- Global config /etc/abssctl/config.yml keys:
192 npm_package_name, install_root: /srv/app, instance_root: /srv, service_user: actual-sync, reverse_proxy: nginx,
193 tls: {enabled: true, system: {cert: /etc/ssl/private/cert.pem, key: /etc/ssl/private/cert.key}, lets_encrypt: {live_dir: /etc/letsencrypt/live}},
194 ports: {base: 5000, strategy: sequential}, state_dir: /var/lib/abssctl, default_version: current.
195- Config precedence: CLI flags > environment variables > /etc/abssctl/config.yml > built-in defaults. Environment variables use the ABSSCTL_* namespace (documented in --help).
196- Registry /var/lib/abssctl/registry/instances.yml: name, domain, port, version_binding (current|X.Y.Z), data_dir, created_at, last_changed, notes.
197- Optional port registry /var/lib/abssctl/registry/ports.yml: records reserved ports with owner instance and timestamp.
198- All writes are atomic (temp file then rename); files created with 0640 perms.
199- Locking via /run/abssctl.lock (global) and /run/abssctl/<instance>.lock (per-instance) to prevent concurrent mutations.
200
2015.6 Observability & Diagnostics
202- Structured logs (human + JSONL) with operation IDs to /var/log/abssctl/ (rc mapping per ADR-013/029).
203- Log rotation: rely on journald for CLI; recommend logrotate for /var/log/abssctl/*.log with sane defaults (weekly, rotate 4).
204- doctor report is machine‑readable and summarized for humans.
205- support-bundle redacts sensitive values (paths, TLS keys) by default.
206- doctor checks the backup index for drift vs on‑disk archives and suggests backup reconcile; backup verify performs checksum validation.
207
2085.7 UX, Help, Man Pages & Autocomplete
209- abssctl --help and per‑subcommand help include synopsis, options, examples, and exit codes.
210- Man pages are built in CI (Sphinx), shipped inside the wheel/sdist, and installed via
211
212 abssctl docs man install [--system|--user|--prefix PATH].
213- Implementation options (finalized via ADR):
214 - CLI framework: Typer (Click‑based) with built‑in completion by default
215 - Man page generation: Built in CI with Sphinx; installed via `abssctl docs man install`
216- Shell completion support for Bash, Zsh, Fish, and PowerShell via `abssctl completion {show,install,uninstall}`.
217
218
2195.8 Backup Operations
220Purpose: Provide a built‑in, auditable way to capture and track instance backups, annotate them with a message, and keep metadata consistent with on‑disk archives.
221
222Archive contents (default):
223- /srv/<instance>/data/ (Actual config.json + data)
224- /etc/systemd/system/<instance>-actual.service
225- /etc/nginx/sites-available/<instance>.conf
226- resolved symlink target of /srv/app/current (recorded as metadata only, not archived)
227
228Index & schema: The authoritative index lives at /srv/backups/backups.json (owned actual-sync:root, mode 0640). Each entry records who/when/why, where the archive is, and integrity details.
229Note: Archive extension reflects the algorithm used — ".tar.zst" for zstd or ".tar.gz" for gzip (see ADR-021).
230
231Example (abbreviated):
232{
233 "backups": [
234 {
235 "id": "20250929-154500-prod-abc123",
236 "instance": "prod",
237 "created_at": "2025-09-29T15:45:00Z",
238 "created_by": "root",
239 "reason": "pre-switch-version",
240 "message": "Before upgrading to v25.8.0",
241 "type": "full",
242 "archive_path": "/srv/backups/prod/20250929-154500-prod-abc123.tar.zst",
243 "size_bytes": 12345678,
244 "checksum_sha256": "<sha256>",
245 "instance_version": "v25.7.1",
246 "domain": "example.tld",
247 "port": 5000,
248 "includes": ["/srv/prod/data", "/etc/systemd/system/prod-actual.service", "/etc/nginx/sites-available/prod.conf"],
249 "status": "present"
250 }
251 ]
252}
253
254IDs & naming: Backups are named YYYYMMDD-HHMMSS-<instance>-<shortid> to ensure sortable, unique IDs. The same value is recorded as id in the index.
255
256Reconciliation: backup reconcile scans /srv/backups/ and updates backups.json to:
257- Add archives found on disk but missing from the index (with minimal metadata inferred).
258- Mark index entries whose files are missing as status: missing.
259- Optionally compute/repair checksums when absent or invalid.
260
261Integration with other commands: On sensitive ops (see §5.1 Safety prompts), the CLI offers to run backup create and auto‑populate the reason field (e.g., pre-delete, pre-rename, pre-switch-version). Users can append a --message.
262
263Retention: Simple pruning is provided via backup prune flags; no automatic scheduling in v1.0.
264
265Permissions: Archives and indexes are created with secure defaults (dirs 0750, files 0640).
266
267-----------------------------------------------------------------------
2686) Non‑Functional Requirements
269- Idempotent operations; atomic writes with rollbacks on provisioning failures.
270- Performance: list/show < 300 ms typical; create < 5 s.
271- CLI UX: all mutating commands accept --dry-run and print planned actions without making changes.
272- Security: least privilege, validated inputs (domains/ports/paths), perms: dirs 0750, files 0640, TLS keys 0600.
273- Compatibility: verify Actual/Node constraints at install time (parse npm metadata where available).
274- No telemetry; local logs only.
275- Backups integrity: archives accompanied by SHA‑256 checksum; index updates are atomic (write‑to‑temp then rename).
276- Backups performance: creating a default backup for a typical instance (< 200 MB data) completes within a reasonable time on TKL; operations are streamed to avoid excessive temp space.
277
278-----------------------------------------------------------------------
2797) Documentation & Repository Standards
280
2817.1 Documentation (Restructured Text first)
282- README.rst: What it is, quickstart for fresh TKL Node.js, install options (pipx/pip), post‑install checks (doctor), health URLs.
283- CHANGELOG.rst: Project‑wide history; reverse‑chronological; keepers note each release.
284- ADMIN‑GUIDE.rst: Operations, backup targets, TLS configuration.
285- SUDOERS‑EXAMPLES.rst: Optional minimal sudoers entries to allow specific abssctl subcommands for operators.
286- DEVELOPER‑GUIDE.rst: Dev setup (macOS), style, tests, release flow.
287- abssctl-app-specs.txt (this file): stored under docs/ requirements/.
288- Architecture Decision Records (ADRs) under docs/adrs/ (e.g., ADR‑001 Language/Framework [Python], ADR‑002 Docs/Man page pipeline, ADR‑003 Packaging).
289- Support Matrix: actual-support-matrix.rst (AUTO‑GENERATED from YAML via tools/gen_support_matrix.py).
290
2917.2 Python Doc Standards
292- Type hints everywhere; docstrings in Google or NumPy style; module headers include brief change log (last 10 entries) and link to global CHANGELOG.
293- Inline comments explaining system interactions (systemd/nginx/npm) and safety/rollback behavior.
294
2957.3 Proposed Repository Layout (new GitHub repo, name TBD)
296abssctl/
297├── pyproject.toml # PEP 621 metadata; console_scripts entry point
298├── src/
299│ └── abssctl/
300│ ├── __init__.py
301│ ├── cli.py # argparse/typer entrypoint
302│ ├── commands/ # subcommand implementations
303│ ├── providers/
304│ │ ├── versions.py # npm interactions
305│ │ ├── systemd.py
306│ │ └── nginx.py
307│ ├── config.py # load/save config.yml & registry
308│ ├── state.py # locking, operations log
309│ ├── logging.py
310│ ├── templates/ # jinja2 or string.Template systemd/nginx files
311│ └── utils.py
312├── docs/
313│ ├── README.rst
314│ ├── CHANGELOG.rst
315│ ├── ADMIN-GUIDE.rst
316│ ├── SUDOERS-EXAMPLES.rst
317│ ├── DEVELOPER-GUIDE.rst
318│ ├── requirements/
319│ │ └── abssctl-app-specs.txt
320│ ├── adrs/
321│ ├── support/
322│ │ ├── actual-support-matrix.yml
323│ │ └── actual-support-matrix.rst
324│ └── man/ # built man pages artifacts (release attachments; wheel includes abssctl/_man)
325├── tests/
326│ ├── unit/
327│ └── integration/
328├── .github/
329│ └── workflows/
330│ └── ci.yml # lint, test, package, build man pages
331├── MANIFEST.in
332├── .gitignore # Python, PyCharm, build artifacts, venv, dist
333└── LICENSE
334
335
3367.4 .gitignore (high‑level)
337- __pycache__/, *.pyc, .pytest_cache/, .mypy_cache/, .ruff_cache/
338- .venv/, .env, dist/, build/, *.egg-info/
339- .DS_Store
340
341-----------------------------------------------------------------------
3428) Packaging & Distribution
343- PyPI package name: abssctl (subject to availability).
344- Recommended install: pip install abssctl (system or venv) on servers.
345- Wheels built for Linux (manylinux where possible); no compiled extensions.
346- Post‑install hook or command to install shell completions (Bash/Zsh)
347- Man page generation in CI (Sphinx); `*.1` files embedded as package data (e.g., abssctl/_man/) and installable via `abssctl docs man install`. Downstream packagers may install into /usr/share/man/man1/.
348- Possible CI with GitHub to auto-package and upload to PyPI on tag on dev (dev build) and prod release on main/master tag
349
350-----------------------------------------------------------------------
3519) Testing Strategy
352- Unit tests: command parsing, validators, renderers, state transitions.
353- Integration (on TKL VM): install → create → start → health → switch version → rollback → delete.
354- Golden‑file tests: systemd & nginx templates.
355- Static checks: Ruff (lint), MyPy (types), Black (format).
356- Performance checks: simple timing asserts for list/show.
357
358-----------------------------------------------------------------------
35910) Security & Compliance
360- Run services as actual-sync; CLI mutating ops gated behind sudo/root.
361- Validate inputs (domains/ports/paths); sanitize shell invocation; avoid shell=True.
362- File permissions: enforce secure defaults; never write private keys world‑readable.
363- Redact secrets/keys from logs and support bundles.
364- Enforce secure process umask (027) at CLI start for file/dir creation defaults.
365
366-----------------------------------------------------------------------
36711) Risks & Mitigations
368- Registry drift (instances.yml ≠ disk reality): doctor detects & offers --fix.
369- npm upstream change/outage: support registry override & local caching; meaningful errors.
370- User data safety: deletions default to preserve data; --purge-data required for irreversible actions.
371- Backup index drift (files deleted/added manually): provide backup reconcile + doctor warnings; index entries can be marked missing instead of silently disappearing.
372- Nginx reload failure leaves site disabled: mitigate by validating with nginx -t before changing symlinks; roll back on error.
373- Port collisions during concurrent provisioning: mitigate by using ports.yml registry with file lock.
374
375-----------------------------------------------------------------------
37612) Removed
377
378-----------------------------------------------------------------------
37913) Roadmap & Milestones
380Planning — Finalize abssctl-app-specs.txt spec document
381
382Pre-Alpha — Repo Bootstrap (Pre-Alpha)
383- Create scaffold layout, add pyproject.toml, .gitignore, docs skeleton, CI with lint/test.
384
385Alpha Builds — Foundations
386- CLI skeleton, config loader, logging, state/lock, template engine, read‑only commands, JSON output plumbing. Setup PiPy project, Github CI auto publish to PyPi via tags to dev
387
388Beta Releases — Core Features
389- Version ops (list/install/switch), instance lifecycle, systemd/nginx providers, doctor basics. Once Beta builds are pushed to PyPi all updates need to be non-distructive or have hooks to update existing installs.
390
391Release Candidate — Quality & Docs (RC)
392- Support bundle, robust errors, man pages & completion, full docs & examples, Manual Integration Test Protocol (MITP) on a TKL VM. Setup githib CI auto publish to PyPi
393
394Release — v1.0.0 (RC → GA)
395- RC burn‑in on a clean TKL image across the support window (current + 10 prior); GA on green pipeline + docs sign‑off.
396
397-----------------------------------------------------------------------
39814) Acceptance Criteria (v1.0)
399- Installability: pipx install abssctl works; abssctl --help shows commands; manpages available after running
400
401 abssctl docs man install.
402- Functionality: From clean TKL node to running instance (HTTPS by default using system cert) in ≤ 5 minutes; custom certs work when supplied.
403- Versioning: list-versions shows the latest 10 from npm, marking installed ones; check-for-updates suggests newer stable.
404- Instance ops: set-domain and set-port are idempotent and safe; switch-version restarts bound instances as requested.
405- Health/Support: doctor is green on healthy systems; support-bundle includes all artifacts with redaction.
406- JSON: --json flags produce valid, documented JSON for list/show/doctor without breaking changes.
407- Backups: backup create persists an archive and metadata (including user message) and appears in backup list.
408- Safety prompts: Running a version change (e.g., switch-version) prompts for a backup; opting in creates a properly annotated backup.
409- Reconciliation: Removing an archive from disk and running backup reconcile marks the entry as missing; adding an orphaned archive adds it to the index.
410
411-----------------------------------------------------------------------
41217) Assumptions
413- The target platform is the TurnKey Linux Node.js v18 appliance; Debian services (systemd, nginx) are available.
414- Admins can use sudo/root for provisioning actions.
415- Internet access exists for npm installs, or an internal registry is configured.
416
417-----------------------------------------------------------------------
41818) Links
419- Github Repo: https://github.com/DocCyblade/abssctl
420- Github Repo Prod Releases : https://github.com/DocCyblade/abssctl/tree/main
421- Github Repo Dev Releases : https://github.com/DocCyblade/abssctl/tree/dev
422- Turnkey Linux: https://www.turnkeylinux.org
423- Turnkey Linux Node.js App: https://www.turnkeylinux.org/nodejs
424- Actual Budget: https://actualbudget.org
425- Actual Budget Docs: https://actualbudget.org/docs/
426- Actual Budget Sync Server CLI Docs: https://actualbudget.org/docs/install/cli-tool/
427- Actual Budget Sync Server (npm): https://www.npmjs.com/package/@actual-app/sync-server
428
429-----------------------------------------------------------------------
430
43119) ADR Template in Markdown Format
432- - - - Start of ADR Template in Markdown Format - - - -
433# ADR XXXX: <Short decision title>
434
435- **Date:** YYYY-MM-DD
436- **Status:** Proposed
437- **Authors:** <name(s)>
438- **Deciders:** <who approves>
439- **Consulted:** <who was consulted>
440- **Tags:** <e.g., licensing, docs, packaging>
441
442## Context
443<What problem are we solving? Include constraints, requirements, and relevant background.>
444
445## Options Considered
446- <Option A> — <one-sentence summary>
447- <Option B> — <one-sentence summary>
448- <Option C> — <one-sentence summary>
449
450## Decision
451<What did we decide and why? Point to the key drivers and trade-offs.>
452
453## Consequences
454- Positive: <benefit 1>
455- Positive: <benefit 2>
456- Negative / Risk: <risk 1 and how we’ll mitigate it>
457
458## Alternatives Considered (Details)
459<Briefly expand on why each major alternative wasn’t picked.>
460
461## Related
462- Supersedes: <ADR #> (if any)
463- Superseded by: <ADR #> (if any)
464- References: <links to issues/PRs/docs>
465- - - - End of ADR Template in Markdown Format - - - -
466
467
468End of Requirements & Project Plan for abssctl.