Memoh/DEPLOYMENT.md

Memoh Docker Deployment Guide

Deploy Memoh AI Agent System with Docker Compose in one command.

Quick Start

1. Clone the Repository

git clone https://github.com/memohai/Memoh.git
cd Memoh

2. One-Click Deployment

./deploy.sh

The script will automatically:

• Check Docker and Docker Compose installation
• Create .env configuration file (if not exists)
• Generate random JWT secret
• Create config.toml configuration file
• Build MCP image
• Start all services

3. Access the Application

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

Default admin credentials:

• Username: admin
• Password: admin123 (change in .env)

Manual Deployment

If you prefer not to use the automated script:

# 1. Create configuration files
cp .env.example .env
cp config.docker.toml config.toml

# 2. Edit configuration (Important!)
nano .env

# 3. Generate JWT secret
openssl rand -base64 32

# 4. Build MCP image
docker build -f cmd/mcp/Dockerfile -t memoh-mcp:latest .

# 5. Start services
docker compose up -d

# 6. View logs
docker compose logs -f

Architecture

This deployment uses the host's Docker daemon to manage Bot containers:

Host Docker
├── memoh-postgres (PostgreSQL)
├── memoh-qdrant (Qdrant)
├── memoh-server (Main Service) ← Manages Bot containers via /var/run/docker.sock
├── memoh-agent (Agent Gateway)
├── memoh-web (Web Frontend)
└── memoh-bot-* (Bot containers, dynamically created by main service)

Advantages:

• ✅ Lightweight, no additional Docker daemon needed
• ✅ Better performance, uses host container runtime directly
• ✅ Easier to manage and debug
• ✅ Lower resource consumption

Common Commands

Using Make (Recommended)

make help       # Show all commands
make deploy     # One-click deployment
make logs       # View logs
make restart    # Restart services
make ps         # View status
make backup     # Backup data
make bots       # View Bot containers

Using Docker Compose

docker compose up -d        # Start services
docker compose down         # Stop services
docker compose logs -f      # View logs
docker compose ps           # View status
docker compose restart      # Restart services

Configuration

Environment Variables (.env)

Key configuration items:

# PostgreSQL password (must change)
POSTGRES_PASSWORD=your_secure_password

# JWT secret (must change)
JWT_SECRET=your_random_jwt_secret

# Admin account
ADMIN_USERNAME=admin
ADMIN_PASSWORD=your_admin_password
ADMIN_EMAIL=admin@yourdomain.com

Application Configuration (config.toml)

Main configuration items:

[postgres]
host = "postgres"
password = "your_secure_password"  # Must match POSTGRES_PASSWORD in .env

[containerd]
socket_path = "unix:///var/run/docker.sock"  # Use host Docker

[qdrant]
base_url = "http://qdrant:6334"

Service Overview

Service	Container Name	Ports	Description
postgres	memoh-postgres	-	PostgreSQL database (internal only)
qdrant	memoh-qdrant	-	Qdrant vector database (internal only)
docker-cli	memoh-docker-cli	-	Docker CLI (uses host Docker)
server	memoh-server	8080	Main service (Go)
agent	memoh-agent	8081	Agent Gateway (Bun)
web	memoh-web	80	Web frontend (Nginx)

Data Persistence

Data is stored in Docker volumes:

# View volumes
docker volume ls | grep memoh

# Backup database
docker compose exec postgres pg_dump -U memoh memoh > backup.sql

Bot Container Management

Bot containers are dynamically created by the main service and run directly on the host:

# View all Bot containers
make bots
# or
docker ps -a | grep memoh-bot

# View Bot logs
docker logs <bot-container-id>

# Enter Bot container
docker exec -it <bot-container-id> sh

# Stop Bot container
docker stop <bot-container-id>

Backup and Restore

Backup

# Create backup directory
mkdir -p backups

# Backup database
docker compose exec postgres pg_dump -U memoh memoh > backups/postgres_$(date +%Y%m%d).sql

# Backup Bot data
docker run --rm -v memoh_memoh_bot_data:/data -v $(pwd)/backups:/backup alpine \
  tar czf /backup/bot_data_$(date +%Y%m%d).tar.gz -C /data .

# Backup configuration files
tar czf backups/config_$(date +%Y%m%d).tar.gz config.toml .env

Restore

# Restore database
docker compose exec -T postgres psql -U memoh memoh < backups/postgres_20240101.sql

# Restore Bot data
docker run --rm -v memoh_memoh_bot_data:/data -v $(pwd)/backups:/backup alpine \
  tar xzf /backup/bot_data_20240101.tar.gz -C /data

Troubleshooting

Services Won't Start

# View detailed logs
docker compose logs server

# Check configuration
docker compose config

# Rebuild
docker compose build --no-cache
docker compose up -d

Database Connection Failed

# Check if database is ready
docker compose exec postgres pg_isready -U memoh

# Test connection
docker compose exec postgres psql -U memoh -d memoh

# View database logs
docker compose logs postgres

Port Conflicts

# Check port usage
sudo netstat -tlnp | grep :8080
sudo netstat -tlnp | grep :80

# Modify port mapping in docker-compose.yml
# Example: change "80:80" to "8000:80"

Docker Socket Permission Issues

# Add user to docker group
sudo usermod -aG docker $USER
newgrp docker

# Check permissions
ls -la /var/run/docker.sock

Production Deployment

1. Use HTTPS

Create docker-compose.override.yml:

services:
  web:
    ports:
      - "443:443"
    volumes:
      - ./ssl:/etc/nginx/ssl:ro
      - ./nginx-https.conf:/etc/nginx/conf.d/default.conf:ro

Create nginx-https.conf:

server {
    listen 80;
    server_name your-domain.com;
    return 301 https://$server_name$request_uri;
}

server {
    listen 443 ssl http2;
    server_name your-domain.com;
    
    ssl_certificate /etc/nginx/ssl/cert.pem;
    ssl_certificate_key /etc/nginx/ssl/key.pem;
    
    # SSL configuration
    ssl_protocols TLSv1.2 TLSv1.3;
    ssl_ciphers HIGH:!aNULL:!MD5;
    ssl_prefer_server_ciphers on;
    
    # Other configurations same as nginx.conf
    # ...
}

2. Resource Limits

Edit docker-compose.yml to add resource limits:

services:
  server:
    deploy:
      resources:
        limits:
          cpus: '2'
          memory: 2G
        reservations:
          cpus: '1'
          memory: 1G

3. Security Recommendations

Production environment recommendations:

• Use separate .env file
• Change all default passwords
• Use strong JWT secret
• Configure firewall rules
• Use HTTPS
• Regular data backups
• Limit containerd socket access permissions
• Run services as non-root user
• Configure log rotation

Performance Optimization

PostgreSQL Optimization

Create postgres-custom.conf:

shared_buffers = 2GB
effective_cache_size = 6GB
maintenance_work_mem = 512MB
checkpoint_completion_target = 0.9
wal_buffers = 16MB

Mount in docker-compose.yml:

postgres:
  volumes:
    - ./postgres-custom.conf:/etc/postgresql/postgresql.conf:ro
  command: postgres -c config_file=/etc/postgresql/postgresql.conf

Network Optimization

networks:
  memoh-network:
    driver: bridge
    driver_opts:
      com.docker.network.driver.mtu: 1500

Update Application

# Pull latest code
git pull

# Rebuild and restart
docker compose up -d --build

# Or use Make
make update

Complete Uninstall

# Stop and remove all containers
docker compose down

# Remove data volumes (Warning! This deletes all data)
docker compose down -v

# Remove images
docker rmi memoh-mcp:latest
docker rmi $(docker images | grep memoh | awk '{print $3}')

Security Considerations

⚠️ Important Security Notes:

1. Docker Socket Access: The main service container has access to the host Docker socket, which means the application can manage other containers on the host. Only run in trusted environments.
2. Change Default Passwords: Must change all default passwords in .env
3. Strong JWT Secret: Use a strong random JWT secret
4. Firewall: Configure firewall to only open necessary ports
5. HTTPS: Use HTTPS in production
6. Regular Backups: Regularly backup data
7. Updates: Regularly update images and dependencies

Get Help

• Detailed Documentation: DOCKER_DEPLOYMENT_CN.md (Chinese)
• GitHub Issues: https://github.com/memohai/Memoh/issues
• Telegram Group: https://t.me/memohai
• Email: business@memoh.net

---

That's it! Deploy Memoh in minutes!