# 0.1 Quick Start

This guide gets the full @CKIR.IO/VISIONS stack running locally in minutes.

## Prerequisites

- [Docker & Docker Compose](https://docs.docker.com/compose/)
- NVIDIA Docker runtime (if using GPU)

## 1. Clone the repository
```bash
git clone https://github.com/ehildt/ckir.io-visions.git
cd ckir.io-visions
```

## 2. Prepare environment

Create a `.env` from the provided example and adjust if needed:
```bash
cp server/.env.example server/.env
```

The default configuration works out of the box for local Docker:
- `BULLMQ_HOST=keydb` — Redis-compatible KeyDB running inside the compose network
- `OLLAMA_HOST=http://ollama:11434` — Ollama reachable within the compose network
- `PORT=3000` — Exposed on your host

### Using cloud models instead of local Ollama

You can point the server to a cloud-hosted Ollama-compatible endpoint instead of running the local `ollama` container. Update `server/.env`:

```bash
# Example: Ollama.com cloud endpoint
OLLAMA_HOST=https://ollama.com
OLLAMA_API_KEY=your_api_key_here
```

If you use a cloud backend, you can optionally remove the `ollama` service from `compose.yml` to free resources—KeyDB and the server still handle queuing and streaming as normal. Just ensure your cloud provider supports vision models (e.g., `llama3.2-vision`) and that the API key has inference permissions.

## 3. Start the stack
```bash
docker compose up -d
```

This starts four services:
| Service | Description | Port |
|--------|-------------|------|
| `server` | NestJS API (REST, MCP, Socket.IO) | [http://localhost:3000](http://localhost:3000) |
| `dashboard` | Vue 3 dev server | [http://localhost:5173](http://localhost:5173) |
| `ollama` | Ollama inference server | [http://localhost:11434](http://localhost:11434) |
| `keydb` | Redis-compatible job store amp; pub/sub | `6379` |

### Pull a vision model
```bash
docker exec -it ollama ollama pull llama3.2-vision
```

## 4. Verify everything is running
- **Swagger / REST docs**: [http://localhost:3000/docs](http://localhost:3000/docs)
- **Health check**: [http://localhost:3000/api/v1/health/ready](http://localhost:3000/api/v1/health/ready)
- **Dashboard**: [http://localhost:5173](http://localhost:5173)
- **Socket.IO**: Shares port `3000` using WebSocket transport

## 5. Next steps
- Read the [Server Overview](1-server.md) for endpoint details.
- Explore the [Dashboard Overview](2-dashboard.md) for UI features.
- Review the [MCP tutorial](1.2-mcp.md) to connect Claude Desktop or other MCP clients.

## Troubleshooting
- **GPU not detected?** Ensure `nvidia-docker2` is installed and the `--gpus=all` flag in `compose.yml` is supported.
- **Port conflicts?** Change the left-side port mappings in `compose.yml` if `3000`, `5173`, `6379`, or `11434` are already in use.

---