atlas-bot/AI-Development-Server
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Establish Phase 1 Atlas infrastructure repository

Browse Source
This commit is contained in:
Nick Beckley 2026-07-10 10:31:48 +00:00
commit 451b5b28d7
26 changed files with 1583 additions and 0 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

104
.gitignore vendored Normal file
View File

@ -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

9
CHANGELOG.md Normal file
View File

@ -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.

110
README.md Normal file
View File

@ -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)

179
SERVER-STANDARDS.md Normal file
View File

@ -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.

43
config/README.md Normal file
View File

@ -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.

1
config/nginx/.gitkeep Normal file
View File

@ -0,0 +1 @@

1
config/sqlserver/.gitkeep Normal file
View File

@ -0,0 +1 @@

1
config/systemd/.gitkeep Normal file
View File

@ -0,0 +1 @@

1
config/templates/.gitkeep Normal file
View File

@ -0,0 +1 @@

193
docs/ARCHITECTURE.md Normal file
View File

@ -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<br>/srv/repos/AI-Development-Server]
subgraph Atlas[atlas<br>Ubuntu 26.04 LTS<br>192.168.10.10]
Repo
Source[Application source repositories<br>/srv/repos]
Install[Future install automation<br>install/]
Config[Future config templates<br>config/ and templates/]
Scripts[Future operational scripts<br>scripts/]
Tests[Future smoke tests<br>tests/]
SQL[(SQL data volume<br>/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.

102
docs/BUILD-LOG.md Normal file
View File

@ -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.
```

283
docs/DISASTER-RECOVERY.md Normal file
View File

@ -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.

140
docs/OPERATING-MODEL.md Normal file
View File

@ -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.`

165
docs/REBUILD-GUIDE.md Normal file
View File

@ -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.`

33
docs/adr/0001-infrastructure-as-code.md Normal file
View File

@ -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.

40
docs/adr/README.md Normal file
View File

@ -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.

48
install/README.md Normal file
View File

@ -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.

49
scripts/README.md Normal file
View File

@ -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.

1
scripts/backup/.gitkeep Normal file
View File

@ -0,0 +1 @@

1
scripts/deploy/.gitkeep Normal file
View File

@ -0,0 +1 @@

1
scripts/maintenance/.gitkeep Normal file
View File

@ -0,0 +1 @@

1
scripts/monitoring/.gitkeep Normal file
View File

@ -0,0 +1 @@

1
scripts/restore/.gitkeep Normal file
View File

@ -0,0 +1 @@

36
templates/README.md Normal file
View File

@ -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.

39
tests/README.md Normal file
View File

@ -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.

1
tests/smoke/.gitkeep Normal file
View File

@ -0,0 +1 @@