214 lines
7.9 KiB
Markdown
214 lines
7.9 KiB
Markdown
# 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/`.
|
|
- Shared installer framework libraries under `install/lib/`.
|
|
- 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
|
|
|
|
Native SQL Server packages are not currently used because Microsoft does not publish a supported native SQL Server repository for Ubuntu 26.04. Atlas runs SQL Server 2025 Developer through Microsoft's official Linux container image instead.
|
|
|
|
- Compose project: `atlas-sql`
|
|
- Container: `atlas-sql-server`
|
|
- Image: `mcr.microsoft.com/mssql/server:2025-CU1-ubuntu-24.04`
|
|
- Digest: `sha256:698682bab57c02c42bc0aa274b158aeb242d8e9104149a7489628d5535805816`
|
|
- Edition: SQL Server 2025 Developer
|
|
- Product version: `17.0.4006.2`
|
|
- Persistent storage: `/sql/mssql`
|
|
- Secret environment file: `/etc/atlas/sql-server.env`
|
|
|
|
The live SQL administrator password is not stored in Git.
|
|
|
|
### Role of Docker
|
|
|
|
Docker Engine is installed from Docker's official signed Ubuntu APT repository for `resolute`.
|
|
|
|
- Docker Engine: `29.6.1`
|
|
- Docker Compose plugin: `v5.3.1`
|
|
- Docker Buildx plugin: `v0.35.0`
|
|
- containerd.io: `2.2.5`
|
|
- User `nick` is a member of the `docker` group.
|
|
|
|
A new login may be required before all shells pick up Docker group membership.
|
|
|
|
## Separation of Concerns
|
|
|
|
The intended storage and responsibility model is:
|
|
|
|
- Source repositories: `/srv/repos`
|
|
- Infrastructure repository: `/srv/repos/AI-Development-Server`
|
|
- Installer logs: `/var/log/atlas/install/`
|
|
- Discovery and validation reports: `/var/log/atlas/reports/`
|
|
- Future installer state and markers: `/var/lib/atlas/`
|
|
- Build artefacts: `TODO: Confirm during the relevant implementation phase.`
|
|
- Deployed applications: `TODO: Confirm during the relevant implementation phase.`
|
|
- SQL data: `/sql`
|
|
- SQL Server container storage: `/sql/mssql`
|
|
- 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.
|