# 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](../blob/main/README.md) ("Instance manager (beta)") and [infrastructure/instance-manager/README.md](../blob/main/infrastructure/instance-manager/README.md).

## Run alongside HarborFM dev

From the monorepo root:

```bash
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](../blob/main/infrastructure/instance-manager/README.md) and [.env.example](../blob/main/infrastructure/instance-manager/.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`:

```bash
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`).

```bash
# 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):

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

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

**Run** (from `infrastructure/instance-manager`):

```bash
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

- [Deployment](Deployment.md) – Docker, Compose, Terraform, and HarborFM environment variables.
- [infrastructure/terraform/README.md](../blob/main/infrastructure/terraform/README.md) – Terraform variables and options.
- [infrastructure/instance-manager/README.md](../blob/main/infrastructure/instance-manager/README.md) – Full instance-manager setup and layout.
- Main [README](../blob/main/README.md) – Instance manager (beta) and FlareVault (optional credential delivery to new instances).