​
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.
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.

​
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.
  • Tmux & Tmuxinator (Optional but Recommended): Useful for managing multiple services in the terminal. Install Tmuxinator (e.g., brew install tmuxinator on macOS).

​
Setup Steps

  1. Clone the Repository: 
    git clone https://github.com/latitude-dev/latitude-llm.git
cd latitude-llm
  2. Install Dependencies: 
    pnpm install
  3. Build Shared Packages: Build the core packages that other services depend on. 
    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. 
docker compose up -d
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).
Alternatively, if using Tmuxinator (recommended): 
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.
  1. Run Database Migrations: Once the database container is running (check docker compose ps or the tmuxinator output), apply the necessary database schema migrations. 
    cd packages/core
pnpm db:migrate
cd ../..
  2. 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: 
    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: 
await database.select().from(users).limit(10)

​
Next Steps