# Component Methods / Interfaces — atheos-blog-lxc

**Stage**: INCEPTION — Application Design (minimal depth)
**Note**: No business logic exists to specify. These are the **contracts between components** —
the things that must match or the stack silently fails (the classic 502 / permission-denied class).

## I-1 · nginx → php-fpm (the interface most likely to break)

```
nginx server block:
  listen 80;
  root /var/www/atheos;
  index index.php index.html;

  location = /index.php { fastcgi_pass unix:<FPM_SOCKET>; ... }
  location ~ \.php$    { fastcgi_pass unix:<FPM_SOCKET>; ... }
```

**Contract**: `<FPM_SOCKET>` in `nginx.conf` **must equal** the `listen =` path in the php-fpm pool.
Alpine's `php83-fpm` default differs between packages — resolve it from the installed
`/etc/php83/php-fpm.d/www.conf` rather than assuming.

- **Input**: HTTP request; **Output**: `text/html` from the PHP process
- **Failure mode if mismatched**: `502 Bad Gateway` (socket missing) — AC-2 fails

## I-2 · Atheos → filesystem (the write contract)

Atheos's installer requires **write access** to exactly these paths, relative to `/var/www/atheos`:

| Path | Why | Mode |
|---|---|---|
| `config.php` | installer writes the config; file must exist | writable by FPM user |
| `data/` | user accounts, settings | writable |
| `workspace/` | projects (incl. the `blog` clone) | writable |
| `plugins/` | plugin install/marketplace | writable |
| `themes/` | theme install | writable |

- **Owner/group**: the php-fpm run user (resolved from the pool config)
- **Failure mode**: installer shows a dependency error; AC-3 fails

## I-3 · Atheos (`codegit`) → git CLI

- **Requires**: `git` on `PATH`
- **Requires**: `safe.directory` for the workspace — otherwise git refuses with
  `detected dubious ownership` because the FPM user differs from the filesystem owner
- **Identity**: `user.name` / `user.email` are **deliberately UNSET** (design Q1=B).
  The operator sets them first thing after SSH (see RUNBOOK).
- **Failure mode**: "dubious ownership" errors, or commit refused for missing identity

## I-4 · git CLI → Gitea

- **Remote (initial)**: `https://git.aridgwayweb.com/armistace/blog.git` (public ⇒ no credential)
- **Remote (operator, later)**: `git@git.aridgwayweb.com:armistace/blog.git` — the RUNBOOK gives the
  exact `git remote set-url` command for after the key is added
- **Contract**: the agent must **not** alter the remote to SSH itself (FR-6/FR-11)

## I-5 · OpenRC service contract (not systemd)

| Service | Enable | Purpose |
|---|---|---|
| `nginx` | `rc-update add nginx default` | HTTP |
| `php-fpm83` | `rc-update add php-fpm83 default` | FastCGI (verify exact rc name on 3.23) |

- **Failure mode if not enabled**: works until first reboot, then AC-6 fails. This is why NFR-2 is
  verified with an actual reboot rather than a service-status check.