Deployment

Deployment is a first-class self-hosted path.

Packaged Lab Image

The current packaged lab image is:

docker run --name pagemaster \
  -p 8090:8090 \
  -v pagemaster-data:/var/lib/pagemaster \
  -v /path/to/media:/media \
  repository.spitzerhome.com/david/pagemaster:0.2.8

Local builds use:

make docker-build
# produces pagemaster:$(cat VERSION)

Image tag policy:

• Version tags, such as 0.2.8, are immutable release artifacts.
• The lab tag may become the moving verified lab channel when the operator wants one.
• The latest tag is reserved for a later stable/public release policy and should not be assumed for fast-moving lab builds.

Open:

http://<docker-host>:8090

First visit shows the setup screen. Create the first operator account in the app. No application .env file is required for normal lab setup.

Runtime basics:

• PORT=8090
• DATA_DIR=/var/lib/pagemaster
• Persistent volume: /var/lib/pagemaster
• Optional media bind mount: /media

The image includes Calibre so ebook conversion tooling is available inside the app image. That keeps lab setup simple, but it also makes the image large.

Docker Healthcheck

The image includes a Docker healthcheck backed by the app binary:

/usr/local/bin/pagemaster healthcheck

It checks http://127.0.0.1:${PORT}/api/health inside the container and requires ok: true. Operators can run it manually with:

docker exec pagemaster /usr/local/bin/pagemaster healthcheck

Use PAGEMASTER_HEALTHCHECK_URL only when the default loopback URL cannot represent the container health endpoint.

Targets

• Docker.
• Proxmox LXC for prototype testing.
• Local filesystem roots and bind-mounted paths.
• Future network storage connectors where feasible.

Proxmox LXC Testing Helper

The repo includes a host-side helper script:

scripts/proxmox/install-pagemaster-lxc.sh

The script is intended to be run from the Proxmox host shell as root. It can update an existing Pagemaster LXC, fully reset an existing LXC after backing up app data, or fresh-install a new LXC.

Current behavior:

• Always creates a privileged Debian container, preferring Debian 13 with Debian 12 fallback.
• Offers static IP or DHCP networking.
• Installs Go, pulls Pagemaster from Forgejo, builds the Go prototype, installs pagemaster.service, and starts the app.
• Runs the service as root in the LXC so Proxmox host bind mounts work cleanly during prototype testing.
• Configures direct root auto-login for the Proxmox LXC console, matching the other lab helper scripts.
• Can configure read-write bind mounts for source/test files, managed output, and completed downloads.
• Can add the CT to Proxmox HA when ha-manager is available.
• Runs in-container and host-to-container health checks after install or update.

Quick command:

apt-get update
apt-get install -y git ca-certificates

tmp_dir="$(mktemp -d)"
git clone --depth 1 \
  https://repository.spitzerhome.com/david/library-manager.git \
  "$tmp_dir/library-manager"
bash "$tmp_dir/library-manager/scripts/proxmox/install-pagemaster-lxc.sh"

The repo is public for Git clone access. This Forgejo instance may still send unauthenticated web/raw file URLs to the login page, so use git clone for the host install path. The installer will install whiptail when needed so the interactive setup uses menu dialogs.

The installer prints a log path like /tmp/pagemaster-lxc-install-YYYYMMDD-HHMMSS.log. If setup stops or the UI disappears, inspect the newest log:

ls -t /tmp/pagemaster-lxc-install-*.log | head -n 1
tail -n 120 "$(ls -t /tmp/pagemaster-lxc-install-*.log | head -n 1)"

For a noisier diagnostic run:

TRACE=1 bash "$tmp_dir/library-manager/scripts/proxmox/install-pagemaster-lxc.sh"

For a private Forgejo repo later, use a read-only Forgejo token:

read -rsp "Forgejo token: " FORGEJO_TOKEN
echo
tmp_script="$(mktemp)"
curl -fsSL \
  -u "david:${FORGEJO_TOKEN}" \
  -o "$tmp_script" \
  https://repository.spitzerhome.com/david/library-manager/raw/branch/main/scripts/proxmox/install-pagemaster-lxc.sh
if head -n 1 "$tmp_script" | grep -q '^#!/usr/bin/env bash'; then
  FORGEJO_USERNAME=david FORGEJO_TOKEN="$FORGEJO_TOKEN" bash "$tmp_script"
else
  echo "Download did not return the installer script. Check Forgejo visibility, auth, or URL."
  head -n 5 "$tmp_script"
fi

If the shell reports syntax error near unexpected token newline and shows <!DOCTYPE html>, Forgejo returned a login/error HTML page instead of the script. Use the private-repo token command or make the raw script readable from the Proxmox host.

The installer asks which operation to run:

1. Update an existing Pagemaster LXC
2. Full reset and install
3. Fresh install into a new CTID

Updates preserve the container, app config, database, and bind mounts. Reset backs up /var/lib/pagemaster and /etc/pagemaster to /var/backups/pagemaster-lxc, removes any HA resource, destroys the CT after confirmation, then installs fresh. Fresh install suggests Proxmox's next available CTID.

Useful environment overrides:

• CTID
• CT_HOSTNAME
• ROOTFS_STORAGE
• TEMPLATE_STORAGE
• BRIDGE
• NETWORK_MODE
• STATIC_IP
• GATEWAY
• DNS_SERVER
• DISK_GB
• MEMORY_MB
• SWAP_MB
• CORES
• PORT
• REPO_URL
• CONFIGURE_MOUNTS
• SOURCE_HOST_PATH
• MANAGED_HOST_PATH
• DOWNLOADS_HOST_PATH
• ADD_TO_HA
• HA_GROUP

The default app URL is:

http://<container-ip>:8090

For shell access, use the Proxmox console or:

pct enter <CTID>

If an older Pagemaster CT still asks for Linux login credentials in the Proxmox console, rerun the helper and choose update for that CTID. The update path reapplies the direct root console configuration.

Default bind-mount paths inside the CT:

/mnt/pm-source
/mnt/pm-managed
/mnt/pm-downloads

This is still a prototype deployment path. Treat source files as valuable data and keep testing focused on deliberate test roots until non-fixture scanning and apply behavior are explicit in the UI. Real provider credentials should start as throwaway credentials.

Release Packaging

Every packaged release should have:

• An explicit version number.
• A Git tag.
• Release notes with operator-facing changes.
• A matching Docker image.
• Wiki install/upgrade notes when deployment behavior changes.

Current release slice:

• Version: 0.2.8
• Docker tag: repository.spitzerhome.com/david/pagemaster:0.2.8
• Release notes: v0.2.8 Docker Healthcheck
• Smoke-tested endpoints: /api/health, /api/setup/status, and Docker health status.

Operational Expectations

• SQLite and app data live in a clear persistent data directory.
• Library source paths remain server-side.
• Secrets are kept outside the repository.
• Backup and restore guidance covers database, config, metadata cache, and generated sidecars where applicable.
• The current LXC testing path always uses a privileged container because Proxmox node storage bind mounts are the goal. Treat that CT as trusted infrastructure behind normal cluster and network protections. Revisit least-privilege service users and container mode for packaged Docker releases, not for this Proxmox LXC path.