# A.R.K.A. local installation / lokalus diegimas

This guide installs the standalone application from the `ARKA/arka` directory.
Ši instrukcija skirta atskirai programai, esančiai `ARKA/arka` kataloge.

## 1. Requirements / reikalavimai

- Linux, macOS or Windows with WSL2;
- Node.js 22.22 or newer LTS, or Docker 24+;
- 2 GB RAM minimum; 8 GB recommended for a local language model;
- 2 GB free space for the application; additional space for ZIM and map content;
- a trusted local network if access from another device is required.

Check the tools:

```bash
node --version
npm --version
```

## 2. Native Node.js installation / diegimas be Docker

From the project directory:

```bash
cd ARKA/arka
npm ci
npm run build
npm start
```

Open <http://127.0.0.1:8080>. The production server exposes both the API and the
compiled web interface on the same port. Stop it with `Ctrl+C`.

### Development mode / kūrimo režimas

```bash
cd ARKA/arka
npm ci
npm run dev
```

- UI: <http://127.0.0.1:5173>
- API: <http://127.0.0.1:8080>
- health check: <http://127.0.0.1:8080/api/health>

Vite forwards `/api` requests to the backend automatically.

## 3. Docker installation

### Core node without a language model

```bash
cd ARKA/arka
docker compose -f docker/docker-compose.yml up -d --build arka
docker compose -f docker/docker-compose.yml ps
```

Open <http://127.0.0.1:8080>.

### Optional local AI with Ollama

```bash
cd ARKA/arka
docker compose -f docker/docker-compose.yml --profile ai up -d --build
docker exec arka_ollama ollama pull llama3.2
```

The initial model download can be several gigabytes. Until a model is available,
the assistant uses the built-in fallback knowledge search.

### Trusted LAN access

The Docker configuration binds to `127.0.0.1` by default. To allow other devices
on a trusted LAN, set a deliberate bind address:

```bash
ARKA_BIND_IP=0.0.0.0 docker compose -f docker/docker-compose.yml up -d --build arka
```

Then open `http://DEVICE_IP:8080`. Use a host firewall to restrict access to the
trusted subnet. Never forward port 8080 from the public internet.

## 4. Configuration

| Variable | Default | Purpose |
|---|---|---|
| `PORT` | `8080` | HTTP port inside the process/container |
| `HOST` | `127.0.0.1` | Native process listening address; Docker overrides it internally |
| `ARKA_STORAGE_PATH` | `storage/` | Downloaded content and indexes |
| `ARKA_AI_BASE_URL` | `http://localhost:11434/v1` | OpenAI-compatible local model endpoint |
| `ARKA_AI_MODEL` | `llama3.2` | Local model name |
| `ARKA_AI_TIMEOUT_MS` | `30000` | AI request timeout |
| `ARKA_ZIM_MAX_DOCS` | `1000000` | Maximum documents in a ZIM full-text index |
| `NODE_OPTIONS` | Docker: 4096 MB heap | Memory limit for large ZIM indexing |

## 5. Acceptance checks / veikimo patikra

```bash
curl -fsS http://127.0.0.1:8080/api/health
curl -fsS http://127.0.0.1:8080/api/system/status
curl -fsS 'http://127.0.0.1:8080/api/knowledge?q=water'
curl -fsS http://127.0.0.1:8080/api/catalog
```

In the browser confirm:

1. Command Center shows live memory, storage and uptime values.
2. LT/EN changes every visible navigation label.
3. Knowledge search returns a result for `vanduo` or `water`.
4. AI Assistant returns a fallback answer when Ollama is not running.
5. Downloads show catalog items and actionable status.
6. Mobile navigation opens and closes without horizontal overflow.

## 6. Data and backup

Native installation stores runtime data in `storage/`. Docker stores it in the
`arka-storage` volume. Back up this data before upgrading. Full-text ZIM indexes
are stored next to their source archives and can be rebuilt if needed.

Stop Docker while retaining data:

```bash
docker compose -f docker/docker-compose.yml down
```

Do not use `down -v` unless you intentionally want to delete downloaded content,
indexes and local model data.

## 7. Security boundaries

- A.R.K.A. has no built-in user authentication in this version.
- Keep it on localhost or a segmented, trusted LAN.
- Do not expose port 8080 to the public internet.
- Review custom download URLs before adding them; the node will fetch them directly.
- Medical and emergency content is guidance, not a replacement for professional help.

## 8. License

A.R.K.A. uses **Apache License 2.0** and does not use QGPL. See `LICENSE` and
`NOTICE` for the exact terms and concept-reference attribution.
