> ## Documentation Index
> Fetch the complete documentation index at: https://docs-v1.latitude.so/llms.txt
> Use this file to discover all available pages before exploring further.

# Development Setup

> Set up a local Latitude instance using Docker for development and testing.

# Development Setup

This guide explains how to set up a local instance of Latitude on your machine for development, testing, or contributing to the project. We primarily use Docker Compose to manage the necessary services.

<Note>
  Due to potential performance limitations with Next.js in Docker volume mounts
  on some systems, parts of the development setup might involve running services
  directly on the host. This guide focuses on the Docker Compose approach.
</Note>

## Prerequisites

* **Git**: To clone the repository.
* **Docker & Docker Compose**: Ensure Docker Desktop or equivalent is installed and running.
* **Node.js & pnpm**: Required for building packages and potentially running some services locally. Install [pnpm](https://pnpm.io/installation).
* **Tmux & Tmuxinator (Optional but Recommended)**: Useful for managing multiple services in the terminal. Install [Tmuxinator](https://github.com/tmuxinator/tmuxinator) (e.g., `brew install tmuxinator` on macOS).

## Setup Steps

1. **Clone the Repository**:

   ```bash theme={null}
   git clone https://github.com/latitude-dev/latitude-llm.git
   cd latitude-llm
   ```

2. **Install Dependencies**:

   ```bash theme={null}
   pnpm install
   ```

3. **Build Shared Packages**:
   Build the core packages that other services depend on.

   ```bash theme={null}
   pnpm build --filter='./packages/**'
   ```

4. **Configure Environment (if needed)**:

   * Copy any example environment files (e.g., `.env.example` to `.env`) and adjust necessary variables. For a standard local setup, defaults are often sufficient.

5. **Start Services with Docker Compose**:
   This command starts the database, message queue, and other background services defined in `docker-compose.yml`.

```bash theme={null}
docker compose up -d
```

<Info>
  The Docker Compose setup pulls pre-built images from GitHub Container Registry (ghcr.io/latitude-dev).
  To build local images after making code changes, add the `--build` flag (e.g., `docker compose up -d --build`).
</Info>

*Alternatively, if using Tmuxinator (recommended)*:

```bash theme={null}
tmuxinator start
```

This will typically start Docker Compose in one pane and potentially other services (like the web app) in other panes according to the `.tmuxinator.yml` config.

6. **Run Database Migrations**:
   Once the database container is running (check `docker compose ps` or the tmuxinator output), apply the necessary database schema migrations.

   ```bash theme={null}
   cd packages/core
   pnpm db:migrate
   cd ../..
   ```

7. **Run the Web Application (if not using Tmuxinator)**:
   If you didn't use tmuxinator, you might need to start the Next.js web application manually:
   ```bash theme={null}
   pnpm dev --filter web
   ```

## Accessing Local Latitude

* **Web UI**: Open your browser to `http://localhost:3000` (or the configured port).
* **Sign Up**: Create your first user account using any email address.
* **Email Confirmation**: Access the local MailHog instance (usually at `http://localhost:8025`) to find the confirmation email and complete the signup.
* **API**: The local API will be available (check `docker-compose.yml` or app configuration for the port, often proxied through the web UI).

## Configuration

* **Docker Compose**: Modify `docker-compose.yml` to adjust service configurations, ports, or volumes.
* **Environment Variables**: Core settings (database URLs, API keys for testing, etc.) are typically managed via `.env` files within the respective app/package directories.
* **Application Config**: Check specific application directories (e.g., `apps/web/config`) for further configuration options.

## Stopping the Environment

* **Docker Compose**: `docker compose down`
* **Tmuxinator**: Stop the session (e.g., `tmux kill-session -t latitude-llm`) or stop individual services in their panes.

Now you have a local Latitude instance running for development!

## Using the REPL

You can run a JavaScript REPL to interact with the local instance of Latitude.
From the root of the repository, start the REPL with `pnpm console`. Try:

```javascript theme={null}
await database.select().from(users).limit(10)
```

## Next Steps

* Learn about deploying to [Production](/guides/self-hosted/production-setup)
* Explore the [Project Structure](/meta/project-structure)