# Lattice Edge — Setup Guide

A simple guide to running the Lattice Edge container and connecting to a remote Ray cluster.

#### Prerequisites

* [Docker](https://docs.docker.com/get-docker/) installed on your machine
* Basic familiarity with the command line
* A Ray auth token (provided by your cluster administrator)

#### Quick Start

**1. Pull the Edge image**

```bash
docker pull latticelab/edge:latest
```

**2. Run the container**

```bash
docker run -d \
  --name lattice-edge \
  -p 8889:8888 \
  -e RAY_AUTH_MODE=token \
  -e RAY_AUTH_TOKEN=your-token-here \
  latticelab/edge:latest
```

Replace `your-token-here` with the Ray auth token provided by your cluster administrator.

**3. Access JupyterLab**

Once the container starts, open your browser and navigate to:

**URL:** <http://localhost:8889>

**4. Connect to the Ray cluster**

In a notebook cell, connect to the remote cluster:

```python
import os
os.environ["RAY_AUTH_MODE"] = "token"
os.environ["RAY_AUTH_TOKEN"] = "your-token-here"

import ray
ray.init("ray://l40.latticelab.ai:9443", namespace="lattice-detection")
print(ray.cluster_resources())
```

The auth env vars must be set **before** `import ray`.

#### Managing the Container

**Stopping the container**

```bash
docker stop lattice-edge
```

**Starting a stopped container**

```bash
docker start lattice-edge
```

**Removing the container**

```bash
docker rm lattice-edge
```

#### Troubleshooting

**Port already in use**

If port 8889 is busy, map to a different local port:

```bash
docker run -d \
  --name lattice-edge \
  -p 9999:8888 \
  -e RAY_AUTH_MODE=token \
  -e RAY_AUTH_TOKEN=your-token-here \
  latticelab/edge:latest
```

Then access via `http://localhost:9999`

**Ray connection timeout**

* Verify the gateway is reachable: `nc -zv l40.latticelab.ai 9443 -w 5`
* Check that you're using port **9443** (not 8443 or 10001)
* Make sure `RAY_AUTH_MODE` and `RAY_AUTH_TOKEN` are set before `import ray`
* If you already imported Ray without the env vars, restart the notebook kernel

**Container won't start**

Check if a container with the same name exists:

```bash
docker ps -a | grep lattice-edge
```

Remove it if needed:

```bash
docker rm lattice-edge
```

**Permission denied on mounted volume**

On Linux, you may need to set the correct user ID:

```bash
docker run -d \
  --name lattice-edge \
  -p 8889:8888 \
  -e RAY_AUTH_MODE=token \
  -e RAY_AUTH_TOKEN=your-token-here \
  -e NB_UID=$(id -u) \
  -e NB_GID=$(id -g) \
  -v ~/notebooks:/home/latlab/work/notebooks \
  latticelab/edge:latest
```

#### License

This documentation is released under the [MIT License](https://opensource.org/licenses/MIT). Feel free to use, modify, and distribute.

#### Contributing

Contributions welcome! Feel free to open an issue or submit a pull request.


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://lattice-1.gitbook.io/lattice-docs/documentation/readme/lattice-edge-setup-guide.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.