Skip to main content

Install (self-hosted)

This page gets a local Community deployment running so you can bootstrap keys and verify integration.

Prerequisites​

  • Docker Desktop (or equivalent Docker Engine) with Docker Compose v2.
  • Node.js and pnpm (for running the dev workflow and CLI tooling).
  • openssl (for generating a stable master key).

Step 1: set a stable master key (required)​

Self-hosted Service Keys are derived from BILLING_MASTER_KEY. Treat it like a secret and keep it stable for the life of your deployment.

Generate a value:

openssl rand -hex 32

Export it:

export BILLING_MASTER_KEY='replace-me-with-generated'

Pull the community image from GitHub Container Registry:

docker pull ghcr.io/lapbay/vluna-community:latest

Run the container:

docker run -d --name vluna-community \
  -p 3002:3002 \
  --add-host host.docker.internal:host-gateway \
  -e DATABASE_URI="postgresql://postgres:@host.docker.internal:5432/vluna" \
  -e DATABASE_MIGRATOR_URI="postgres://postgres:@host.docker.internal:5432/vluna" \
  --env-file apps/app-community/.env.production \
  -e BILLING_MASTER_KEY="${BILLING_MASTER_KEY}" \
  --rm \
  ghcr.io/lapbay/vluna-community:latest

This uses host.docker.internal for DB connections from the container to your local PostgreSQL. If your Docker runtime does not support host-gateway, replace this with an addressable DB host (for example an explicit IP or DNS name) and remove this flag.

Step 3: install with docker compose (alternative)​

If you prefer local orchestration, run from the repository root:

docker compose -f infra/docker/docker-compose.yml --profile db --profile api up -d

This follows the same install flow documented in README.md.

Step 4: (optional) run the dev workflow (hot reload)​

If you want source-based development:

pnpm i
pnpm community:setup
pnpm community:dev

Verify​

You are ready to proceed if:

  • curl -fsS http://localhost:3002/health returns success.

Next, provision a realm and a service key:

Troubleshoot​

  • Port conflicts: ensure 3002 (API) and your Postgres port are free.
  • Missing BILLING_MASTER_KEY: the system will fail early. Export it before starting containers or dev commands.
  • Docker state: if you need to reset local data, stop and remove volumes:
docker compose -f infra/docker/docker-compose.yml down -v

Next steps​