# Upgrading MateClaw ## 1.0.x → 1.1.0 **TL;DR** — Most users have nothing to do. Restart with 1.1.0, Flyway's built-in repair heals known checksum drift, Ollama auto-discovery rewrites the bad `:latest` defaults, and everything else self-converges. Docker Compose deployments need a one-time `.env` update. See `docs/en/releases/1.1.0.md` for the feature changelog. --- ## For everyone ### ⚠️ What happens automatically (no action) - **Flyway migration self-heal** — 1.1.0 rewrote all MySQL migrations V2–V14 to replace unsupported `ADD COLUMN IF NOT EXISTS` syntax (Gitee #IIYHLJ). `FlywayRepairConfig` runs `flyway.repair()` on every boot, so the new checksums auto-accept and migration resumes from wherever your schema is. - **Ollama default model** — if your 1.0.x run auto-picked a model tag Ollama no longer has (commonly `deepseek-r1:latest`), on 1.1.0 restart `OllamaAutoDiscoveryRunner` detects the broken default and re-picks a tag-capable model (e.g. `deepseek-r1:7b`, `qwen3:latest`), preferring one that supports function calling. - **Stale `mate_model_config` rows** — idempotent seed data reconciles on each startup. ### 📋 Recommended pre-upgrade steps 1. Back up your database — `mateclaw` schema on MySQL, or `data/mateclaw.mv.db` on H2. 2. Back up `data/` directory (skill workspaces, uploaded files, memory files). 3. Note your current default model in Settings → Models in case you want to switch back. ### 🚀 Upgrade ```bash git pull cd mateclaw-server mvn clean package -DskipTests # then restart your service per your deployment method ``` Or for Desktop app users: just update to 1.1.0 via the in-app updater or re-download. --- ## For Docker Compose deployments **One-time migration step required** — 1.1.0 refuses to start with default hardcoded passwords. ### 1. Copy-paste merge the new `.env.example` keys ```bash cp .env .env.backup # open .env.example — it has new required keys: # DB_PASSWORD= (was default 'mateclaw123', now MUST be overridden) # DB_ROOT_PASSWORD= (new, required for MySQL root) # JWT_SECRET= (new, strongly recommended) # MATECLAW_CORS_ALLOWED_ORIGINS= (new, strongly recommended for prod) ``` ### 2. Set strong values in your `.env` ```env # STRONG passwords — at least 16 chars, mixed case + digits + symbols DB_PASSWORD= DB_ROOT_PASSWORD= # 32+ char random string — generate with: openssl rand -base64 48 JWT_SECRET= # Production CORS allowlist — comma-separated, no wildcards MATECLAW_CORS_ALLOWED_ORIGINS=https://mateclaw.example.com ``` If any of `DB_PASSWORD` / `DB_ROOT_PASSWORD` / `DASHSCOPE_API_KEY` is missing, `docker compose up` will fail fast with a clear error — this is intentional. ### 3. Existing MySQL volume compatibility If you already ran 1.0.x with the old default password (`mateclaw123`), **your existing MySQL volume still has the old root password inside**. You have two options: **Option A — keep existing password** (fastest, least secure): Set `DB_ROOT_PASSWORD=mateclaw123` and `DB_PASSWORD=mateclaw123` in `.env` to match. Upgrade works. Then rotate after upgrade using `ALTER USER ... IDENTIFIED BY ...` inside the MySQL container. **Option B — fresh volume with new password** (cleanest, loses DB if not backed up): ```bash docker compose down -v # ⚠️ deletes mysql_data volume; back up first # edit .env with new strong password docker compose up -d ``` Then re-import your backup if you kept one. ### 4. Restart ```bash docker compose up -d docker compose logs -f mateclaw-server # watch for "Flyway Successfully applied N migrations" ``` Expected log lines during boot: - `Flyway Successfully applied N migrations to schema mateclaw` - `Ollama: auto-activated default model ''` (if you use Ollama — should NOT say `:latest` any more) - `[Security] Using default JWT secret!` → means you forgot to set `JWT_SECRET` — fix and restart --- ## For local dev / H2 deployments No action required. `mvn spring-boot:run` picks up the latest migrations on next start, Flyway repair handles checksum drift, H2 file at `data/mateclaw.mv.db` is preserved. --- ## Known migration quirks ### 1. If you manually fiddled with `flyway_schema_history` In 1.0.x some users hit Flyway version collisions (V8/V9 and V9/V10) which 1.1.0 fixes by renumbering. If you manually deleted rows from `flyway_schema_history` you may see `Validate failed` on 1.1.0 startup — run: ```sql -- MySQL DELETE FROM flyway_schema_history WHERE success = 0; ``` Then restart. `FlywayRepairConfig` will rebuild history from current schema state. ### 2. If your Ollama models are all in the no-tools family After upgrade, agents that require tool calling will log a warning on first invocation: ``` Ollama: auto-activated default model '...' but its family does not support tool calling ``` Fix — pull a tool-capable model, or switch default in Settings → Models: ```bash ollama pull qwen3 # or ollama pull llama3.1:8b # or ollama pull mistral-nemo ``` ### 3. If you had custom tools using `extract_document_text` / wiki tools Wiki chunk schema changed (new `embedding` + `embedding_model` columns on `mate_wiki_chunk`). Your existing wiki pages work unchanged; only semantic search is new and requires an embedding model to be configured in Settings → Models (a default DashScope embedding is seeded). --- ## Rolling back to 1.0.x Not recommended (some new tables / columns don't exist in 1.0.x), but possible if you backed up the DB before upgrade: ```bash git checkout v1.0.418 # restore DB backup docker compose up -d # or mvn spring-boot:run ``` If you need to keep the new data but downgrade the app, you're in unsupported territory — open a Gitee issue. --- ## Getting help - **Logs first**: `mateclaw-server/logs/mateclaw.log` + `mateclaw-error.log` have everything. Flyway decisions are at INFO level in main log. - **Doctor tab**: in-app Settings → Doctor runs basic health checks - **Gitee**: https://gitee.com/matevip_admin/mateclaw/issues — include your upgrade path (1.0.?? → 1.1.0), profile (H2 / MySQL), and the last 100 lines of startup log