NewsAtlas/deploy/lxc

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

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:

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

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