kestrelos/docs/installation.md

Installation

You can run KestrelOS from source (npm), as a Docker container, or on Kubernetes with Helm.

Prerequisites

• Node.js 20+ (for npm install)
• Docker (optional, for container run)
• Kubernetes and Helm 3 (optional, for Helm install)

---

npm (from source)

Best for development or a single server.

1. Clone and install

   git clone <repository-url> kestrelos
   cd kestrelos
   npm install
   

2. Start the app

   npm run dev
   

   Open http://localhost:3000. The app will create a SQLite database at data/kestrelos.db on first run and bootstrap an admin user if none exist (see Authentication).

3. Production build

   npm run build
   npm run preview
   

   Or run the built app with Node:

   node .output/server/index.mjs
   

   For production, set HOST=0.0.0.0 and PORT as needed (e.g. PORT=3000).

Environment (npm)

Variable	Description
HOST	Bind address (default from Nuxt; use 0.0.0.0 for all interfaces).
PORT	Port (default 3000).
DB_PATH	Path to SQLite file (default data/kestrelos.db).

See Authentication for BOOTSTRAP_EMAIL, BOOTSTRAP_PASSWORD, and OIDC variables. See Map and cameras and ATAK and iTAK for device and CoT options.

---

Docker

Best for a single server or CI.

1. Build the image

   docker build -t kestrelos:latest .
   

2. Run the container

   docker run -p 3000:3000 -p 8089:8089 kestrelos:latest
   

   Open http://localhost:3000.

3. Persist data and set env

   docker run -p 3000:3000 -p 8089:8089 \
     -v kestrelos-data:/app/data \
     -e HOST=0.0.0.0 \
     -e BOOTSTRAP_EMAIL=admin@example.com \
     -e BOOTSTRAP_PASSWORD=yourpassword \
     kestrelos:latest
   

   Use a volume so the SQLite DB and any uploaded data survive restarts.

Docker environment

Same as npm; pass with -e. CoT (ATAK/iTAK) uses port 8089; expose both 3000 and 8089:

docker run -p 3000:3000 -p 8089:8089 -v kestrelos-data:/app/data kestrelos:latest

---

Helm (Kubernetes)

Best for production or multi-replica deployments.

From a Helm registry (e.g. Gitea)

helm repo add keligrubb --username YOUR_USER --password YOUR_TOKEN https://git.keligrubb.com/api/packages/keligrubb/helm
helm repo update
helm install kestrelos keligrubb/kestrelos

From source

helm install kestrelos ./helm/kestrelos

Configuration

• Edit helm/kestrelos/values.yaml for image, replica count, resources, and Ingress.
• Health endpoints: GET /health (overview), GET /health/live (liveness), GET /health/ready (readiness). The chart configures liveness and readiness probes.
• To expose the app, set ingress.enabled: true and set ingress.host (and TLS if needed).
• For ATAK/iTAK, expose port 8089 (CoT) in addition to 3000 (web/API) on the service or via Ingress.

Upgrade

helm upgrade kestrelos keligrubb/kestrelos
# or
helm upgrade kestrelos ./helm/kestrelos

---

Next steps

• Authentication — First login (local or OIDC).
• Map and cameras — Add devices and use the map.
• ATAK and iTAK — Connect TAK clients.
• Share live — Stream from your phone.