mateclaw/UPGRADING.md

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

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

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

# STRONG passwords — at least 16 chars, mixed case + digits + symbols
DB_PASSWORD=<your-strong-db-user-password>
DB_ROOT_PASSWORD=<different-strong-root-password>

# 32+ char random string — generate with: openssl rand -base64 48
JWT_SECRET=<your-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):

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

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 '<actual-tag>' (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:

-- 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:

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:

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