Frontend Compose quickstart¶
This quickstart runs Hubuum Frontend and Valkey. It does not install Hubuum Server or PostgreSQL; point it at an existing Hubuum Server instance.
Requirements¶
- Docker Compose 2.20 or newer, or a compatible Podman Compose installation.
- A Hubuum Server URL reachable from inside the frontend container.
Start¶
Copy the example environment and set BACKEND_BASE_URL:
cp .env.quickstart.example .env.quickstart
docker compose --env-file .env.quickstart -f compose.quickstart.yml up -d
Open http://localhost:3000. Check dependency readiness with:
The quickstart mounts ./login-backgrounds read-only into the frontend. Put
private AVIF, JPEG, PNG, or WebP files there before starting Compose. To keep
the artwork elsewhere, set LOGIN_BACKGROUNDS_HOST_DIR in .env.quickstart to
that host directory. The images remain outside the container image and source
repository.
For Docker Desktop, a server running directly on the host is normally
reachable as http://host.docker.internal:8080. On Linux Docker Engine, add
extra_hosts: ["host.docker.internal:host-gateway"] to the frontend service or
use a routable host address. Podman commonly exposes the host as
host.containers.internal.
Manage the quickstart¶
docker compose --env-file .env.quickstart -f compose.quickstart.yml logs -f frontend
docker compose --env-file .env.quickstart -f compose.quickstart.yml pull
docker compose --env-file .env.quickstart -f compose.quickstart.yml up -d
docker compose --env-file .env.quickstart -f compose.quickstart.yml down
Use down -v only when you also want to remove the Valkey data volume and sign
out all stored sessions.
This quickstart binds the frontend to loopback and does not configure TLS. Use the Helm chart or the Hubuum Server single-host installer for production.
For Helm deployments, store the private images on a read-only PVC and set
loginBackgrounds.existingClaim to its name. The chart mounts that claim at
/app/login-backgrounds without copying the images into the application image.