Docker Installation

Docker is the recommended way to run Memoh. The stack includes PostgreSQL, Qdrant, the main server (with embedded Containerd), agent gateway, and web UI — all orchestrated via Docker Compose. You do not need to install containerd, nerdctl, or buildkit on your host; everything runs inside containers.

Prerequisites

• Docker
• Docker Compose v2
• Git

One-Click Install (Recommended)

Run the official install script (requires Docker and Docker Compose):

curl -fsSL https://memoh.sh | sudo sh

The script will:

1. Check for Docker and Docker Compose
2. Prompt for configuration (workspace, data directory, admin credentials, JWT secret, Postgres password, China mirror)
3. Clone the repository
4. Generate config.toml from the Docker template with your settings
5. Write a .env file with POSTGRES_PASSWORD and MEMOH_CONFIG
6. Pull images and start all services

Silent install (use all defaults, no prompts):

curl -fsSL https://memoh.sh | sudo sh -s -- -y

Defaults when running silently:

• Workspace: ~/memoh
• Data directory: ~/memoh/data
• Admin: admin / admin123
• JWT secret: auto-generated
• Postgres password: memoh123

Manual Install

git clone --depth 1 https://github.com/memohai/Memoh.git
cd Memoh
cp conf/app.docker.toml config.toml

Edit config.toml — at minimum change:

• admin.password — Admin password
• auth.jwt_secret — Generate with openssl rand -base64 32
• postgres.password — Database password (must match the POSTGRES_PASSWORD env var)

Then start:

sudo POSTGRES_PASSWORD=your-db-password docker compose up -d

Alternatively, create a .env file in the project root:

POSTGRES_PASSWORD=your-db-password
MEMOH_CONFIG=./config.toml

Then simply run:

sudo docker compose up -d

On macOS or if your user is in the docker group, sudo is not required.

Important: docker-compose.yml mounts ${MEMOH_CONFIG:-./config.toml} into the containers. You must create this file before starting — running without it will fail.

China Mainland Mirror

For users in mainland China who cannot access Docker Hub directly, uncomment the registry line in config.toml:

[mcp]
registry = "memoh.cn"

And use the China mirror compose overlay:

sudo docker compose -f docker-compose.yml -f docker/docker-compose.cn.yml up -d

The install script handles this automatically when you answer "yes" to the China mirror prompt.

Service Architecture

Docker Compose starts the following services:

Service	Image	Description
postgres	postgres:18-alpine	PostgreSQL database
qdrant	qdrant/qdrant:latest	Qdrant vector database for memory semantic search
migrate	memohai/server:latest	One-shot service — runs database migrations, then exits
server	memohai/server:latest	Main backend with embedded Containerd (privileged)
agent	memohai/agent:latest	Agent Gateway (Bun/Elysia) for AI chat, tool execution, and SSE streaming
web	memohai/web:latest	Web UI (Vue 3 + Nginx)

Startup order: postgres and qdrant start first; once healthy, migrate runs database migrations; after migration completes, server starts; finally agent and web come up.

Access Points

After startup:

Service	URL
Web UI	http://localhost:8082
API	http://localhost:8080
Agent Gateway	http://localhost:8081

Default login: admin / admin123 (change this in config.toml).

First startup may take 1–2 minutes while images are pulled and services initialize.

Data Persistence

All persistent data is stored in Docker named volumes:

Volume	Description
postgres_data	PostgreSQL database files
qdrant_data	Qdrant vector storage
containerd_data	Containerd image store and snapshots
memoh_data	Bot container data (mounted at /opt/memoh/data inside the server)
server_cni_state	CNI network state for container networking

These volumes survive docker compose down. To fully reset all data, run:

docker compose down -v

Common Commands

Prefix with sudo on Linux if your user is not in the docker group.

docker compose up -d           # Start
docker compose down            # Stop
docker compose logs -f         # View logs
docker compose logs server     # View a specific service's logs
docker compose ps              # Status
docker compose pull && docker compose up -d  # Update to latest images

Upgrading

To upgrade to the latest version:

cd /path/to/Memoh
git pull
docker compose pull
docker compose up -d

The migrate service runs automatically on every startup, applying any new database migrations.

Environment Variables

Variable	Default	Description
POSTGRES_PASSWORD	memoh123	PostgreSQL password (must match postgres.password in config.toml)
MEMOH_CONFIG	./config.toml	Path to the configuration file

Production Checklist

1. Passwords — Change all default passwords and secrets in config.toml
2. HTTPS — Configure SSL (e.g. via docker-compose.override.yml with certs or a reverse proxy)
3. Firewall — Restrict access to necessary ports
4. Resource limits — Set memory/CPU limits for containers
5. Backups — Regular backups of Postgres and Qdrant data volumes

Troubleshooting

docker compose logs server      # View main service logs
docker compose logs migrate     # Check if migrations succeeded
docker compose config           # Validate compose configuration
docker compose down && docker compose up -d  # Full restart

Security Warnings

• The main service runs with privileged container access (required for embedded Containerd) — only run in trusted environments
• You must change all default passwords and secrets before production use
• Use HTTPS in production