Skip to main content

​
Podman

Run the FluffBuzz gateway in a rootless Podman container. Uses the same image as Docker (build from the repo Dockerfile).

​
Requirements

  • Podman (rootless)
  • Sudo for one-time setup (create user, build image)

​
Quick start

1. One-time setup (from repo root; creates user, builds image, installs launch script): 
./setup-podman.sh
This also creates a minimal ~fluffbuzz/.fluffbuzz/fluffbuzz.json (sets gateway.mode="local") so the gateway can start without running the wizard. By default the container is not installed as a systemd service, you start it manually (see below). For a production-style setup with auto-start and restarts, install it as a systemd Quadlet user service instead: 
./setup-podman.sh --quadlet
(Or set FLUFFBUZZ_PODMAN_QUADLET=1; use --container to install only the container and launch script.) 2. Start gateway (manual, for quick smoke testing): 
./scripts/run-fluffbuzz-podman.sh launch
3. Onboarding wizard (e.g. to add channels or providers): 
./scripts/run-fluffbuzz-podman.sh launch setup
Then open http://127.0.0.1:18789/ and use the token from ~fluffbuzz/.fluffbuzz/.env (or the value printed by setup).

​
Systemd (Quadlet, optional)

If you ran ./setup-podman.sh --quadlet (or FLUFFBUZZ_PODMAN_QUADLET=1), a Podman Quadlet unit is installed so the gateway runs as a systemd user service for the fluffbuzz user. The service is enabled and started at the end of setup.
  • Start: sudo systemctl --machine fluffbuzz@ --user start fluffbuzz.service
  • Stop: sudo systemctl --machine fluffbuzz@ --user stop fluffbuzz.service
  • Status: sudo systemctl --machine fluffbuzz@ --user status fluffbuzz.service
  • Logs: sudo journalctl --machine fluffbuzz@ --user -u fluffbuzz.service -f
The quadlet file lives at ~fluffbuzz/.config/containers/systemd/fluffbuzz.container. To change ports or env, edit that file (or the .env it sources), then sudo systemctl --machine fluffbuzz@ --user daemon-reload and restart the service. On boot, the service starts automatically if lingering is enabled for fluffbuzz (setup does this when loginctl is available). To add quadlet after an initial setup that did not use it, re-run: ./setup-podman.sh --quadlet.

​
The fluffbuzz user (non-login)

setup-podman.sh creates a dedicated system user fluffbuzz:
  • Shell: nologin — no interactive login; reduces attack surface.
  • Home: e.g. /home/fluffbuzz — holds ~/.fluffbuzz (config, workspace) and the launch script run-fluffbuzz-podman.sh.
  • Rootless Podman: The user must have a subuid and subgid range. Many distros assign these automatically when the user is created. If setup prints a warning, add lines to /etc/subuid and /etc/subgid: 
    fluffbuzz:100000:65536
    Then start the gateway as that user (e.g. from cron or systemd): 
    sudo -u fluffbuzz /home/fluffbuzz/run-fluffbuzz-podman.sh
sudo -u fluffbuzz /home/fluffbuzz/run-fluffbuzz-podman.sh setup
  • Config: Only fluffbuzz and root can access /home/fluffbuzz/.fluffbuzz. To edit config: use the Control UI once the gateway is running, or sudo -u fluffbuzz $EDITOR /home/fluffbuzz/.fluffbuzz/fluffbuzz.json.

​
Environment and config

  • Token: Stored in ~fluffbuzz/.fluffbuzz/.env as FLUFFBUZZ_GATEWAY_TOKEN. setup-podman.sh and run-fluffbuzz-podman.sh generate it if missing (uses openssl, python3, or od).
  • Optional: In that .env you can set provider keys (e.g. GROQ_API_KEY, OLLAMA_API_KEY) and other FluffBuzz env vars.
  • Host ports: By default the script maps 18789 (gateway) and 18790 (bridge). Override the host port mapping with FLUFFBUZZ_PODMAN_GATEWAY_HOST_PORT and FLUFFBUZZ_PODMAN_BRIDGE_HOST_PORT when launching.
  • Gateway bind: By default, run-fluffbuzz-podman.sh starts the gateway with --bind loopback for safe local access. To expose on LAN, set FLUFFBUZZ_GATEWAY_BIND=lan and configure gateway.controlUi.allowedOrigins (or explicitly enable host-header fallback) in fluffbuzz.json.
  • Paths: Host config and workspace default to ~fluffbuzz/.fluffbuzz and ~fluffbuzz/.fluffbuzz/workspace. Override the host paths used by the launch script with FLUFFBUZZ_CONFIG_DIR and FLUFFBUZZ_WORKSPACE_DIR.

​
Useful commands

  • Logs: With quadlet: sudo journalctl --machine fluffbuzz@ --user -u fluffbuzz.service -f. With script: sudo -u fluffbuzz podman logs -f fluffbuzz
  • Stop: With quadlet: sudo systemctl --machine fluffbuzz@ --user stop fluffbuzz.service. With script: sudo -u fluffbuzz podman stop fluffbuzz
  • Start again: With quadlet: sudo systemctl --machine fluffbuzz@ --user start fluffbuzz.service. With script: re-run the launch script or podman start fluffbuzz
  • Remove container: sudo -u fluffbuzz podman rm -f fluffbuzz — config and workspace on the host are kept

​
Troubleshooting

  • Permission denied (EACCES) on config or auth-profiles: The container defaults to --userns=keep-id and runs as the same uid/gid as the host user running the script. Ensure your host FLUFFBUZZ_CONFIG_DIR and FLUFFBUZZ_WORKSPACE_DIR are owned by that user.
  • Gateway start blocked (missing gateway.mode=local): Ensure ~fluffbuzz/.fluffbuzz/fluffbuzz.json exists and sets gateway.mode="local". setup-podman.sh creates this file if missing.
  • Rootless Podman fails for user fluffbuzz: Check /etc/subuid and /etc/subgid contain a line for fluffbuzz (e.g. fluffbuzz:100000:65536). Add it if missing and restart.
  • Container name in use: The launch script uses podman run --replace, so the existing container is replaced when you start again. To clean up manually: podman rm -f fluffbuzz.
  • Script not found when running as fluffbuzz: Ensure setup-podman.sh was run so that run-fluffbuzz-podman.sh is copied to fluffbuzz’s home (e.g. /home/fluffbuzz/run-fluffbuzz-podman.sh).
  • Quadlet service not found or fails to start: Run sudo systemctl --machine fluffbuzz@ --user daemon-reload after editing the .container file. Quadlet requires cgroups v2: podman info --format '{{.Host.CgroupsVersion}}' should show 2.

​
Optional: run as your own user

To run the gateway as your normal user (no dedicated fluffbuzz user): build the image, create ~/.fluffbuzz/.env with FLUFFBUZZ_GATEWAY_TOKEN, and run the container with --userns=keep-id and mounts to your ~/.fluffbuzz. The launch script is designed for the fluffbuzz-user flow; for a single-user setup you can instead run the podman run command from the script manually, pointing config and workspace to your home. Recommended for most users: use setup-podman.sh and run as the fluffbuzz user so config and process are isolated.