93 lines
4.1 KiB
Markdown
93 lines
4.1 KiB
Markdown
# 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).
|