From effe033c4fe484267fb4ce93eaaf70d229f2e59c Mon Sep 17 00:00:00 2001 From: weishu Date: Sat, 31 Jan 2026 11:01:33 +0800 Subject: [PATCH] docs: unify ENV and settings.json configuration documentation (#113) - Add settings.json column to environment variables table with key name mappings - Document missing ENV variables: TELEGRAM_BOT_TOKEN, TELEGRAM_NOTIFICATION, HAPI_RELAY_FORCE_TCP, VAPID_SUBJECT - Add settings.json example with configuration priority explanation - Create JSON Schema file for settings.json validation and editor autocompletion with all fields, descriptions, and ENV variable references clsoe #113 --- docs/guide/installation.md | 47 ++++++++++---- docs/public/schemas/settings.schema.json | 78 ++++++++++++++++++++++++ 2 files changed, 113 insertions(+), 12 deletions(-) create mode 100644 docs/public/schemas/settings.schema.json diff --git a/docs/guide/installation.md b/docs/guide/installation.md index ecdeb5e5..0e66080c 100644 --- a/docs/guide/installation.md +++ b/docs/guide/installation.md @@ -166,18 +166,41 @@ On first run, HAPI:
Environment variables -| Variable | Default | Description | -|----------|---------|-------------| -| `CLI_API_TOKEN` | Auto-generated | Shared secret for authentication | -| `HAPI_API_URL` | `http://localhost:3006` | Hub URL for CLI | -| `HAPI_LISTEN_HOST` | `127.0.0.1` | HTTP service bind address | -| `HAPI_LISTEN_PORT` | `3006` | HTTP service port | -| `HAPI_PUBLIC_URL` | - | Public URL for external access | -| `HAPI_HOME` | `~/.hapi` | Config directory path | -| `DB_PATH` | `~/.hapi/hapi.db` | Database file path | -| `CORS_ORIGINS` | - | Allowed CORS origins | -| `ELEVENLABS_API_KEY` | - | ElevenLabs API key for voice | -| `ELEVENLABS_AGENT_ID` | Auto-created | Custom ElevenLabs agent ID | +| Variable | Default | settings.json | Description | +|----------|---------|---------------|-------------| +| `CLI_API_TOKEN` | Auto-generated | `cliApiToken` | Shared secret for authentication | +| `HAPI_API_URL` | `http://localhost:3006` | `apiUrl` | Hub URL for CLI connections | +| `HAPI_LISTEN_HOST` | `127.0.0.1` | `listenHost` | Hub HTTP bind address | +| `HAPI_LISTEN_PORT` | `3006` | `listenPort` | Hub HTTP port | +| `HAPI_PUBLIC_URL` | - | `publicUrl` | Public URL for external access | +| `CORS_ORIGINS` | - | `corsOrigins` | Allowed CORS origins (comma-separated) | +| `TELEGRAM_BOT_TOKEN` | - | `telegramBotToken` | Telegram Bot API token | +| `TELEGRAM_NOTIFICATION` | `true` | `telegramNotification` | Enable Telegram notifications | +| `HAPI_RELAY_FORCE_TCP` | `false` | - | Force TCP mode for relay | +| `VAPID_SUBJECT` | `mailto:admin@hapi.run` | - | Web Push contact info | +| `HAPI_HOME` | `~/.hapi` | - | Config directory path | +| `DB_PATH` | `~/.hapi/hapi.db` | - | Database file path | +| `ELEVENLABS_API_KEY` | - | - | ElevenLabs API key for voice | +| `ELEVENLABS_AGENT_ID` | Auto-created | - | Custom ElevenLabs agent ID | +
+ +
+settings.json example + +Configuration priority: **ENV > settings.json > default** + +When ENV values are set and not present in settings.json, they are automatically saved. + +```json +{ + "$schema": "https://hapi.run/schemas/settings.schema.json", + "listenHost": "0.0.0.0", + "listenPort": 3006, + "publicUrl": "https://your-domain.com" +} +``` + +JSON Schema: [settings.schema.json](https://hapi.run/schemas/settings.schema.json)
## CLI setup diff --git a/docs/public/schemas/settings.schema.json b/docs/public/schemas/settings.schema.json new file mode 100644 index 00000000..b1f5556b --- /dev/null +++ b/docs/public/schemas/settings.schema.json @@ -0,0 +1,78 @@ +{ + "$schema": "http://json-schema.org/draft-07/schema#", + "$id": "https://hapi.run/schemas/settings.schema.json", + "title": "HAPI Settings", + "description": "Configuration file for HAPI (~/.hapi/settings.json)", + "type": "object", + "properties": { + "cliApiToken": { + "type": "string", + "description": "Shared secret for CLI authentication. Auto-generated if not set. ENV: CLI_API_TOKEN" + }, + "apiUrl": { + "type": "string", + "format": "uri", + "default": "http://localhost:3006", + "description": "Hub URL for CLI connections. ENV: HAPI_API_URL" + }, + "listenHost": { + "type": "string", + "default": "127.0.0.1", + "description": "Hub HTTP bind address. ENV: HAPI_LISTEN_HOST" + }, + "listenPort": { + "type": "integer", + "default": 3006, + "minimum": 1, + "maximum": 65535, + "description": "Hub HTTP port. ENV: HAPI_LISTEN_PORT" + }, + "publicUrl": { + "type": "string", + "format": "uri", + "description": "Public URL for external access (e.g., Telegram Mini App). ENV: HAPI_PUBLIC_URL" + }, + "corsOrigins": { + "type": "array", + "items": { + "type": "string" + }, + "description": "Allowed CORS origins. ENV: CORS_ORIGINS (comma-separated)" + }, + "telegramBotToken": { + "type": "string", + "description": "Telegram Bot API token from @BotFather. ENV: TELEGRAM_BOT_TOKEN" + }, + "telegramNotification": { + "type": "boolean", + "default": true, + "description": "Enable Telegram notifications. ENV: TELEGRAM_NOTIFICATION" + }, + "vapidKeys": { + "type": "object", + "description": "Auto-generated Web Push VAPID keys. Do not edit manually.", + "properties": { + "publicKey": { + "type": "string" + }, + "privateKey": { + "type": "string" + } + }, + "required": ["publicKey", "privateKey"] + }, + "machineId": { + "type": "string", + "description": "Auto-generated unique machine identifier. Do not edit manually." + }, + "machineIdConfirmedByServer": { + "type": "boolean", + "description": "Internal flag. Do not edit manually." + }, + "runnerAutoStartWhenRunningHappy": { + "type": "boolean", + "description": "Auto-start runner when running hapi command." + } + }, + "additionalProperties": false +}