Comprehensive Guide to Installing Letta with Docker and PostgreSQL on macOS Using Homebrew

Step-by-step instructions to set up Letta locally with Docker and PostgreSQL

Key Takeaways

Prerequisite Installation: Ensure Homebrew, Docker, and Docker Compose are installed for a smooth setup.
Persistent Data Management: Use Docker volumes to retain PostgreSQL data across container restarts.
Environment Configuration: Properly configure environment variables to establish seamless connectivity between Letta and PostgreSQL.

Introduction

Setting up Letta, an AI-powered tool, with Docker and PostgreSQL on macOS using Homebrew involves several steps that ensure a smooth and efficient installation process. This comprehensive guide will walk you through each stage, from installing prerequisites to verifying your setup, ensuring that you have a robust development environment for Letta.

1. Installing Prerequisites

1.1 Install Homebrew

Homebrew is a versatile package manager for macOS that simplifies the installation of software. If you haven't installed Homebrew yet, follow these steps:

Open the Terminal application on your Mac.

Run the following command to install Homebrew:

/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"

After installation, verify it by checking the version:
```
brew --version
```

1.2 Install Docker and Docker Compose

Docker is essential for containerizing applications, while Docker Compose allows you to manage multi-container Docker applications. Install both using Homebrew:

Install Docker Desktop:
```
brew install --cask docker
```
Launch Docker Desktop either from the Applications folder or via Terminal:
```
open /Applications/Docker.app
```
Wait for Docker to initialize. The whale icon in the menu bar indicates Docker's status.
Verify Docker installation:
```
docker --version
```
Docker Compose is included with Docker Desktop. To verify, run:
```
docker-compose --version
```

2. Setting Up PostgreSQL with Docker

2.1 Create a Persistent Volume

To ensure that your PostgreSQL data persists across container restarts and removals, create a Docker volume:

Create a directory for PostgreSQL data:

mkdir -p $HOME/docker/volumes/postgres-data

2.2 Pull and Run the PostgreSQL Docker Image

Execute the following command to pull the latest PostgreSQL image and run it in a Docker container:

docker run --name letta-postgres \
  -v $HOME/docker/volumes/postgres-data:/var/lib/postgresql/data \
  -e POSTGRES_USER=letta_user \
  -e POSTGRES_PASSWORD=secure_password \
  -e POSTGRES_DB=letta_db \
  -p 5432:5432 \
  -d postgres:latest

Explanation of Flags:

--name letta-postgres: Assigns the name "letta-postgres" to the container.
-v: Mounts the Docker volume for persistent storage.
-e POSTGRES_USER: Sets the PostgreSQL username.
-e POSTGRES_PASSWORD: Sets the PostgreSQL password.
-e POSTGRES_DB: Specifies the name of the database.
-p 5432:5432: Maps port 5432 of the container to port 5432 on the host machine.
-d postgres:latest: Runs the container in detached mode using the latest PostgreSQL image.

2.3 Verify PostgreSQL Container

Check if the PostgreSQL container is running:
```
docker ps
```
You should see "letta-postgres" listed among the running containers.
Connect to the PostgreSQL database using psql or a GUI tool like pgAdmin:
```
docker exec -it letta-postgres psql -U letta_user -d letta_db
```
Enter the password when prompted.

3. Installing and Configuring Letta with Docker

3.1 Clone the Letta Repository

Begin by cloning the Letta repository from GitHub or downloading the necessary files:

Clone the repository:

git clone https://github.com/letta-ai/letta.git

Navigate to the Letta directory:
```
cd letta
```

3.2 Build the Letta Docker Image

If Letta provides a Dockerfile, build the Docker image using the following command:

docker build -t letta .

Note: Ensure that the Dockerfile is present in the root directory of the Letta project.

3.3 Configure Environment Variables

Environment variables are crucial for establishing connections between Letta and PostgreSQL, as well as configuring any additional services. Follow these steps:

Create an .env file in the Letta directory:
```
touch letta.env
```

Open the letta.env file in your preferred text editor and add the following content:

.env
LETTA_DATABASE_HOST=host.docker.internal
LETTA_DATABASE_PORT=5432
LETTA_DATABASE_NAME=letta_db
LETTA_DATABASE_USER=letta_user
LETTA_DATABASE_PASSWORD=secure_password
LETTA_LLM_API_KEY=your_openai_api_key

Replace your_openai_api_key with your actual API key and adjust other values as necessary to match your PostgreSQL configuration.

3.4 Run the Letta Docker Container

Use the following command to run the Letta container, ensuring it connects to the PostgreSQL container:

docker run --name letta-app \
--env-file letta.env \
-p 8000:8000 \
--link letta-postgres:postgres \
-d letta

Explanation of Flags:

--name letta-app: Assigns the name "letta-app" to the container.
--env-file letta.env: Supplies the container with environment variables from the letta.env file.
-p 8000:8000: Maps port 8000 of the container to port 8000 on the host machine.
--link letta-postgres:postgres: Links the Letta container to the PostgreSQL container, allowing inter-container communication.
-d letta: Runs the Letta image in detached mode.

Alternative Using Docker Compose: For better management, consider using Docker Compose as detailed in section 5.

3.5 Verify the Letta Installation

Check if the Letta container is running:
```
docker ps
```
You should see "letta-app" listed among the running containers.
Access Letta in your web browser by navigating to:
```
http://localhost:8000
```
You should see the Letta interface if everything is set up correctly.

4. Managing PostgreSQL and Letta Containers

4.1 Accessing PostgreSQL Directly

To interact with your PostgreSQL database, you can use tools like psql or pgAdmin. Here's how to connect using psql:

docker exec -it letta-postgres psql -U letta_user -d letta_db

Enter the password when prompted to access the PostgreSQL shell.

4.2 Monitoring Container Logs

To monitor the logs of the Letta container, use the following command:

docker logs -f letta-app

The -f flag follows the log output in real-time.

4.3 Stopping and Removing Containers

When you need to stop the containers, execute:

docker stop letta-app letta-postgres

To remove the containers:

docker rm letta-app letta-postgres

5. Automating with Docker Compose

5.1 Creating a Docker Compose File

Docker Compose allows you to define and manage multi-container Docker applications with ease. Create a docker-compose.yml file in your Letta project directory with the following content:

version: '3.8'

services:
  postgres:
    image: postgres:latest
    container_name: letta-postgres
    environment:
      POSTGRES_USER: letta_user
      POSTGRES_PASSWORD: secure_password
      POSTGRES_DB: letta_db
    ports:
      - "5432:5432"
    volumes:
      - postgres-data:/var/lib/postgresql/data

  letta:
    image: letta/letta:latest
    container_name: letta-app
    depends_on:
      - postgres
    environment:
      - LETTA_DATABASE_HOST=postgres
      - LETTA_DATABASE_PORT=5432
      - LETTA_DATABASE_NAME=letta_db
      - LETTA_DATABASE_USER=letta_user
      - LETTA_DATABASE_PASSWORD=secure_password
      - LETTA_LLM_API_KEY=your_openai_api_key
    ports:
      - "8000:8000"
    links:
      - postgres

volumes:
  postgres-data:

Explanation:

version: '3.8': Specifies the Docker Compose version.
services:: Defines the services (containers) to be managed.
postgres:: Configuration for the PostgreSQL service.
letta:: Configuration for the Letta service.
volumes:: Defines persistent storage volumes.

5.2 Running Docker Compose

Navigate to your project directory containing the docker-compose.yml file:
```
cd path/to/your/letta/project
```
Start the containers in detached mode:
```
docker-compose up -d
```
Verify that both containers are running:
```
docker-compose ps
```

5.3 Managing Services with Docker Compose

Docker Compose provides several commands to manage your services efficiently:

Stopping Services:
```
docker-compose stop
```
Starting Services:
```
docker-compose start
```
Viewing Logs:
```
docker-compose logs -f
```
Bringing Down Services:
```
docker-compose down
```

Note: To remove all associated volumes and networks, use docker-compose down -v.

6. Advanced Configurations and Tips

6.1 Securing Your Setup

Security is paramount when setting up databases and applications. Consider the following best practices:

Use Strong Passwords: Ensure that the POSTGRES_PASSWORD and LETTA_LLM_API_KEY are strong and kept confidential.
Limit Exposed Ports: Only expose necessary ports to minimize potential attack vectors.
Network Isolation: Use Docker networks to isolate your containers from external networks.

6.2 Optimizing Docker Performance on macOS

Docker performance on macOS can be optimized by adjusting resource allocations:

Allocate Sufficient Resources: Ensure Docker has enough CPU and memory allocated via Docker Desktop settings.
Use Named Volumes: Named volumes are managed by Docker and offer better performance compared to bind mounts.
Enable Experimental Features: Docker Desktop offers experimental features that can enhance performance but use them with caution.

6.3 Backup and Restore PostgreSQL Data

Regular backups ensure data integrity. Here's how to back up and restore your PostgreSQL data:

6.3.1 Backup PostgreSQL Data

docker exec letta-postgres pg_dump -U letta_user letta_db > letta_db_backup.sql

6.3.2 Restore PostgreSQL Data

docker exec -i letta-postgres psql -U letta_user -d letta_db < letta_db_backup.sql

6.4 Updating Containers

To keep your setup up-to-date with the latest security patches and features:

Pull the latest images:

docker pull postgres:latest

docker pull letta/letta:latest

Rebuild and restart the containers:

docker-compose down

docker-compose up -d --build

Conclusion

Installing Letta with Docker and PostgreSQL on macOS using Homebrew is a structured process that, when followed meticulously, results in a stable and efficient development environment. By leveraging Docker Compose, you can manage your containers seamlessly, ensuring persistent data storage and easy scalability. Adhering to best practices in security and performance optimization will further enhance your setup, providing a robust foundation for your projects with Letta.

References

medium.com

How to run PostgreSQL in Docker on Mac (for local development)

simplebackups.com

Run PostgreSQL on Docker: Guide for Mac & Linux

cprime.com

Docker for Mac: Homebrew Step-by-Step Tutorial

docs.letta.com

Run Letta with Docker Documentation

saltycrane.com

Install PostgreSQL using Docker on macOS

Last updated January 25, 2025