Skip to content

Instance manager

Jump to bottom
Logan Rickert edited this page Jul 21, 2026 · 2 revisions

Instance manager

The instance manager is a web UI to list and deploy multiple HarborFM instances. It supports Terraform (AWS or Vultr) and Kubernetes (Helm). Helm support exists in the UI and runners but is still a work in progress. Terraform and Helm configs live in infrastructure/terraform and infrastructure/helm.

When to use it: Use the instance manager when you want to manage several HarborFM instances from one place instead of running Terraform or Helm manually from the command line.

For full environment variable reference and advanced options, see the main README ("Instance manager (beta)") and infrastructure/instance-manager/README.md.

Run alongside HarborFM dev

From the monorepo root:

pnpm run dev          # Terminal 1: main HarborFM server + web
pnpm run dev:manager  # Terminal 2: Instance Manager

Open http://localhost:3998 (Vite dev server; it proxies /api to the manager on port 3999).

Environment variables

Copy .env.example to .env in infrastructure/instance-manager and set as needed. Summary:

Variable Purpose
PORT API server port (default 3999).
INFRASTRUCTURE_ROOT Repo root path if you run from a different cwd.
KUBECONFIG Path to kubeconfig for Helm/Kubernetes (optional).
VULTR_API_KEY Required for Terraform Vultr deploys.
AWS_ACCESS_KEY_ID / AWS_SECRET_ACCESS_KEY Required for Terraform AWS deploys.
MANAGER_SECRET Optional; when set, config.json and data.json are stored encrypted at rest. If unset, run-docker.sh can generate one.
FLAREVAULT_URL / FLAREVAULT_ADMIN_TOKEN Optional; for FlareVault-backed admin credentials on deploy (single-use secret delivery).
DEFAULT_SSH_PUBLIC_KEY Optional; default SSH public key for deploy form.

Full list and details: infrastructure/instance-manager/README.md and .env.example.

Features

  • Instances – List Terraform workspaces (AWS + Vultr) and Helm releases. Filter by orchestrator and provider. Shows URL, IP, setup link where available.
  • Deploy – Terraform or Kubernetes; for Terraform choose AWS or Vultr. Form covers name, domain, deploy type, WebRTC, admin/certbot, region/plan. Submit streams live terraform / helm output and shows success or error when done.
  • Settings – Defaults for deploy form and optional SSH key.

Production build

From infrastructure/instance-manager:

pnpm run build   # Vite build + tsc
pnpm run start   # Node server; serves API and static UI on PORT

Open http://localhost:3999 (or your PORT).

Docker

The image includes the instance-manager app and Terraform (AWS + Vultr).

Image from GitHub Container Registry

Images are built on push to main (tag latest) and staging (tag staging).

# Create .env from .env.example and set VULTR_API_KEY (and/or AWS creds), etc.
docker run --rm -it --init \
  --env-file .env \
  -p 3997:3999 \
  -v "$(pwd)/tfstate:/data" \
  -v "$(pwd)/config.json:/app/manager/config.json" \
  -v "$(pwd)/data.json:/app/manager/data.json" \
  ghcr.io/loganrickert/harborfm-instance-manager:latest

Open http://localhost:3997. Config, instance data, and Terraform state persist via the bind mounts.

Build and run locally

Build (from repo root):

./infrastructure/instance-manager/build-docker.sh

Or: docker build -f infrastructure/instance-manager/Dockerfile -t instance-manager .

Run (from infrastructure/instance-manager):

cd infrastructure/instance-manager
./run-docker.sh
  • Requires a .env file (copy from .env.example). If MANAGER_SECRET is not set, the script generates one and appends it to .env.
  • Volumes: ./tfstate > /data (Terraform state); ./config.json and ./data.json > container (created as {} if missing). Config and instance data persist in the current directory.
  • Port: Container 3999 is published as 3997 so it doesn't clash with a local manager. Open http://localhost:3997.
  • Credentials: Set VULTR_API_KEY (and for AWS: AWS_ACCESS_KEY_ID, AWS_SECRET_ACCESS_KEY) in .env so deploys work. The API reports clearly if they're missing.
  • Ctrl+C stops the container (--init forwards signals).

See also

Clone this wiki locally