Skip to content

Database, deployment and troubleshooting ​

Choose and initialize a database ​

Use caseProcedure
First local installationKAIWU_DB_TYPE=mysql ./kaiwu up creates MySQL. Startup runs the migrations.
Existing MySQLPrepare a separate empty database and supply KAIWU_DB_HOST, port, database, username and password in protected runtime configuration.
Dameng DM8Prepare 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 dataIn 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.env from 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-init to fetch the GitOps repository. Find the Chart in System under deploy/helm/kaiwu. Pin image versions and prepare the namespace and runtime credentials. Use helm lint and helm template to 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-up in the System launcher and inspect native processes with local-status and local-logs. Configuration templates and startup parameters

Troubleshooting ​

SymptomFirst check
A second instance conflicts with ports or connects to an old databaseUse a separate checkout, project name, published ports and platform network. Reuse those settings for this instance. Inspect ./kaiwu status.
Image pull failsDistinguish 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 platformCompare the browser URL, CLI KAIWU_URL and ./kaiwu whoami. Inspect first-login credentials locally.
Workbench works but the business page failsCheck membership, project entry, frontend mount and explicit Gateway route. Run ./kaiwu logs --tail 100. Follow a request
A configuration change has no effectCheck 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.

Apache License 2.0