# NewsAtlas — Proxmox LXC deployment

Builds a Proxmox LXC container running the full NewsAtlas stack (Docker +
docker-compose inside the CT), and packages it as a reusable `.tar.zst`
template. Supports Debian, Ubuntu, and Alpine base images.

> **Not executed against a real Proxmox host while writing this** — there
> wasn't one available in that environment. The docker-compose stack itself
> (`../../docker-compose.yml`) *has* been built and run end-to-end; this LXC
> layer just automates `pct`/`pveam`/`vzdump` calls around it. Run
> `./build.sh <target> --dry-run` first and read the printed commands before
> running for real.

## Security model — read before using

`build.sh` writes real secrets (whatever you put in `prebuild-config.json`)
into `/opt/newsatlas/.env` **inside the container's filesystem**, and that
filesystem gets packaged into the `.tar.zst` template. This was a deliberate
choice — the safer default (inject secrets only into the running container,
never into a distributable template) was offered and explicitly declined in
favor of "clone-and-go" templates that boot with everything already
configured.

The trade-off that comes with that: **every copy of the resulting
`.tar.zst` is a credentials-bearing artifact**, for every distro variant you
build. Concretely:

- Keep template files (`local:vztmpl/...` / your `vzdump` dump directory)
  on storage only trusted operators can read — never a public/shared LXC
  template store. The whole point of a reusable template is that it gets
  cloned, and each clone carries the same baked-in credentials.
- If a copy of the tarball is ever backed up somewhere less trusted, copied
  off-host, or shared, **rotate every key in `prebuild-config.json`**
  (OpenWeatherMap, ACLED, OpenSky) — there's no way to invalidate just the
  copy that leaked.
- `prebuild-config.json` itself is gitignored; don't commit it, don't paste
  it into issues/chat.

If you'd rather not carry that risk, don't use this path — run
`docker compose up --build` directly on any host (see the root README) and
manage `.env` there normally; nothing gets baked into a shareable artifact.

## Setup

```bash
cp prebuild-config.json.template prebuild-config.json
$EDITOR prebuild-config.json   # fill in secrets, LXC sizing, network, etc.
```

Key fields:

- `app.repo_url` / `app.branch` — where `provision.sh` clones the app from
  inside the container. Defaults to this repo's own remote.
- `secrets.*` — same keys as the root `.env.example`, baked in as described
  above.
- `lxc.*` — sizing (`cores`, `memory_mb`, `disk_gb`), Proxmox storage IDs
  (`storage` for the rootfs, `template_storage` for both the base template
  and the packaged output), networking (`bridge`, `vlan`, `ip`, `gateway`),
  and either `root_password` or `ssh_public_key_file` for access.
- `distros.*` — the `pveam available` template-name prefix used to resolve
  the newest matching template for each distro. Check `pveam available`
  on your host if these drift.

## Building

Run as root on the Proxmox VE host:

```bash
./build.sh debian            # one distro
./build.sh all                # debian + ubuntu + alpine
./build.sh ubuntu --dry-run   # print the pct/pveam/vzdump commands, run nothing
./build.sh alpine --no-keep   # destroy the scratch CT after packaging (template file only)
./build.sh debian --no-template  # deploy and leave the CT running; skip packaging
```

Each run: allocates the next free CTID, creates the CT with `nesting=1`
(required to run Docker inside an LXC), installs Docker via `provision.sh`,
clones the app, pushes the generated `.env`, runs `docker compose up
--build`, waits for `/api/health`, then (unless `--no-template`) stops the
CT and runs `vzdump --mode stop --compress zstd` to produce the template,
restarting the CT afterward (unless `--no-keep`).

## Redeploying from a packaged template

```bash
pct restore <newid> <template_storage>:backup/vzdump-lxc-<ctid>-*.tar.zst --storage <storage>
pct start <newid>
```

The container comes up with the app already running and `.env` already in
place — no further provisioning needed (that's the whole point, and also
exactly why the security note above matters).