# 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**
   ```bash
   git clone <repository-url> kestrelos
   cd kestrelos
   npm install
   ```

2. **Start the app**
   ```bash
   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](auth.md)).

3. **Production build**
   ```bash
   npm run build
   npm run preview
   ```
   Or run the built app with Node:
   ```bash
   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](auth.md) for `BOOTSTRAP_EMAIL`, `BOOTSTRAP_PASSWORD`, and OIDC variables. See [Map and cameras](map-and-cameras.md) and [ATAK and iTAK](atak-itak.md) for device and CoT options.

---

## Docker

Best for a single server or CI.

1. **Build the image**
   ```bash
   docker build -t kestrelos:latest .
   ```

2. **Run the container**
   ```bash
   docker run -p 3000:3000 -p 8089:8089 kestrelos:latest
   ```
   Open **http://localhost:3000**.

3. **Persist data and set env**
   ```bash
   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:
```bash
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)

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

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

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

---

## Next steps

- [Authentication](auth.md) — First login (local or OIDC).
- [Map and cameras](map-and-cameras.md) — Add devices and use the map.
- [ATAK and iTAK](atak-itak.md) — Connect TAK clients.
- [Share live](live-streaming.md) — Stream from your phone.