# 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.
- Installer logs must be stored outside this repository under `/var/log/atlas/install/`.
- Generated discovery and validation reports must be stored outside this repository under `/var/log/atlas/reports/`.
- 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.
- Future persistent installer state and marker files belong under `/var/lib/atlas/`.

## 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.
- Host validation thresholds are `/` 10 GiB, `/srv` 20 GiB, and `/sql` 20 GiB unless an approved implementation phase changes them.

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