From cedac8dbf6e12d8398437263c7981a7247de2f0f Mon Sep 17 00:00:00 2001 From: BBQ <35603386+HoneyBBQ@users.noreply.github.com> Date: Thu, 26 Feb 2026 20:20:29 +0800 Subject: [PATCH] chore: require config.toml for deployment, update docs (#139) - docker-compose.yml now defaults to ./config.toml instead of conf/app.docker.toml, enforcing explicit configuration for production deployments (dev environment still uses conf/ directly) - Update DEPLOYMENT.md and docs with clear instructions to copy config template before starting - Update config-toml.md: add registry/cni fields, remove obsolete [brave] section (search providers are now managed via web UI), fix default values - Add China mainland mirror documentation --- DEPLOYMENT.md | 47 ++++++++-------- docker-compose.yml | 6 +- docs/docs/installation/config-toml.md | 39 ++++++------- docs/docs/installation/docker.md | 81 ++++++++++++++------------- 4 files changed, 86 insertions(+), 87 deletions(-) diff --git a/DEPLOYMENT.md b/DEPLOYMENT.md index c8b187dc..99051eaf 100644 --- a/DEPLOYMENT.md +++ b/DEPLOYMENT.md @@ -6,46 +6,50 @@ curl -fsSL https://memoh.sh | sudo sh ``` -Or manually: +The script prompts for configuration, generates `config.toml`, and starts all services. + +## Manual Install ```bash git clone https://github.com/memohai/Memoh.git cd Memoh +cp conf/app.docker.toml config.toml +nano config.toml # Change passwords and JWT secret sudo docker compose up -d ``` > On macOS or if your user is in the `docker` group, `sudo` is not required. +> **Important**: You must create `config.toml` before starting. `docker-compose.yml` mounts `./config.toml` into the containers — running without it will fail. + Access: - Web UI: http://localhost:8082 - API: http://localhost:8080 - Agent: http://localhost:8081 -Default credentials: `admin` / `admin123` +Default credentials: `admin` / `admin123` (change in `config.toml`) ## Prerequisites - Docker (with Docker Compose v2) - Git -That's it. No containerd, nerdctl, or buildkit required on the host. +## Configuration -## Custom Configuration - -By default, Docker Compose uses `conf/app.docker.toml` (no file in project root is mounted; only this config file is mounted into the containers). - -To use your own config, create and edit it in the project root, then point `MEMOH_CONFIG` at it (path is on the host; run `docker compose` from the project root): - -```bash -cp conf/app.docker.toml config.toml -nano config.toml -sudo MEMOH_CONFIG=./config.toml docker compose up -d -``` +`config.toml` is generated from `conf/app.docker.toml` and should live in the project root. It is mounted into all containers at startup and is **not** tracked by git. Recommended changes for production: -- `admin.password` - Admin password -- `auth.jwt_secret` - JWT secret (generate with `openssl rand -base64 32`) -- `postgres.password` - Database password +- `admin.password` — Admin password +- `auth.jwt_secret` — JWT secret (generate with `openssl rand -base64 32`) +- `postgres.password` — Database password (also set `POSTGRES_PASSWORD` env var) + +### China Mainland Mirror + +Uncomment `registry = "memoh.cn"` in `config.toml` under `[mcp]`, then use: + +```bash +sudo docker compose -f docker-compose.yml -f docker/docker-compose.cn.yml up -d +``` ## Common Commands @@ -56,13 +60,13 @@ docker compose up -d # Start docker compose down # Stop docker compose logs -f # View logs docker compose ps # Status -docker compose up -d --build # Rebuild and restart +docker compose pull && docker compose up -d # Update images ``` ## Production -1. Configure HTTPS (create `docker-compose.override.yml` with SSL certs) -2. Change all default passwords +1. Change all default passwords and secrets +2. Configure HTTPS (reverse proxy or `docker-compose.override.yml` with SSL) 3. Configure firewall 4. Set resource limits 5. Regular backups @@ -71,13 +75,12 @@ docker compose up -d --build # Rebuild and restart ```bash docker compose logs server # View service logs -docker compose logs containerd # View containerd logs docker compose config # Check configuration docker compose build --no-cache && docker compose up -d # Full rebuild ``` ## Security Warnings -- Main service has privileged container access - only run in trusted environments +- Main service has privileged container access — only run in trusted environments - Must change all default passwords and secrets - Use HTTPS in production diff --git a/docker-compose.yml b/docker-compose.yml index a9f348b1..4052c60b 100644 --- a/docker-compose.yml +++ b/docker-compose.yml @@ -43,7 +43,7 @@ services: container_name: memoh-migrate entrypoint: ["/app/memoh-server", "migrate", "up"] volumes: - - ${MEMOH_CONFIG:-./conf/app.docker.toml}:/app/config.toml:ro + - ${MEMOH_CONFIG:-./config.toml}:/app/config.toml:ro depends_on: postgres: condition: service_healthy @@ -57,7 +57,7 @@ services: privileged: true pid: host volumes: - - ${MEMOH_CONFIG:-./conf/app.docker.toml}:/app/config.toml:ro + - ${MEMOH_CONFIG:-./config.toml}:/app/config.toml:ro - containerd_data:/var/lib/containerd - server_cni_state:/var/lib/cni - memoh_data:/opt/memoh/data @@ -77,7 +77,7 @@ services: image: memohai/agent:latest container_name: memoh-agent volumes: - - ${MEMOH_CONFIG:-./conf/app.docker.toml}:/config.toml:ro + - ${MEMOH_CONFIG:-./config.toml}:/config.toml:ro - /etc/localtime:/etc/localtime:ro ports: - "8081:8081" diff --git a/docs/docs/installation/config-toml.md b/docs/docs/installation/config-toml.md index b471c844..863679a8 100644 --- a/docs/docs/installation/config-toml.md +++ b/docs/docs/installation/config-toml.md @@ -1,6 +1,6 @@ # config.toml Reference -Memoh uses a TOML configuration file. By default it looks for `config.toml` in the current directory. With Docker, you can mount a custom config via `MEMOH_CONFIG` (see [Docker installation](./docker#custom-configuration)). +Memoh uses a TOML configuration file (`config.toml`) in the project root. For Docker deployments, copy the template first: `cp conf/app.docker.toml config.toml`. See [Docker installation](./docker) for details. ## Full Example @@ -26,14 +26,15 @@ socket_path = "/run/containerd/containerd.sock" namespace = "default" [mcp] -image = "docker.io/library/memoh-mcp:latest" +# registry = "memoh.cn" # Uncomment for China mainland mirror +image = "memohai/mcp:latest" snapshotter = "overlayfs" data_root = "data" [postgres] host = "127.0.0.1" port = 5432 -user = "postgres" +user = "memoh" password = "your-password" database = "memoh" sslmode = "disable" @@ -47,14 +48,11 @@ timeout_seconds = 10 [agent_gateway] host = "127.0.0.1" port = 8081 +server_addr = ":8080" [web] host = "127.0.0.1" port = 8082 - -[brave] -api_key = "" -base_url = "https://api.search.brave.com/res/v1/" ``` ## Section Reference @@ -100,9 +98,12 @@ MCP (Model Context Protocol) container configuration. Each bot runs in a contain | Field | Type | Default | Description | |---------------|--------|---------|--------------------------------------------------| -| `image` | string | `"docker.io/library/memoh-mcp:latest"` | MCP container image | +| `registry` | string | `""` | Image registry mirror prefix. Set to `"memoh.cn"` for China mainland. When set, the final image ref becomes `registry/image`. | +| `image` | string | `"memohai/mcp:latest"` | MCP container image. Short Docker Hub names are auto-normalized for containerd (e.g. `memohai/mcp:latest` → `docker.io/memohai/mcp:latest`). | | `snapshotter` | string | `"overlayfs"` | Containerd snapshotter | | `data_root` | string | `"data"` | Host path for bot data (Docker: `/opt/memoh/data`) | +| `cni_bin_dir` | string | `"/opt/cni/bin"` | CNI plugin binary directory | +| `cni_conf_dir`| string | `"/etc/cni/net.d"` | CNI configuration directory | ### `[postgres]` @@ -110,7 +111,7 @@ MCP (Model Context Protocol) container configuration. Each bot runs in a contain |-----------|--------|---------|--------------------------------------------------| | `host` | string | `"127.0.0.1"` | PostgreSQL host | | `port` | int | `5432` | PostgreSQL port | -| `user` | string | `"postgres"` | Database user | +| `user` | string | `"memoh"` | Database user | | `password`| string | — | Database password | | `database`| string | `"memoh"` | Database name | | `sslmode` | string | `"disable"` | SSL mode: `disable`, `require`, `verify-ca`, `verify-full` | @@ -126,12 +127,11 @@ MCP (Model Context Protocol) container configuration. Each bot runs in a contain ### `[agent_gateway]` -| Field | Type | Default | Description | -|--------|--------|---------|--------------------------------------------------| -| `host` | string | `"127.0.0.1"` | Agent gateway bind host | -| `port` | int | `8081` | Agent gateway port | - -In Docker Compose, `host` is typically `"agent"` (service name). The agent reads `[server].addr` to call the main API. +| Field | Type | Default | Description | +|---------------|--------|---------|--------------------------------------------------| +| `host` | string | `"127.0.0.1"` | Agent gateway bind host. In Docker, use `"agent"` (service name). | +| `port` | int | `8081` | Agent gateway port | +| `server_addr` | string | `":8080"` | Address the agent uses to reach the main server. In Docker, use `"server:8080"`. | ### `[web]` @@ -140,11 +140,4 @@ In Docker Compose, `host` is typically `"agent"` (service name). The agent reads | `host` | string | `"127.0.0.1"` | Web UI bind host | | `port` | int | `8082` | Web UI port | -### `[brave]` - -Brave Search API for the web search tool. Leave `api_key` empty to disable web search. - -| Field | Type | Default | Description | -|-----------|--------|---------|--------------------------------------------------| -| `api_key` | string | `""` | Brave Search API key. Get one at [brave.com/search/api](https://brave.com/search/api). | -| `base_url`| string | `"https://api.search.brave.com/res/v1/"` | Brave Search API base URL | +Web search providers (Brave, Bing, Google, Tavily, Serper, SearXNG, Jina, Exa, Bocha, DuckDuckGo, Yandex, Sogou) are configured through the web UI under **Search Providers**, not in `config.toml`. diff --git a/docs/docs/installation/docker.md b/docs/docs/installation/docker.md index cdab6986..2940a3eb 100644 --- a/docs/docs/installation/docker.md +++ b/docs/docs/installation/docker.md @@ -1,6 +1,6 @@ # Docker Installation -Docker is the recommended way to run Memoh. The stack includes PostgreSQL, Qdrant, Containerd, the main server, 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. +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 @@ -8,7 +8,7 @@ Docker is the recommended way to run Memoh. The stack includes PostgreSQL, Qdran - [Docker Compose v2](https://docs.docker.com/compose/install/) - Git -## One-Click Install +## One-Click Install (Recommended) Run the official install script (requires Docker and Docker Compose): @@ -19,10 +19,10 @@ 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) +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 -5. Start all services with `docker compose up -d --build` +4. Generate `config.toml` from the Docker template with your settings +5. Pull images and start all services **Silent install** (use all defaults, no prompts): @@ -40,17 +40,44 @@ Defaults when running silently: ## Manual Install -Clone the repository and start with Docker Compose: - ```bash git clone https://github.com/memohai/Memoh.git cd Memoh -sudo docker compose up -d +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 (also set `POSTGRES_PASSWORD` env var to match) + +Then start: + +```bash +sudo POSTGRES_PASSWORD=your-db-password docker compose up -d ``` > On macOS or if your user is in the `docker` group, `sudo` is not required. -By default, Docker Compose uses `conf/app.docker.toml`. No config file in the project root is mounted — only this built-in config is used. See [config.toml reference](./config-toml) for all configuration fields. +> **Important**: `docker-compose.yml` mounts `./config.toml` by default. 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`: + +```toml +[mcp] +registry = "memoh.cn" +``` + +And use the China mirror compose overlay: + +```bash +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. ## Access Points @@ -62,32 +89,9 @@ After startup: | API | http://localhost:8080 | | Agent Gateway | http://localhost:8081 | -Default login: `admin` / `admin123` +Default login: `admin` / `admin123` (change this in `config.toml`). -First startup may take 1–2 minutes while images build and services initialize. - -## Custom Configuration - -To use your own config file: - -1. Copy the Docker config template and edit it. See [config.toml reference](./config-toml) for field descriptions: - -```bash -cp conf/app.docker.toml config.toml -nano config.toml -``` - -2. Point `MEMOH_CONFIG` at your config when starting (path is on the host; run `docker compose` from the project root): - -```bash -sudo MEMOH_CONFIG=./config.toml docker compose up -d -``` - -**Recommended changes for production** (see [config.toml reference](./config-toml) for details): - -- `admin.password` — Change the admin password -- `auth.jwt_secret` — Generate with `openssl rand -base64 32` -- `postgres.password` — Change the database password (and set `POSTGRES_PASSWORD` when running `docker compose`) +First startup may take 1–2 minutes while images are pulled and services initialize. ## Common Commands @@ -98,13 +102,13 @@ docker compose up -d # Start docker compose down # Stop docker compose logs -f # View logs docker compose ps # Status -docker compose up -d --build # Rebuild and restart +docker compose pull && docker compose up -d # Update to latest images ``` ## Production Checklist -1. **HTTPS** — Configure SSL (e.g. via `docker-compose.override.yml` with certs) -2. **Passwords** — Change all default passwords and secrets +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 @@ -113,8 +117,7 @@ docker compose up -d --build # Rebuild and restart ```bash docker compose logs server # View main service logs -docker compose logs containerd # View containerd logs -docker compose config # Validate configuration +docker compose config # Validate configuration docker compose build --no-cache && docker compose up -d # Full rebuild ```