Database, deployment and troubleshooting
Choose and initialize a database
| Use case | Procedure |
|---|---|
| First local installation | KAIWU_DB_TYPE=mysql ./kaiwu up creates MySQL. Startup runs the migrations. |
| Existing MySQL | Prepare a separate empty database and supply KAIWU_DB_HOST, port, database, username and password in protected runtime configuration. |
| Dameng DM8 | Prepare a separate empty schema. Check UTF-8, page size, case sensitivity and compatibility mode. Run the database guide’s preflight checks. |
| DBA review of initialization data | In a separate empty database, run mysql-01-ddl.sql or dm8-01-ddl.sql, then the matching 02-dml.sql file to inspect seed data. Application startup requires Flyway history. Use a separate empty database for Compose or Helm so its migration task initializes the schema and records that history. |
v0.3.0 installs apply V127 and V128. Existing v0.2.0 installations apply V128 through the existing migration process. A v0.1.0 (V44) installation needs a new database. For intermediate versions choose the path for the last successful Flyway version. Initialization scripts can damage an existing database. Take a recoverable backup before upgrading. Database configuration · Initialization SQL downloads and instructions · Version-specific upgrade paths
Deploy on a server or Kubernetes
- Single-server Compose. Check out matching product versions, then run
./scripts/kaiwu-server-env.sh ../.kaiwu-server/runtime.envfrom System to prepare runtime configuration. Use the base and server Compose files together as documented. Configure the reverse proxy and same-origin entry, deploy the business backend and frontend, and verify an authenticated read from the workbench. Server and external MySQL / Redis - Kubernetes. Run
./kaiwu deploy-initto fetch the GitOps repository. Find the Chart in System underdeploy/helm/kaiwu. Pin image versions and prepare the namespace and runtime credentials. Usehelm lintandhelm templateto check the target values. After installation check the migration Job, Pod readiness, explicit route and same-origin business UI. Install, upgrade and roll back - Nacos development environment. Give System and Gateway their respective Data IDs. Set route audiences explicitly and configure egress for the actual storage and model hosts. Start the environment with
local-upin the System launcher and inspect native processes withlocal-statusandlocal-logs. Configuration templates and startup parameters
Troubleshooting
| Symptom | First check |
|---|---|
| A second instance conflicts with ports or connects to an old database | Use a separate checkout, project name, published ports and platform network. Reuse those settings for this instance. Inspect ./kaiwu status. |
| Image pull fails | Distinguish download failures from source build failures in the logs. Use ./kaiwu up --build to select source builds explicitly. |
| Sign-in fails or the CLI points to another platform | Compare the browser URL, CLI KAIWU_URL and ./kaiwu whoami. Inspect first-login credentials locally. |
| Workbench works but the business page fails | Check membership, project entry, frontend mount and explicit Gateway route. Run ./kaiwu logs --tail 100. Follow a request |
| A configuration change has no effect | Check the project code, sync preview, target environment and current identity. Start a new session if required. Configuration transfer |
Use ./kaiwu down to pause the local platform and retain its data. ./kaiwu reset deletes local platform data.