# A.R.K.A. v0.2.0 local installation

A.R.K.A. is a standalone local-first application. Keep it on localhost or a
segmented, trusted LAN: this version has no built-in user authentication.

## Requirements

- Linux, macOS or Windows with WSL2;
- Node.js 22.22 or newer, or Docker 24+;
- 2 GB RAM minimum; 8 GB recommended for a local language model;
- 2 GB free space plus room for downloaded ZIM and PMTiles content.

## Option A — Node.js

Download `arka-0.2.0.zip` from the A.R.K.A. page, then run:

```bash
unzip arka-0.2.0.zip -d arka-0.2.0
cd arka-0.2.0
npm ci
npm run build
npm start
```

Open <http://127.0.0.1:8080>. Stop the server with `Ctrl+C`.

Development mode:

```bash
npm run dev
```

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

## Option B — Docker

Core node without a language model:

```bash
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
docker compose -f docker/docker-compose.yml --profile ai up -d --build
docker exec arka_ollama ollama pull llama3.2
```

Until a model is installed, the assistant uses its built-in offline knowledge
fallback.

## Trusted LAN access

The native server and Docker port bind to localhost by default. To allow another
device on a trusted LAN with Docker:

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

Open `http://DEVICE_IP:8080` and restrict access with a host firewall. Never
forward port 8080 from the public internet and do not create public DNS for the
node.

## Configuration

| Variable | Default | Purpose |
|---|---|---|
| `PORT` | `8080` | HTTP port |
| `HOST` | `127.0.0.1` | Native listening address |
| `ARKA_STORAGE_PATH` | `storage/` | Content and indexes |
| `ARKA_AI_BASE_URL` | `http://localhost:11434/v1` | Local OpenAI-compatible endpoint |
| `ARKA_AI_MODEL` | `llama3.2` | Local model name |
| `ARKA_ZIM_MAX_DOCS` | `1000000` | Maximum ZIM documents to index |

## Acceptance check

```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 that:

1. Command Center shows live memory, storage and uptime.
2. EN/LT changes all visible navigation and page labels.
3. Knowledge search returns a result for `water`.
4. AI Assistant returns a fallback answer without Ollama.
5. Downloaded PMTiles regions open locally.
6. Mobile navigation opens without horizontal overflow.

## Data and backup

Native mode stores runtime data in `storage/`. Docker uses the `arka-storage`
volume. Back it up before upgrades. Stop Docker while retaining data with:

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

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