All apps live under `apps/` in the workspace and share dependencies via the root `Cargo.toml`. Shared crates live under `crates/`:

- `andromeda-auth` — password verify, session token, cookie helpers

- `andromeda-db` — DB connection helpers, optional `session` feature

- `andromeda-darkmatter-css` — shared CSS theme

andromeda-db = { workspace = true, features = ["session"] }  # if using session auth

andromeda-darkmatter-css = { workspace = true }              # if using shared theme

After creating the app, register it in the workspace root `Cargo.toml` under `[workspace] members`. See **Wiring up a new app** below for the full set of workspace files to update.

Multi-stage workspace build using `cargo-chef` for dep caching. Built from repo root with `docker build -f apps/APP_NAME/Dockerfile .`:

FROM lukemathwalker/cargo-chef:latest-rust-1-slim-bookworm AS chef

FROM chef AS planner

COPY . .

RUN cargo chef prepare --recipe-path recipe.json

FROM chef AS builder

RUN apt-get update && apt-get install -y pkg-config libssl-dev && rm -rf /var/lib/apt/lists/*

COPY --from=planner /app/recipe.json recipe.json

RUN cargo chef cook --release --recipe-path recipe.json -p APP_NAME

COPY . .

Replace all `APP_NAME` with actual binary/package name. If app makes HTTPS requests (uses reqwest etc.), add `RUN apt-get update && apt-get install -y ca-certificates && rm -rf /var/lib/apt/lists/*` to final stage.

## Wiring up a new app

A new app is not done when `cargo run -p APP_NAME` works. Several workspace-level files list every app explicitly and must be updated, or CI/release/deploy break silently.

### 1. Workspace root `Cargo.toml`

Add to `[workspace] members`:

```toml

[workspace]

members = [

    "apps/sipp",

    # ...

    "apps/APP_NAME",

    "crates/auth",

    "crates/db",

    "crates/darkmatter-css",

]

```

### 2. `dist-workspace.toml`

Add to `[workspace] members` so `cargo dist` builds release binaries + Homebrew formula:

```toml

[workspace]

members = [

    "cargo:apps/sipp",

    # ...

    "cargo:apps/APP_NAME",

]

```

### 3. `.github/workflows/docker.yml`

Two spots — both list every app:

```yaml

ALL='["cellar","sipp","feeds","parcels","jotts","og","shrink","backup","posts","library","APP_NAME"]'

```

```yaml

for app in cellar sipp feeds parcels jotts og shrink backup posts library APP_NAME; do

```

If the cargo package name differs from directory name, add a case to `pkg_to_dir()`:

```bash

pkg_to_dir() {

  case "$1" in

    sipp-so) echo "sipp" ;;

    APP_PKG) echo "APP_NAME" ;;

    *) echo "$1" ;;

  esac

}

```

### 4. `.github/workflows/docker-test.yml`

Same two lists — keep in sync with `docker.yml`:

```yaml

ALL='["cellar","sipp","feeds","parcels","jotts","og","shrink","backup","posts","library","APP_NAME"]'

```

```yaml

for app in cellar sipp feeds parcels jotts og shrink backup posts library APP_NAME; do

```

### 5. Root `docker-compose.yml`

Production compose at repo root pulls images from GHCR. Add a service + volume:

```yaml

services:

  APP_NAME:

    image: ghcr.io/stevedylandev/andromeda/APP_NAME:latest

    restart: unless-stopped

    ports:

      - "PORT:3000"

    volumes:

      - APP_NAME_data:/data

    env_file: apps/APP_NAME/.env

volumes:

  APP_NAME_data:

    external: true

    name: APP_NAME_APP_NAME-data

```

Pick a unique host port (existing: 3000 sipp, 3030 jotts, 3456 og, 3535 posts, 3565 shrink, 4555 feeds, 4646 library, 6754 cellar). Drop `volumes`/`env_file` if app is stateless (see `shrink`, `og`).

If the app holds data worth backing up, add a read-only mount to the `backup` service:

```yaml

backup:

  volumes:

    - APP_NAME_data:/data/APP_NAME:ro

```

### 6. App-local `docker-compose.yml`

Per-app compose for local dev — builds from source:

```yaml

services:

  app:

    build:

      context: ../..

      dockerfile: apps/APP_NAME/Dockerfile

    ports:

      - "${PORT:-3000}:${PORT:-3000}"

    environment:

      - APP_PASSWORD=${APP_PASSWORD:-changeme}

      - APP_DB_PATH=/data/APP_NAME.sqlite

      - COOKIE_SECURE=false

      - HOST=0.0.0.0

      - PORT=${PORT:-3000}

    volumes:

      - APP_NAME-data:/data

    restart: unless-stopped

volumes:

  APP_NAME-data:

```

When scaffolding a new app:

1. Create `apps/APP_NAME/` with `cargo init`

2. Set up `apps/APP_NAME/Cargo.toml` with workspace deps + `andromeda-auth` (and `andromeda-db`, `andromeda-darkmatter-css` if used)

3. Register app in workspace root `Cargo.toml` under `[workspace] members`

4. Register app in `dist-workspace.toml` under `[workspace] members` (with `cargo:` prefix)

5. Add app to `ALL` array + `for app in ...` loop in `.github/workflows/docker.yml`

6. Add app to `ALL` array + `for app in ...` loop in `.github/workflows/docker-test.yml`

7. Write `db.rs` — schema, model, CRUD, session table if needed

8. Write `auth.rs` — wrap `andromeda-auth` with `AuthSession` extractor (if auth needed)

9. Write `server.rs` — config, state, templates, handlers, routes

10. Write `main.rs` — minimal entry point

11. Create `templates/` with `base.html` + index page

12. Create `static/styles.css`

13. Create `.env.example`

14. Create `Dockerfile` (cargo-chef multi-stage) + app-local `docker-compose.yml`

15. Add service entry + volume to root `docker-compose.yml` (and `backup` mount if stateful)

16. Test: `cargo run -p APP_NAME`, hit routes

17. Test: `docker build -f apps/APP_NAME/Dockerfile .` from repo root