Local Development
Dependencies
PostgreSQL
- version: PostgreSQL 18.4 with pgvector 0.8.5
- host:
localhost - port:
5432 - database:
soha - username:
pgsql - password:
pgsql
Initial Administrator
- username:
opensoha - email:
opensoha@soha.local - password:
opensoha
These are Soha’s standard initial credentials in every deployment form. Override either value only when the installation needs different credentials.
System Secrets
JWT, runner, webhook, and credential encryption all use soha-123456789012345678901234567890 by default. Local startup does not create or lock a SecretStore file. Use config or environment overrides when testing custom values. Do not change the credential encryption key after encrypted test data exists unless that data is migrated or can be discarded.
Initialize Local Development Dependencies
npm ci
make initRun the Make commands from the Root soha checkout.
npm ci installs the Node dependencies from the Root lockfile. make init checks Go module hygiene against the same-checkout SDK and initializes the selected database mode. DEV_DB_MODE defaults to external, so initialization uses the database configured in configs/config.yaml without starting a local database. To start the Compose PostgreSQL service instead, run make DEV_DB_MODE=local init.
Start Backend and Frontend
makeLocal frontend development does not rely on an in-repository frontend .env template file. By default:
web/src/services/api-client.tsrequests same-origin/api/v1web/vite.config.tsproxies/apitohttp://127.0.0.1:8080soharedirects/docs/to the configured external documentation URL by default- To test documentation integration locally, start the
soha-docsdev server and configure the frontend or backend to use docs proxy mode
Optional shortcut commands:
make init
make dev-api
make dev-webStart Docs
cd ../soha-docs
npm install
npm run devsoha-docs is a standalone Next.js/Nextra site. Official i18n routes use /zh, /zh/docs/..., /en, and /en/docs/...; unprefixed / and /docs/... requests redirect through the nextra/locales proxy based on NEXT_LOCALE or browser language preferences. When publishing to https://docs.opensoha.dev/, set DOCS_BASE_URL to match the target deployment path.
Historical MVP Runtime Notes
The following describes the earlier MVP development setup; the current Make targets do not bootstrap a local Kubernetes cluster.
The backend bootstraps a local development cluster from configs/config.yaml and reads the generated kubeconfig from ./.dev/k3s/kubeconfig.yaml.
The minimal MVP exposes:
- cluster list
- namespace list
- pod list
- deployment list
- audit write for read APIs