commit 451b5b28d761a76661895df217ba50b1ecd3fe37 Author: Nick Beckley Date: Fri Jul 10 10:31:48 2026 +0000 Establish Phase 1 Atlas infrastructure repository diff --git a/.gitignore b/.gitignore new file mode 100644 index 0000000..3bfe703 --- /dev/null +++ b/.gitignore @@ -0,0 +1,104 @@ +# Secrets and environment files +.env +.env.* +!.env.example +!.env.*.example +*.secret +*.secrets +secrets/ +credentials/ +local-secrets/ + +# Private keys and certificates +*.key +*.pem +*.p12 +*.pfx +*.crt +*.csr +*.jks +id_rsa +id_rsa.* +id_ed25519 +id_ed25519.* +*_rsa +*_rsa.* +*_ed25519 +*_ed25519.* + +# Local overrides +*.local +*.local.* +local/ +overrides/ +*.override +*.override.* + +# Logs +*.log +logs/ +log/ + +# Temporary files +tmp/ +temp/ +*.tmp +*.temp +*.swp +*.swo +*~ +.cache/ + +# Build outputs and dependencies +bin/ +obj/ +build/ +out/ +dist/ +publish/ +coverage/ +node_modules/ +.next/ +.nuxt/ + +# Deployment artefacts and archives +artifacts/ +artefacts/ +deployments/ +releases/ +*.zip +*.tar +*.tar.gz +*.tgz +*.7z + +# Backup artefacts and database dumps +/backups/ +/backup/ +*.bak +*.trn +*.bacpac +*.dacpac +*.dump +*.sql.gz +*.sql.zip + +# Package caches +.npm/ +.pnpm-store/ +.yarn/ +.pip-cache/ +vendor/cache/ +packages/ +*.deb +*.rpm + +# IDE and editor metadata +.vscode/ +.idea/ +*.code-workspace + +# OS metadata +.DS_Store +Thumbs.db +desktop.ini diff --git a/CHANGELOG.md b/CHANGELOG.md new file mode 100644 index 0000000..b750aac --- /dev/null +++ b/CHANGELOG.md @@ -0,0 +1,9 @@ +# Changelog + +All notable changes to this repository will be documented in this file. + +## Unreleased + +- Created the Phase 1 repository structure for `atlas`. +- Added baseline documentation for architecture, operating model, rebuild, disaster recovery, and server standards. +- Added the first Architecture Decision Record. diff --git a/README.md b/README.md new file mode 100644 index 0000000..327531b --- /dev/null +++ b/README.md @@ -0,0 +1,110 @@ +# Atlas AI Development Server + +Atlas is a dedicated AI development server used as the primary Linux host for source code, automation, development tooling, operational scripts, and future application deployment work. + +This repository is the authoritative infrastructure and operations source for Atlas. Its long-term purpose is to make the server rebuildable from a clean Ubuntu installation using documented, version-controlled, idempotent automation. + +## Current Server Summary + +The following facts are established for the current server: + +- Hostname: `atlas` +- Operating system: Ubuntu 26.04 LTS +- Static IP address: `192.168.10.10` +- CPU: AMD Ryzen 7 2700 +- Memory: 16 GB RAM +- OS storage: SSD using full-disk LVM, mounted at `/` +- SQL data volume: SSD mounted at `/sql` +- Development volume: SSD mounted at `/srv` +- Repository location: `/srv/repos/AI-Development-Server` +- Git remote: `git@git.catherinelynwood.com:atlas-bot/AI-Development-Server.git` + +Do not add unverified server details to this repository. Use `TODO: Confirm during the relevant implementation phase.` where information is not yet established. + +## Repository Purpose + +This repository will contain: + +- Atlas architecture and operating documentation. +- Server standards for scripts, services, configuration, deployment, and change control. +- Installation automation. +- Configuration templates. +- Operational scripts. +- Smoke tests and validation checks. +- Recovery and rebuild runbooks. +- Architecture Decision Records. +- Build history. + +It must not contain secrets, passwords, tokens, private keys, live credentials, database backups, generated deployment artefacts, or local machine state. + +## Design Principles + +- Git is the source of truth for infrastructure and operational intent. +- Changes should be documented before they are automated. +- Installation scripts must be idempotent and safe to rerun. +- Manual server changes should be reduced over time and recorded when they occur. +- Source, build artefacts, deployed applications, data, backups, and temporary files must remain separate. +- Secrets must live outside the repository. +- Planned components must not be documented as installed until verified. + +## Repository Layout + +```text +. +├── README.md +├── SERVER-STANDARDS.md +├── docs/ +│ ├── ARCHITECTURE.md +│ ├── BUILD-LOG.md +│ ├── REBUILD-GUIDE.md +│ ├── DISASTER-RECOVERY.md +│ ├── OPERATING-MODEL.md +│ └── adr/ +├── install/ +├── config/ +├── scripts/ +├── tests/ +├── templates/ +└── .gitignore +``` + +Directory-level README files explain what belongs in each working area. + +## Future Installation Model + +Future installation scripts will live under `install/`. They will be ordered, idempotent Bash scripts, for example: + +```text +install/01-base-tools.sh +install/02-dotnet.sh +install/03-sqlserver.sh +install/04-nginx.sh +install/05-docker.sh +``` + +These scripts do not exist yet. Until they do, rebuild steps remain manual and are documented in [docs/REBUILD-GUIDE.md](docs/REBUILD-GUIDE.md). + +## Change Control + +- Plan architecture and standards changes before implementation. +- Review diffs before committing. +- Run relevant validation before commit. +- Do not commit without explicit approval. +- Keep commits focused on one infrastructure outcome. +- Record meaningful operational changes in [docs/BUILD-LOG.md](docs/BUILD-LOG.md). + +## Roadmap Summary + +- Phase 1: Establish repository structure, standards, architecture documentation, rebuild guidance, disaster recovery guidance, operating model, and ADR process. +- Future phases: Add idempotent installation scripts, configuration templates, operational scripts, smoke tests, backup automation, restore automation, deployment automation, and monitoring. + +## Security Warning + +Never commit secrets or credentials. This includes `.env` files, passwords, tokens, private keys, certificates, SQL backups, Codex authentication material, deployment credentials, and backup encryption keys. + +Use templates, examples, placeholder names, and documented environment variable names instead. + +## Rebuild and Recovery + +- Rebuild procedure: [docs/REBUILD-GUIDE.md](docs/REBUILD-GUIDE.md) +- Disaster recovery: [docs/DISASTER-RECOVERY.md](docs/DISASTER-RECOVERY.md) diff --git a/SERVER-STANDARDS.md b/SERVER-STANDARDS.md new file mode 100644 index 0000000..f3d9b10 --- /dev/null +++ b/SERVER-STANDARDS.md @@ -0,0 +1,179 @@ +# Server Standards + +These standards apply to infrastructure documentation, installation scripts, operational scripts, configuration templates, tests, and manual server changes for Atlas. + +Unknowns must be written exactly as `TODO: Confirm during the relevant implementation phase.` + +## Bash Script Conventions + +- Use Bash for repository-managed server automation unless a better tool is explicitly adopted by an ADR. +- Start executable scripts with `#!/usr/bin/env bash`. +- Use `set -Eeuo pipefail`. +- Prefer explicit named variables over positional parameters. +- Quote variable expansions unless word splitting is intentional. +- Keep functions small and named by behaviour. +- Use long option names where they improve readability. +- Avoid hidden dependencies on the current working directory. Resolve paths explicitly. +- Place shared helpers only when repeated logic justifies them. + +## Idempotency + +- Scripts must be safe to run more than once. +- Check current state before making changes. +- Prefer create-or-update behaviour over delete-and-recreate behaviour. +- Do not assume users, packages, directories, mounts, services, firewall rules, or configuration files are absent. +- Print a clear message when a step is already satisfied. +- Avoid overwriting local state unless the script owns that file and has a documented rollback path. + +## Error Handling + +- Fail early when prerequisites are missing. +- Use meaningful error messages that identify the failed operation. +- Do not continue after a failed critical step. +- Use traps when cleanup or failure context is useful. +- Validate inputs before making changes. +- Treat unset variables as errors. + +## Logging + +- Print concise progress messages. +- Use consistent prefixes: `[INFO]`, `[WARN]`, `[ERROR]`, `[OK]`. +- Do not print secrets, tokens, passwords, connection strings, private keys, or certificate material. +- Long-term logs must be stored outside this repository. +- Repository scripts may write temporary logs only under documented temporary paths and must clean them up where practical. + +## Exit Codes + +- `0`: success. +- `1`: general failure. +- `2`: invalid arguments or missing required input. +- `3`: unmet prerequisite. +- `4`: validation failed. +- `5`: unsafe state detected. + +## File Ownership and Permissions + +- Repository files should be owned by the dedicated development user. +- Use executable permissions only for scripts intended to be run directly. +- Use root ownership only for system files that require it. +- Do not change ownership recursively outside documented paths. +- Secrets outside the repository must use the narrowest practical permissions. +- Templates in the repository must not contain live secrets. + +## Configuration Locations + +- Repository-managed templates belong under `config/` or `templates/`. +- Generated or live service configuration belongs in the service's normal system location, usually under `/etc`, and should be produced from repository templates where practical. +- Local overrides must not be committed. +- Application-specific paths must not be locked in until the relevant implementation phase confirms them. + +## Service Naming + +- Use clear, stable service names. +- Prefer names that identify the application or function rather than the implementation detail. +- Prefix Atlas-specific helper services consistently when a naming convention is established. +- Avoid renaming services without a migration and rollback note. +- Service naming convention: `TODO: Confirm during the relevant implementation phase.` + +## systemd Conventions + +- Store systemd unit templates under `config/systemd/` or `templates/` when introduced. +- Install live units under the appropriate systemd directory only through documented scripts. +- Run `systemctl daemon-reload` after unit changes. +- Enable services only when the intended boot behaviour is documented. +- Prefer environment files outside the repository for secret-bearing configuration. +- Include validation steps for service status and logs. + +## nginx Conventions + +- Store nginx templates under `config/nginx/` or `templates/` when introduced. +- Do not commit live TLS private keys or certificates. +- Validate nginx configuration before reloads. +- Reload nginx only after successful validation. +- Keep reverse proxy rules explicit and reviewed. +- Public DNS, TLS, and exposure policy: `TODO: Confirm during the relevant implementation phase.` + +## SQL Server Data Locations + +- `/sql` is the intended SQL data volume. +- SQL Server data, logs, and backups must not be stored in this repository. +- SQL Server paths must be confirmed during the SQL Server implementation phase before automation is created. +- Backup destination, retention, encryption, and restore validation are not yet established. + +## Repository Locations + +- `/srv` is the primary development volume. +- Git repositories should live under `/srv/repos`. +- This infrastructure repository lives at `/srv/repos/AI-Development-Server`. +- Do not assume application repository names or paths until they are confirmed. + +## Deployment Locations + +- Deployment locations must be outside this infrastructure repository. +- Deployed applications should be separated from source repositories and build artefacts. +- Intended deployment root: `TODO: Confirm during the relevant implementation phase.` +- Deployment scripts must document rollback and validation. + +## Backup Locations + +- Backups must not be committed. +- Backup storage location: `TODO: Confirm during the relevant implementation phase.` +- Backup retention: `TODO: Confirm during the relevant implementation phase.` +- Backup encryption: `TODO: Confirm during the relevant implementation phase.` +- Restore testing schedule: `TODO: Confirm during the relevant implementation phase.` + +## Temporary File Handling + +- Use `mktemp` for script-created temporary files and directories. +- Clean temporary files on exit where practical. +- Do not place temporary files in the repository unless they are intentionally version-controlled examples. +- Never store secret-bearing temporary files in world-readable locations. + +## Secrets Management + +- Never commit live secrets, tokens, passwords, private keys, SQL backups, `.env` files, generated credentials, or Codex authentication material. +- Use `.example`, `.template`, placeholder values, or documented environment variable names. +- Store secret-bearing live configuration outside the repository. +- Rotate credentials after suspected exposure. +- Secret storage mechanism: `TODO: Confirm during the relevant implementation phase.` + +## Package Installation + +- Installation scripts must use the system package manager where practical. +- Add third-party package repositories only when documented and justified. +- Validate repository signing keys and sources. +- Avoid installing packages in ad hoc scripts without recording why they are needed. +- Do not install application dependencies globally unless required. + +## Version Pinning + +- Pin versions when reproducibility, compatibility, or security requires it. +- Document why a version is pinned and when it should be reviewed. +- If using latest available packages, document that choice. +- Do not record planned component versions as installed until verified. + +## Testing Requirements + +- Add smoke tests for scripts that change services, network state, mounts, databases, deployments, or backup behaviour. +- Tests should verify observable outcomes, not only exit codes. +- Tests must avoid requiring secrets where practical. +- Tests must not mutate production data unless explicitly designed and approved. +- Run relevant tests before committing. + +## Documentation Requirements + +- Update documentation with every change that affects rebuild, operation, security, backup, restore, deployment, or architecture. +- Update [docs/BUILD-LOG.md](docs/BUILD-LOG.md) for meaningful manual or automated infrastructure milestones. +- Update runbooks when manual steps become automated. +- Link related ADRs where decisions are recorded. +- Use UK English. + +## Change Control + +- Plan substantial changes before implementation. +- Human approval is required for architecture changes. +- Review `git diff` before commit. +- Do not commit without explicit approval. +- Keep commits focused and reversible. +- Document rollback expectations for risky changes. +- Git rollback restores repository state only. It does not automatically undo server changes already applied. diff --git a/config/README.md b/config/README.md new file mode 100644 index 0000000..59a4513 --- /dev/null +++ b/config/README.md @@ -0,0 +1,43 @@ +# Config + +This directory is for repository-managed service configuration templates and configuration examples for Atlas. + +## What Belongs Here + +- nginx templates. +- systemd unit templates. +- SQL Server configuration templates. +- Non-secret example configuration. +- Documented placeholders for environment variables. + +## What Must Not Be Stored Here + +- Live configuration containing secrets. +- `.env` files. +- Private keys. +- TLS private keys or live certificates. +- Database backups. +- Machine-local overrides. + +## Naming Conventions + +- Use lower-case directory names. +- Use lower-case hyphenated file names. +- Use `.template`, `.example`, or `.sample` for files that are not live configuration. +- Use clear placeholder names such as `CHANGE_ME` or `${ENV_VAR_NAME}`. + +## Expected Future Structure + +Current planned areas include: + +```text +config/nginx/ +config/sqlserver/ +config/systemd/ +``` + +Additional service directories may be added when those services are implemented. + +## Security Considerations + +Configuration templates must not contain live secrets. Secret-bearing live files should be stored outside the repository and referenced by documented paths or environment variable names. diff --git a/config/nginx/.gitkeep b/config/nginx/.gitkeep new file mode 100644 index 0000000..8b13789 --- /dev/null +++ b/config/nginx/.gitkeep @@ -0,0 +1 @@ + diff --git a/config/sqlserver/.gitkeep b/config/sqlserver/.gitkeep new file mode 100644 index 0000000..8b13789 --- /dev/null +++ b/config/sqlserver/.gitkeep @@ -0,0 +1 @@ + diff --git a/config/systemd/.gitkeep b/config/systemd/.gitkeep new file mode 100644 index 0000000..8b13789 --- /dev/null +++ b/config/systemd/.gitkeep @@ -0,0 +1 @@ + diff --git a/config/templates/.gitkeep b/config/templates/.gitkeep new file mode 100644 index 0000000..8b13789 --- /dev/null +++ b/config/templates/.gitkeep @@ -0,0 +1 @@ + diff --git a/docs/ARCHITECTURE.md b/docs/ARCHITECTURE.md new file mode 100644 index 0000000..d589282 --- /dev/null +++ b/docs/ARCHITECTURE.md @@ -0,0 +1,193 @@ +# Atlas Architecture + +This document separates confirmed current architecture from planned architecture. Do not describe planned components as installed until they have been verified. + +## Current Architecture + +Atlas is a single physical development server. + +### Physical Server Overview + +- Hostname: `atlas` +- Operating system: Ubuntu 26.04 LTS +- Hardware model: ASUS PRIME B450-PLUS +- CPU: AMD Ryzen 7 2700 +- Memory: 16 GB RAM +- Architecture: x86-64 +- Role: AI development server and infrastructure automation host + +### Storage Layout + +- OS volume: SSD using LVM, mounted at `/` +- SQL data volume: SSD mounted at `/sql` +- Development volume: SSD mounted at `/srv` +- Repository root: `/srv/repos` +- Infrastructure repository: `/srv/repos/AI-Development-Server` + +The intended model separates operating system state, SQL data, and development data. This supports rebuild and recovery by reducing reliance on the OS volume for mutable project data. + +### Network Identity + +- Hostname: `atlas` +- Static IP address: `192.168.10.10` +- Default gateway: `192.168.10.1` +- Primary network interface: `enp3s0` +- Gitea SSH remote for this repository: `git@git.catherinelynwood.com:atlas-bot/AI-Development-Server.git` + +DNS, firewall, public exposure, and TLS policy are `TODO: Confirm during the relevant implementation phase.` + +### Repository and Source-Control Flow + +Git is the source of truth for repository state. Atlas holds the working copy under `/srv/repos/AI-Development-Server`, and Gitea is the remote source-control system for this infrastructure repository. + +Expected flow: + +1. Plan infrastructure changes in documentation. +2. Implement scripts, templates, or documentation updates. +3. Validate locally on Atlas. +4. Review the full diff. +5. Commit only after explicit approval. +6. Push reviewed commits to Gitea. + +Branching policy is `TODO: Confirm during the relevant implementation phase.` + +## Planned Architecture + +The repository is intended to grow into the version-controlled control plane for Atlas. Planned components include: + +- Idempotent installation scripts under `install/`. +- Managed configuration templates under `config/` and `templates/`. +- Operational scripts under `scripts/`. +- Smoke tests under `tests/`. +- Rebuild and recovery procedures under `docs/`. +- Architecture Decision Records under `docs/adr/`. + +### Intended Development Platform Components + +Atlas is intended to support: + +- Codex CLI usage. +- Git and Git LFS workflows. +- Node.js-based tooling where required. +- .NET SDKs when application requirements are confirmed. +- SQL Server when the database phase is implemented. +- nginx when reverse proxy requirements are confirmed. +- Docker when runtime policy is confirmed. +- Backup, restore, monitoring, and maintenance automation. + +Only components verified during implementation should be recorded as installed. + +### Intended PlotDirector Deployment Topology + +PlotDirector deployment topology is not yet established. + +Current assumptions: + +- Source repositories should live under `/srv/repos`. +- Build artefacts should be generated outside this infrastructure repository. +- Deployed applications should be separated from source repositories. +- SQL data should use `/sql` once SQL Server paths are confirmed. +- nginx may act as the reverse proxy if the application is exposed over HTTP or HTTPS. +- Docker may host one or more services if containerisation is adopted. + +Specific PlotDirector service names, ports, deployment paths, database names, and rollback procedures are `TODO: Confirm during the relevant implementation phase.` + +### Role of nginx + +nginx is planned as the likely local reverse proxy for HTTP and HTTPS applications. Its future responsibilities may include: + +- Routing requests to application services. +- TLS termination. +- Static file serving where appropriate. +- Request size, timeout, and header policy. + +nginx installation, site layout, TLS certificate handling, and exposure rules are `TODO: Confirm during the relevant implementation phase.` + +### Role of SQL Server + +SQL Server is planned as the relational database platform for applications that require it. `/sql` is the intended data volume. + +SQL Server version, data paths, backup paths, service account model, authentication policy, maintenance jobs, and restore process are `TODO: Confirm during the relevant implementation phase.` + +### Role of Docker + +Docker is planned as a possible application runtime and tooling boundary. It should be introduced only after the runtime policy is documented. + +Docker installation method, user access policy, network policy, volume locations, image retention, and compose layout are `TODO: Confirm during the relevant implementation phase.` + +## Separation of Concerns + +The intended storage and responsibility model is: + +- Source repositories: `/srv/repos` +- Infrastructure repository: `/srv/repos/AI-Development-Server` +- Build artefacts: `TODO: Confirm during the relevant implementation phase.` +- Deployed applications: `TODO: Confirm during the relevant implementation phase.` +- SQL data: `/sql` +- Backups: `TODO: Confirm during the relevant implementation phase.` +- Temporary files: system temporary locations or script-created `mktemp` paths +- Live secrets: outside this repository + +## Trust Boundaries + +Known trust boundaries: + +- Atlas local OS user accounts. +- SSH access to Atlas. +- SSH access from Atlas to Gitea. +- Root-level operations performed through `sudo`. +- Repository content versus live secret-bearing configuration. +- SQL data on `/sql` versus source and scripts on `/srv`. +- Future public-facing application traffic through nginx, if enabled. + +Unresolved trust-boundary details: + +- Firewall policy: `TODO: Confirm during the relevant implementation phase.` +- Production access model: `TODO: Confirm during the relevant implementation phase.` +- Secret storage model: `TODO: Confirm during the relevant implementation phase.` +- Backup encryption model: `TODO: Confirm during the relevant implementation phase.` + +## High-Level Diagram + +```mermaid +flowchart TB + Nick[Nick] -->|reviews plans and diffs| Git[Gitea Remote] + ChatGPT[ChatGPT] -->|planning and review support| Nick + Codex[Codex CLI on Atlas] -->|implements approved changes| Repo + Git <--> Repo[Infrastructure repository
/srv/repos/AI-Development-Server] + + subgraph Atlas[atlas
Ubuntu 26.04 LTS
192.168.10.10] + Repo + Source[Application source repositories
/srv/repos] + Install[Future install automation
install/] + Config[Future config templates
config/ and templates/] + Scripts[Future operational scripts
scripts/] + Tests[Future smoke tests
tests/] + SQL[(SQL data volume
/sql)] + Deploy[Future deployed applications] + Nginx[Future nginx reverse proxy] + Docker[Future Docker runtime] + end + + Repo --> Install + Repo --> Config + Repo --> Scripts + Repo --> Tests + Source --> Deploy + Deploy --> SQL + Nginx --> Deploy + Docker --> Deploy +``` + +## Decisions Not Yet Made + +- Backup destination, schedule, retention, encryption, and restore testing. +- SQL Server version, installation method, and data layout. +- nginx site layout, TLS model, and exposure policy. +- Docker installation method and runtime policy. +- PlotDirector topology, service names, ports, paths, and rollback process. +- Monitoring stack and alerting channels. +- Branching and release policy. +- CI model. +- Firewall policy. +- Production access model. diff --git a/docs/BUILD-LOG.md b/docs/BUILD-LOG.md new file mode 100644 index 0000000..b0673b1 --- /dev/null +++ b/docs/BUILD-LOG.md @@ -0,0 +1,102 @@ +# Build Log + +This file records chronological Atlas build and infrastructure milestones. Do not fabricate dates, command output, validation results, or operator names. + +## Entries + +### Date + +Not recorded. + +### Phase + +Baseline server preparation before Phase 1 repository completion. + +### Objective + +Prepare Atlas as a dedicated AI development server with storage, network, SSH, Git, Gitea access, Codex CLI, and standard development utilities. + +### Changes + +- Ubuntu 26.04 LTS installed. +- Hostname set to `atlas`. +- Static IP configured as `192.168.10.10`. +- OS SSD configured with full-disk LVM. +- OS logical volume expanded to use available LVM capacity. +- SQL SSD mounted at `/sql`. +- Development SSD mounted at `/srv`. +- SSH access configured. +- Gitea SSH authentication configured. +- Git installed. +- Git LFS installed. +- Node.js installed. +- Standard development utilities installed. +- Codex CLI installed and authenticated. +- Codex full-access mode configured with no approval prompts. +- Passwordless sudo configured for the dedicated development user. +- Infrastructure repository created and cloned at `/srv/repos/AI-Development-Server`. + +### Validation + +- Server identity and storage were later inspected during Phase 1 planning. +- Repository remote was later inspected during Phase 1 planning. +- Original command output was not captured in this repository. + +### Problems + +- No baseline problems were recorded in this repository. + +### Decisions + +- Atlas will use this repository as the authoritative infrastructure and operations source. +- Atlas will be rebuilt over time through documented, version-controlled, idempotent automation. + +### Git Commit + +Not yet committed. + +### Operator + +TODO: Confirm during the relevant implementation phase. + +## Entry Template + +Copy this template for future entries. + +```markdown +### Date + +YYYY-MM-DD + +### Phase + +Phase name or number. + +### Objective + +What this work was intended to achieve. + +### Changes + +- Change made. + +### Validation + +- Validation performed. + +### Problems + +- Problem encountered, or `None recorded.` + +### Decisions + +- Decision made, or `None recorded.` + +### Git Commit + +Commit hash, or `Not yet committed.` + +### Operator + +Name or role. +``` diff --git a/docs/DISASTER-RECOVERY.md b/docs/DISASTER-RECOVERY.md new file mode 100644 index 0000000..4a45fc4 --- /dev/null +++ b/docs/DISASTER-RECOVERY.md @@ -0,0 +1,283 @@ +# Disaster Recovery + +This document defines expected recovery scenarios for Atlas. It does not claim that backups currently exist unless they have been verified. + +Backup destination, retention, encryption, restore testing, and ownership are `TODO: Confirm during the relevant implementation phase.` + +## Recovery Principles + +- Protect source repositories and infrastructure history first. +- Keep secrets outside this repository. +- Prefer rebuild from documented automation over manual reconstruction. +- Validate restored services before returning them to use. +- Record recovery actions in [BUILD-LOG.md](BUILD-LOG.md). + +## OS Disk Failure + +### Impact + +- Ubuntu installation unavailable. +- System packages and live configuration on the OS disk unavailable. +- `/sql` and `/srv` may remain intact if their disks are healthy. + +### Required Backups + +- Ubuntu installation media. +- Repository access through Gitea or another verified copy. +- Copies of live system configuration not yet generated from this repository. +- Secrets and SSH keys from an approved location outside this repository. + +### Recovery Outline + +1. Replace the OS disk if required. +2. Reinstall Ubuntu 26.04 LTS. +3. Restore hostname, network, SSH, and sudo access. +4. Remount `/sql` and `/srv`. +5. Clone or use the existing infrastructure repository. +6. Run future installation automation when available. +7. Restore live configuration and services. + +### Validation + +- Hostname is `atlas`. +- Static IP address is `192.168.10.10`. +- `/sql` and `/srv` are mounted. +- Git can reach Gitea. +- Required services start and pass smoke tests. + +### Remaining Gaps + +- OS rebuild automation is not yet implemented. +- Live configuration inventory is not yet complete. + +## SQL Disk Failure + +### Impact + +- SQL data on `/sql` may be unavailable or lost. +- Applications depending on SQL Server may be unavailable. + +### Required Backups + +- Verified SQL backups from outside this repository. +- SQL Server installation and configuration documentation. +- SQL credentials from approved secret storage. + +### Recovery Outline + +1. Replace or repair the SQL disk. +2. Recreate filesystem and mount at `/sql`. +3. Reinstall or validate SQL Server. +4. Restore databases from verified backups. +5. Reapply permissions and maintenance jobs. + +### Validation + +- `/sql` is mounted. +- SQL Server starts. +- Databases are online. +- Application connectivity succeeds. +- Restore validation queries pass. + +### Remaining Gaps + +- SQL Server is not yet documented as installed by this repository. +- Backup location, retention, and restore procedure are not yet confirmed. + +## Development Disk Failure + +### Impact + +- `/srv` may be unavailable or lost. +- Local repository working copies, scripts in progress, build artefacts, and deployment material on `/srv` may be lost. + +### Required Backups + +- Gitea remote repositories. +- Any non-committed work that was backed up outside `/srv`. +- Deployment artefacts only if they cannot be rebuilt from source. + +### Recovery Outline + +1. Replace or repair the development disk. +2. Recreate filesystem and mount at `/srv`. +3. Recreate `/srv/repos`. +4. Clone required repositories from Gitea. +5. Recreate build and deployment directories from documented automation. + +### Validation + +- `/srv` is mounted. +- `/srv/repos` exists. +- Infrastructure repository is cloned. +- Required application repositories are cloned. +- Smoke tests pass where available. + +### Remaining Gaps + +- Application repository inventory is not yet documented. +- Build artefact and deployment location policy is not yet confirmed. + +## Complete Server Loss + +### Impact + +- All local OS, SQL, development, configuration, and service state may be lost. +- Recovery depends on external repositories, backups, installation media, and secret storage. + +### Required Backups + +- Gitea-hosted repositories or another off-server Git copy. +- SQL backups. +- Secret material from approved secret storage. +- Configuration not yet represented in this repository. +- Documentation needed to rebuild storage, network, and services. + +### Recovery Outline + +1. Replace or rebuild hardware. +2. Install Ubuntu 26.04 LTS. +3. Recreate storage layout with `/sql` and `/srv`. +4. Restore network identity. +5. Restore SSH and Gitea access. +6. Clone this repository. +7. Follow [REBUILD-GUIDE.md](REBUILD-GUIDE.md). +8. Restore databases and services from verified backups. + +### Validation + +- Server identity matches documented values. +- Repositories are restored. +- Required services pass validation. +- Applications pass smoke tests. +- Data restore is verified. + +### Remaining Gaps + +- Full rebuild is not yet automated. +- Off-server backup coverage has not been verified in this repository. + +## Accidental Repository Deletion + +### Impact + +- Local infrastructure working copy under `/srv/repos/AI-Development-Server` is lost. +- Uncommitted changes may be lost. + +### Required Backups + +- Gitea remote repository. +- Any external backup containing uncommitted work, if available. + +### Recovery Outline + +1. Recreate `/srv/repos` if needed. +2. Clone the repository from Gitea. +3. Confirm branch and remote. +4. Reapply any known uncommitted work only from trusted sources. + +### Validation + +- `git remote -v` shows the expected Gitea remote. +- `git status` is clean or only shows expected work. +- Required documentation and scripts are present. + +### Remaining Gaps + +- Uncommitted work recovery depends on external backups or manual reconstruction. + +## Failed Application Deployment + +### Impact + +- A deployed application may be unavailable, partially updated, or running an unintended version. +- Source repositories and this infrastructure repository should remain intact. + +### Required Backups + +- Previous known-good deployment artefact or source revision. +- Database backup if the deployment includes schema or data changes. +- Previous live configuration if changed. + +### Recovery Outline + +1. Stop or isolate the failed deployment if required. +2. Restore the previous artefact or redeploy the previous source revision. +3. Restore database state if required and approved. +4. Restore previous configuration if changed. +5. Validate application behaviour. + +### Validation + +- Service status is healthy. +- nginx routing works if applicable. +- Application smoke tests pass. +- Logs show no repeated startup or request failures. + +### Remaining Gaps + +- Deployment paths, rollback scripts, and smoke tests are not yet defined. + +## Configuration Corruption + +### Impact + +- Services may fail to start or may run with unintended settings. +- Secret-bearing live configuration may need manual restoration. + +### Required Backups + +- Repository-managed templates. +- Backup of live configuration files. +- Secret values from approved secret storage. + +### Recovery Outline + +1. Identify the corrupted configuration. +2. Compare live configuration with repository templates. +3. Restore from a known-good backup or regenerate from templates. +4. Reinsert secrets from approved storage without committing them. +5. Validate and reload affected services. + +### Validation + +- Service configuration validation passes. +- Service reload or restart succeeds. +- Logs show expected behaviour. +- Application smoke tests pass where available. + +### Remaining Gaps + +- Live configuration inventory and backup process are not yet complete. + +## Credential Compromise + +### Impact + +- Unauthorised access may be possible to Atlas, Gitea, databases, deployments, external APIs, or backups. +- Affected credentials must be rotated. + +### Required Backups + +- Not primarily a backup-driven recovery scenario. +- Requires access to credential authorities and secret storage. + +### Recovery Outline + +1. Identify affected credentials and access scope. +2. Revoke or rotate compromised credentials. +3. Review logs for misuse. +4. Update live systems with new credentials. +5. Confirm no secret values were committed to Git. +6. If a secret was committed, treat Git history and all clones as compromised for that secret. + +### Validation + +- Old credentials no longer work. +- New credentials work only where intended. +- Services using rotated credentials pass validation. +- Repository search finds no committed live secret values. + +### Remaining Gaps + +- Credential inventory, rotation schedule, and incident process are not yet confirmed. diff --git a/docs/OPERATING-MODEL.md b/docs/OPERATING-MODEL.md new file mode 100644 index 0000000..85e6322 --- /dev/null +++ b/docs/OPERATING-MODEL.md @@ -0,0 +1,140 @@ +# Operating Model + +This document defines how Nick, ChatGPT, and Codex work together on Atlas. + +## Roles + +- Nick owns architecture approval, operational judgement, production access decisions, and commit approval. +- ChatGPT supports planning, review, documentation, and implementation guidance. +- Codex runs on Atlas to inspect the repository, make approved changes, run validation, and report diffs. + +## Git as Source of Truth + +Git is the source of truth for repository-managed infrastructure and operational intent. + +- Infrastructure documentation belongs in this repository. +- Installation scripts must be version-controlled. +- Configuration templates must be version-controlled. +- Manual changes should be recorded and converted to automation where practical. +- Live secrets and generated artefacts must not be committed. + +## Documentation-First Changes + +Substantial changes should begin with documentation: + +1. Define the problem or objective. +2. Record relevant assumptions and unknowns. +3. Update standards, architecture, runbooks, or ADRs as needed. +4. Implement scripts or templates. +5. Validate the result. +6. Review the diff before commit. + +## Codex Planning Before Implementation + +Codex must inspect the repository and produce a plan before making architecture-level or broad repository changes. + +Implementation should start only after Nick approves the plan, unless the request is a narrow mechanical change that clearly does not affect architecture or operations. + +## Human Approval of Architecture + +Architecture decisions require human approval. Use ADRs for decisions that affect: + +- Infrastructure management approach. +- Service topology. +- Storage layout. +- Deployment model. +- Backup and recovery model. +- Security boundaries. +- Tooling choices with long-term maintenance impact. + +## Commit Control + +Codex must not commit unless explicitly instructed. + +Before commit: + +- Review `git status`. +- Review the full relevant diff. +- Run validation appropriate to the change. +- Confirm no secrets are present. +- Ensure documentation and implementation agree. + +## Branching Expectations + +Default branch: + +- `main` + +Branching model: + +- `TODO: Confirm during the relevant implementation phase.` + +Until a fuller branching model exists, keep work small, reviewable, and easy to revert. + +## Diff Review + +Every change should be reviewed with `git diff` before commit. + +Review should check: + +- Behavioural intent. +- File paths. +- Secrets exposure. +- Inconsistent terminology. +- Broken Markdown links. +- Missing validation. +- Unintended generated files. + +## Testing Before Commit + +Run the strongest practical validation before commit. + +For documentation-only changes, validation should include: + +- Repository tree inspection. +- Markdown link checks where practical. +- Search for accidental secrets. +- Search for inconsistent server names, IP addresses, and mount paths. +- `git diff --check`. + +For scripts and service changes, validation should also include syntax checks, dry runs where available, and smoke tests. + +## Rollback Expectations + +- Prefer changes that can be reversed through Git and idempotent scripts. +- Document rollback steps for service-affecting changes. +- Preserve previous configuration where practical before replacing live files. +- Remember that Git rollback does not automatically undo external system state. + +## Handling of Secrets + +- Do not commit secrets. +- Do not print secrets in logs or command output. +- Do not copy Codex authentication material into the repository. +- Use templates, examples, and documented environment variable names. +- Store live secrets outside this repository. +- Rotate credentials after suspected exposure. + +Secret storage mechanism is `TODO: Confirm during the relevant implementation phase.` + +## Handling of Production Access + +Production access must be deliberate and documented. + +- Do not assume development and production permissions are the same. +- Do not embed production credentials in scripts. +- Do not run production-impacting commands without explicit approval. +- Record deployment and rollback expectations before automating production changes. + +Production access model is `TODO: Confirm during the relevant implementation phase.` + +## Development and Production Responsibilities + +Atlas is currently documented as a development server. Future production responsibilities must be explicitly approved before they are added. + +Expected separation: + +- Development: source work, automation development, local validation, builds, and staging-like testing. +- Production: live application availability, production data protection, externally exposed endpoints, customer-impacting deployments, and incident response. + +Whether Atlas will host production workloads is `TODO: Confirm during the relevant implementation phase.` diff --git a/docs/REBUILD-GUIDE.md b/docs/REBUILD-GUIDE.md new file mode 100644 index 0000000..618e6f2 --- /dev/null +++ b/docs/REBUILD-GUIDE.md @@ -0,0 +1,165 @@ +# Rebuild Guide + +This guide describes the planned rebuild path for Atlas. At Phase 1, the repository contains documentation but no executable installation phases. Steps marked as TODO are not yet automated. + +## Automation Status + +- Repository structure and documentation: present. +- Installation scripts: not yet created. +- Configuration templates: not yet created. +- Operational scripts: not yet created. +- Smoke tests: not yet created. +- Backup and restore automation: not yet created. + +## Preconditions + +- Physical server hardware is available. +- Ubuntu 26.04 LTS installation media is available. +- Network details for Atlas are known. +- Gitea SSH access can be restored or re-created. +- Required secrets and private keys are available from an approved location outside this repository. +- Backups are available where required. + +Backup inventory and credential recovery process are `TODO: Confirm during the relevant implementation phase.` + +## 1. Ubuntu Installation + +1. Install Ubuntu 26.04 LTS on the OS SSD. +2. Set hostname to `atlas`. +3. Create the dedicated development user. +4. Configure administrative access for the development user. +5. Apply operating system updates. + +Exact installer choices, partitioning profile, and user creation procedure are `TODO: Confirm during the relevant implementation phase.` + +## 2. Storage Preparation + +Target storage layout: + +- OS volume mounted at `/` +- SQL data volume mounted at `/sql` +- Development volume mounted at `/srv` +- Repository root at `/srv/repos` + +Current Phase 1 status: + +- `/sql` is the intended SQL data volume. +- `/srv` is the primary development volume. +- Idempotent storage preparation scripts do not exist yet. + +Future rebuild work must document: + +- Disk identification method. +- Filesystem labels or UUIDs. +- `/etc/fstab` entries. +- Mount validation commands. +- Ownership and permissions. + +These details are `TODO: Confirm during the relevant implementation phase.` + +## 3. Network Setup + +Target identity: + +- Hostname: `atlas` +- Static IP address: `192.168.10.10` +- Default gateway: `192.168.10.1` +- Primary interface: `enp3s0` + +Configure DNS, host mappings, firewall rules, and public exposure only after the relevant policy is confirmed. + +DNS and firewall details are `TODO: Confirm during the relevant implementation phase.` + +## 4. SSH + +1. Install or enable OpenSSH. +2. Confirm SSH access from trusted administration clients. +3. Restore or create the SSH key needed for Gitea access. +4. Keep private keys outside this repository. + +SSH hardening policy, trusted client list, and key rotation procedure are `TODO: Confirm during the relevant implementation phase.` + +## 5. Repository Checkout + +Create the repository root if needed: + +```bash +sudo mkdir -p /srv/repos +``` + +Clone the infrastructure repository: + +```bash +cd /srv/repos +git clone git@git.catherinelynwood.com:atlas-bot/AI-Development-Server.git +cd AI-Development-Server +``` + +If the remote repository is unavailable, follow the disaster recovery guidance in [DISASTER-RECOVERY.md](DISASTER-RECOVERY.md). + +## 6. Bootstrap Process + +At Phase 1, bootstrap is manual. Future bootstrap should be reduced to a documented command sequence that runs idempotent scripts from this repository. + +Planned bootstrap flow: + +1. Review [README.md](../README.md). +2. Review [SERVER-STANDARDS.md](../SERVER-STANDARDS.md). +3. Review this rebuild guide. +4. Run base installation validation. +5. Run ordered installation scripts from `install/` when they exist. +6. Run smoke tests from `tests/` when they exist. + +Bootstrap command sequence is `TODO: Confirm during the relevant implementation phase.` + +## 7. Running Installation Phases + +Planned scripts may include: + +```text +install/01-base-tools.sh +install/02-dotnet.sh +install/03-sqlserver.sh +install/04-nginx.sh +install/05-docker.sh +``` + +These scripts do not exist yet. When created, each script must: + +- Be idempotent. +- Validate prerequisites. +- Log concise progress. +- Avoid printing secrets. +- Document rollback expectations. +- Include or reference validation steps. + +## 8. Validation + +Minimum rebuild validation should confirm: + +- Hostname is `atlas`. +- Static IP address is `192.168.10.10`. +- `/sql` is mounted. +- `/srv` is mounted. +- `/srv/repos` exists. +- Git can reach Gitea over SSH. +- This repository is checked out. +- Required installation phases have run successfully. +- Smoke tests pass. + +Validation scripts are `TODO: Confirm during the relevant implementation phase.` + +## 9. Restoring Services and Data + +Restoration order should be: + +1. Restore base OS access. +2. Restore storage mounts. +3. Restore repository access. +4. Run installation automation. +5. Restore configuration generated from templates. +6. Restore SQL data from verified backups. +7. Restore deployed applications or rebuild them from source. +8. Validate services and application behaviour. + +SQL backup location, deployment artefact policy, restore commands, and service validation are `TODO: Confirm during the relevant implementation phase.` diff --git a/docs/adr/0001-infrastructure-as-code.md b/docs/adr/0001-infrastructure-as-code.md new file mode 100644 index 0000000..980cca7 --- /dev/null +++ b/docs/adr/0001-infrastructure-as-code.md @@ -0,0 +1,33 @@ +# 0001: Infrastructure as Code + +## Status + +Accepted + +## Context + +Atlas is a dedicated AI development server intended to be rebuildable from a clean Ubuntu installation. The server needs a practical source of truth for architecture, standards, installation automation, configuration templates, operational scripts, tests, recovery procedures, architectural decisions, and build history. + +Manual server changes are difficult to audit and repeat. A repository-managed approach gives Atlas a reviewable history and creates a path toward reliable rebuilds. + +## Decision + +Atlas will be managed using Infrastructure as Code principles. + +This repository is the authoritative source for Atlas infrastructure and operations. Installation and operational automation will be implemented as documented, version-controlled, idempotent scripts. Configuration will be represented through repository-managed templates where practical. Unknown details will remain documented as TODOs until the relevant implementation phase confirms them. + +## Consequences + +- Infrastructure changes must be reviewable in Git. +- Manual changes should be documented and converted into automation where practical. +- Scripts must be safe to rerun. +- Documentation is part of the operational system and must be maintained. +- Secrets must remain outside the repository. +- Rebuild and recovery should become more reliable as automation is added. +- Initial progress may be slower because standards and documentation are created before automation. + +## Alternatives considered + +- Continue managing the server manually. This was rejected because it would make rebuilds, audits, and recovery harder. +- Use ad hoc scripts outside Git. This was rejected because it would not provide reliable history or review. +- Adopt a heavier configuration-management system immediately. This was deferred because Atlas is currently a single server and Bash scripts are sufficient for the initial phase. diff --git a/docs/adr/README.md b/docs/adr/README.md new file mode 100644 index 0000000..0d8f115 --- /dev/null +++ b/docs/adr/README.md @@ -0,0 +1,40 @@ +# Architecture Decision Records + +Architecture Decision Records capture decisions that affect the long-term structure, operation, security, or rebuildability of Atlas. + +## When to Create an ADR + +Create an ADR for decisions about: + +- Infrastructure management approach. +- Service topology. +- Storage layout. +- Deployment model. +- Backup and recovery model. +- Security and trust boundaries. +- Tooling choices with long-term maintenance impact. + +Small implementation details do not need ADRs unless they establish a precedent. + +## Naming Convention + +Use a four-digit sequence number and a short lower-case slug: + +```text +0001-infrastructure-as-code.md +0002-example-decision.md +``` + +Do not renumber existing ADRs. + +## Required Sections + +Each ADR should include: + +- Status +- Context +- Decision +- Consequences +- Alternatives considered + +Accepted ADRs remain part of the historical record. If a decision changes, create a new ADR that supersedes the earlier one. diff --git a/install/README.md b/install/README.md new file mode 100644 index 0000000..8027fad --- /dev/null +++ b/install/README.md @@ -0,0 +1,48 @@ +# Install + +This directory is reserved for ordered, idempotent installation scripts for Atlas. + +## What Belongs Here + +- Bootstrap scripts. +- Package installation scripts. +- Service installation scripts. +- Storage, runtime, and tooling setup scripts. +- Validation wrappers for installation phases. + +## What Must Not Be Stored Here + +- Secrets, passwords, tokens, private keys, or live credentials. +- One-off experiments. +- Generated logs. +- Downloaded package caches. +- Application source code. +- Deployment artefacts. + +## Naming Conventions + +Use a two-digit numeric prefix followed by a short lower-case hyphenated name: + +```text +01-base-tools.sh +02-dotnet.sh +03-sqlserver.sh +04-nginx.sh +05-docker.sh +``` + +Scripts must follow [SERVER-STANDARDS.md](../SERVER-STANDARDS.md). + +## Expected Future Structure + +Phase scripts may be added directly under this directory at first. If the directory grows, shared helpers may be added under a clearly named subdirectory. + +Future structure is `TODO: Confirm during the relevant implementation phase.` + +## Security Considerations + +- Use `sudo` only for commands that need it. +- Do not print secrets. +- Do not embed credentials. +- Validate package sources and signing keys. +- Make scripts safe to rerun. diff --git a/scripts/README.md b/scripts/README.md new file mode 100644 index 0000000..a8dc793 --- /dev/null +++ b/scripts/README.md @@ -0,0 +1,49 @@ +# Scripts + +This directory is for operational scripts used after Atlas is installed. + +## What Belongs Here + +- Backup scripts. +- Restore scripts. +- Deployment scripts. +- Maintenance scripts. +- Monitoring scripts. +- Service validation helpers. + +## What Must Not Be Stored Here + +- Installation phase scripts. Those belong in `install/`. +- Secrets or credentials. +- Generated logs. +- Temporary files. +- Build artefacts. +- One-off experimental commands. + +## Naming Conventions + +- Use lower-case hyphenated names. +- Prefer verb-target names, such as `backup-sql.sh` or `check-disk-space.sh`. +- Group scripts by operational area when useful. +- Executable permissions should be used only for scripts intended to run directly. + +## Expected Future Structure + +Current planned areas include: + +```text +scripts/backup/ +scripts/deploy/ +scripts/maintenance/ +scripts/monitoring/ +scripts/restore/ +``` + +Additional areas may be added when a repeated operational need exists. + +## Security Considerations + +- Do not print secrets. +- Do not store credentials in scripts. +- Make destructive actions explicit and documented. +- Include validation and rollback guidance for service-affecting scripts. diff --git a/scripts/backup/.gitkeep b/scripts/backup/.gitkeep new file mode 100644 index 0000000..8b13789 --- /dev/null +++ b/scripts/backup/.gitkeep @@ -0,0 +1 @@ + diff --git a/scripts/deploy/.gitkeep b/scripts/deploy/.gitkeep new file mode 100644 index 0000000..8b13789 --- /dev/null +++ b/scripts/deploy/.gitkeep @@ -0,0 +1 @@ + diff --git a/scripts/maintenance/.gitkeep b/scripts/maintenance/.gitkeep new file mode 100644 index 0000000..8b13789 --- /dev/null +++ b/scripts/maintenance/.gitkeep @@ -0,0 +1 @@ + diff --git a/scripts/monitoring/.gitkeep b/scripts/monitoring/.gitkeep new file mode 100644 index 0000000..8b13789 --- /dev/null +++ b/scripts/monitoring/.gitkeep @@ -0,0 +1 @@ + diff --git a/scripts/restore/.gitkeep b/scripts/restore/.gitkeep new file mode 100644 index 0000000..8b13789 --- /dev/null +++ b/scripts/restore/.gitkeep @@ -0,0 +1 @@ + diff --git a/templates/README.md b/templates/README.md new file mode 100644 index 0000000..def9f6c --- /dev/null +++ b/templates/README.md @@ -0,0 +1,36 @@ +# Templates + +This directory is for reusable templates that do not belong to one specific service directory under `config/`. + +## What Belongs Here + +- Generic environment file examples. +- Reusable script templates. +- Documentation templates. +- Deployment manifest examples. +- Non-secret placeholder files. + +## What Must Not Be Stored Here + +- Live `.env` files. +- Passwords, tokens, private keys, or certificates. +- Generated credentials. +- Live service configuration. +- Build artefacts. +- Backups. + +## Naming Conventions + +- Use lower-case hyphenated names. +- Use `.template`, `.example`, or `.sample` suffixes where appropriate. +- Use obvious placeholder values such as `CHANGE_ME` or `${ENV_VAR_NAME}`. + +## Expected Future Structure + +Subdirectories may be introduced when templates grow beyond a small number of files. + +Future structure is `TODO: Confirm during the relevant implementation phase.` + +## Security Considerations + +Templates are version-controlled and must be safe to publish to anyone with repository access. Never include a live credential, even temporarily. diff --git a/tests/README.md b/tests/README.md new file mode 100644 index 0000000..5429edd --- /dev/null +++ b/tests/README.md @@ -0,0 +1,39 @@ +# Tests + +This directory is for smoke tests and validation checks for Atlas infrastructure. + +## What Belongs Here + +- Smoke tests for installation phases. +- Validation checks for mounts, services, network identity, and repository state. +- Script syntax checks. +- Non-secret test fixtures. + +## What Must Not Be Stored Here + +- Secrets. +- Real production data. +- SQL backups. +- Large generated test output. +- Package caches. +- Environment-specific local overrides. + +## Naming Conventions + +- Use lower-case hyphenated names. +- Prefer names that describe the observable behaviour being checked. +- Group tests by area when useful, for example `tests/smoke/`. + +## Expected Future Structure + +Current planned areas include: + +```text +tests/smoke/ +``` + +Additional test groups should be added only when they have clear ownership and purpose. + +## Security Considerations + +Tests must not expose secrets or mutate production data unless explicitly designed and approved. Prefer read-only validation where practical. diff --git a/tests/smoke/.gitkeep b/tests/smoke/.gitkeep new file mode 100644 index 0000000..8b13789 --- /dev/null +++ b/tests/smoke/.gitkeep @@ -0,0 +1 @@ +