Skip to documentation
Documentation
Docs navigation
Docs/Database setup with Docker
Getting started

Database setup with Docker

Run a local PostgreSQL database with pgvector for MemoGrafter using a minimal Docker Compose setup.

Prerequisites

Docker Desktop, or Docker Engine with the Compose plugin.
A free local port for PostgreSQL. This guide uses 5432.

Compose file without Redis

For normal package usage, create compose.yml in your application directory with only PostgreSQL and pgvector. Redis is optional and is not required to run MemoGrafter.

compose.yml
services:
  postgres:
    image: pgvector/pgvector:pg16
    environment:
      POSTGRES_USER: memografter
      POSTGRES_PASSWORD: memografter
      POSTGRES_DB: memografter
    ports:
      - "5432:5432"
    volumes:
      - memografter_postgres_data:/var/lib/postgresql/data
    healthcheck:
      test: ["CMD-SHELL", "pg_isready -U memografter -d memografter"]
      interval: 5s
      timeout: 5s
      retries: 10

volumes:
  memografter_postgres_data:

Compose file with Redis

Contributors, or package users testing queue mode and the optional recall cache, can use this expanded compose.yml. It keeps the same PostgreSQL setup and adds Redis.

Set REDIS_URL=redis://localhost:6379 only when enabling a Redis-backed MemoGrafter feature.

compose.yml
services:
  postgres:
    image: pgvector/pgvector:pg16
    environment:
      POSTGRES_USER: memografter
      POSTGRES_PASSWORD: memografter
      POSTGRES_DB: memografter
    ports:
      - "5432:5432"
    volumes:
      - memografter_postgres_data:/var/lib/postgresql/data
    healthcheck:
      test: ["CMD-SHELL", "pg_isready -U memografter -d memografter"]
      interval: 5s
      timeout: 5s
      retries: 10

  redis:
    image: redis:7-alpine
    ports:
      - "6379:6379"
    volumes:
      - memografter_redis_data:/data
    healthcheck:
      test: ["CMD", "redis-cli", "ping"]
      interval: 5s
      timeout: 5s
      retries: 10

volumes:
  memografter_postgres_data:
  memografter_redis_data:

Start PostgreSQL

Start the container in the background. Docker downloads the image automatically the first time.

terminal
docker compose up -d

Configure MemoGrafter

Set DATABASE_URL in your server environment. Its username, password, port, and database name must match the Compose file.

.env
DATABASE_URL=postgresql://memografter:memografter@localhost:5432/memografter

Initialize and migrate

Initialize MemoGrafter, then create or update its database schema. The migration manages MemoGrafter-owned tables and enables required PostgreSQL extensions, including vector.

terminal
npx memo-grafter init
npx memo-grafter migrate

Verify the setup

Run the doctor command to check the configuration and database connection.

terminal
npx memo-grafter doctor

Common Docker commands

terminal
# Show container status
docker compose ps

# Follow PostgreSQL logs
docker compose logs -f postgres

# Stop and remove the containers
docker compose down

Reset the local database

Use this only when you intentionally want a completely fresh local database, for example after changing the configured PostgreSQL credentials.

terminal
docker compose down -v

Common failures

Port 5432 already in use: stop the other PostgreSQL service or map another host port, such as 5433:5432, and use that port in DATABASE_URL.
Docker daemon not running: start Docker Desktop or the Docker Engine service, then retry docker compose up -d.
PostgreSQL container unhealthy: run docker compose ps and docker compose logs postgres; wait for startup to finish and check the environment values and available disk space.
DATABASE_URL mismatch: make its username, password, host port, and database name match POSTGRES_USER, POSTGRES_PASSWORD, POSTGRES_DB, and the Compose port mapping.
pgvector extension permission problem: run migrations as the database owner created by Compose. A restricted database user may not have permission to run CREATE EXTENSION vector.
Existing Docker volume with old credentials: PostgreSQL applies POSTGRES_* values only when initializing an empty data directory. Reuse the original credentials, or intentionally reset the volume after backing up any data you need.

Package users and contributors

Package users should start with the PostgreSQL-only Compose file. It contains everything required for ordinary MemoGrafter usage.

The PostgreSQL-and-Redis Compose file is intended for contributors and users testing queue mode, caching, and integrations. Adding Redis does not make it mandatory for the rest of MemoGrafter.