Add CLI reference documentation with vault commands
This commit is contained in:
parent
2c930a3316
commit
1fd5b13595
3 changed files with 459 additions and 0 deletions
|
|
@ -49,6 +49,7 @@ botserver-installers/ # Downloaded archives (cache)
|
|||
|
||||
## Chapter Contents
|
||||
|
||||
- [CLI Reference](./cli-reference.md) - Command-line interface for botserver
|
||||
- [Updating Components](./updating-components.md) - How to update individual services
|
||||
- [Component Reference](./component-reference.md) - Detailed info for each component
|
||||
- [Security Auditing](./security-auditing.md) - Running security audits
|
||||
|
|
|
|||
457
src/19-maintenance/cli-reference.md
Normal file
457
src/19-maintenance/cli-reference.md
Normal file
|
|
@ -0,0 +1,457 @@
|
|||
# CLI Reference
|
||||
|
||||
botserver provides a command-line interface for managing components, secrets, and services.
|
||||
|
||||
## General Usage
|
||||
|
||||
```bash
|
||||
botserver <command> [options]
|
||||
```
|
||||
|
||||
## Commands Overview
|
||||
|
||||
| Command | Description |
|
||||
|---------|-------------|
|
||||
| `install` | Install a component |
|
||||
| `remove` | Remove a component |
|
||||
| `list` | List all available components |
|
||||
| `status` | Check component status |
|
||||
| `start` | Start all installed components |
|
||||
| `stop` | Stop all components |
|
||||
| `restart` | Restart all components |
|
||||
| `vault` | Manage secrets in HashiCorp Vault |
|
||||
|
||||
## Global Options
|
||||
|
||||
| Option | Description |
|
||||
|--------|-------------|
|
||||
| `--container` | Use LXC container mode instead of local installation |
|
||||
| `--tenant <name>` | Specify tenant name (default: "default") |
|
||||
| `--help`, `-h` | Show help information |
|
||||
|
||||
---
|
||||
|
||||
## Component Management
|
||||
|
||||
### Install a Component
|
||||
|
||||
```bash
|
||||
botserver install <component> [--container] [--tenant <name>]
|
||||
```
|
||||
|
||||
**Examples:**
|
||||
|
||||
```bash
|
||||
# Install vault locally
|
||||
botserver install vault
|
||||
|
||||
# Install vault in an LXC container with tenant name
|
||||
botserver install vault --container --tenant pragmatismo
|
||||
|
||||
# Install vector database
|
||||
botserver install vector_db --container --tenant pragmatismo
|
||||
```
|
||||
|
||||
**Available Components:**
|
||||
|
||||
| Component | Description |
|
||||
|-----------|-------------|
|
||||
| `vault` | HashiCorp Vault - Secrets management |
|
||||
| `tables` | PostgreSQL - Primary database |
|
||||
| `cache` | Valkey - Redis-compatible cache |
|
||||
| `drive` | MinIO - S3-compatible object storage |
|
||||
| `llm` | llama.cpp - Local LLM server |
|
||||
| `email` | Stalwart - Mail server |
|
||||
| `proxy` | Caddy - HTTPS reverse proxy |
|
||||
| `dns` | CoreDNS - DNS server |
|
||||
| `directory` | Zitadel - Identity management |
|
||||
| `alm` | Forgejo - Git repository |
|
||||
| `alm_ci` | Forgejo Runner - CI/CD |
|
||||
| `meeting` | LiveKit - Video conferencing |
|
||||
| `vector_db` | Qdrant - Vector database |
|
||||
| `timeseries_db` | InfluxDB - Time series database |
|
||||
| `observability` | Vector - Log aggregation |
|
||||
|
||||
### Remove a Component
|
||||
|
||||
```bash
|
||||
botserver remove <component> [--container] [--tenant <name>]
|
||||
```
|
||||
|
||||
### List Components
|
||||
|
||||
```bash
|
||||
botserver list [--container] [--tenant <name>]
|
||||
```
|
||||
|
||||
Shows all available components and their installation status.
|
||||
|
||||
### Check Status
|
||||
|
||||
```bash
|
||||
botserver status <component> [--container] [--tenant <name>]
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Service Control
|
||||
|
||||
### Start Services
|
||||
|
||||
```bash
|
||||
botserver start [--container] [--tenant <name>]
|
||||
```
|
||||
|
||||
Starts all installed components.
|
||||
|
||||
### Stop Services
|
||||
|
||||
```bash
|
||||
botserver stop
|
||||
```
|
||||
|
||||
Stops all running components.
|
||||
|
||||
### Restart Services
|
||||
|
||||
```bash
|
||||
botserver restart [--container] [--tenant <name>]
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Vault Commands
|
||||
|
||||
The `vault` subcommand manages secrets stored in HashiCorp Vault.
|
||||
|
||||
### Prerequisites
|
||||
|
||||
Vault commands require these environment variables:
|
||||
|
||||
```bash
|
||||
export VAULT_ADDR=http://<vault-ip>:8200
|
||||
export VAULT_TOKEN=<your-vault-token>
|
||||
```
|
||||
|
||||
### Migrate Secrets from .env
|
||||
|
||||
Migrates secrets from an existing `.env` file to Vault.
|
||||
|
||||
```bash
|
||||
botserver vault migrate [env_file]
|
||||
```
|
||||
|
||||
**Arguments:**
|
||||
|
||||
| Argument | Description | Default |
|
||||
|----------|-------------|---------|
|
||||
| `env_file` | Path to .env file | `.env` |
|
||||
|
||||
**Example:**
|
||||
|
||||
```bash
|
||||
# Migrate from default .env
|
||||
botserver vault migrate
|
||||
|
||||
# Migrate from specific file
|
||||
botserver vault migrate /opt/gbo/bin/system/.env
|
||||
```
|
||||
|
||||
**Migrated Secret Paths:**
|
||||
|
||||
| .env Variables | Vault Path |
|
||||
|----------------|------------|
|
||||
| `TABLES_*` | `gbo/tables` |
|
||||
| `CUSTOM_*` | `gbo/custom` |
|
||||
| `DRIVE_*` | `gbo/drive` |
|
||||
| `EMAIL_*` | `gbo/email` |
|
||||
| `STRIPE_*` | `gbo/stripe` |
|
||||
| `AI_*`, `LLM_*` | `gbo/llm` |
|
||||
|
||||
After migration, your `.env` file only needs:
|
||||
|
||||
```env
|
||||
RUST_LOG=info
|
||||
VAULT_ADDR=http://<vault-ip>:8200
|
||||
VAULT_TOKEN=<vault-token>
|
||||
SERVER_HOST=0.0.0.0
|
||||
SERVER_PORT=5858
|
||||
```
|
||||
|
||||
### Store Secrets
|
||||
|
||||
Store key-value pairs at a Vault path.
|
||||
|
||||
```bash
|
||||
botserver vault put <path> <key=value> [key=value...]
|
||||
```
|
||||
|
||||
**Examples:**
|
||||
|
||||
```bash
|
||||
# Store database credentials
|
||||
botserver vault put gbo/tables host=localhost port=5432 username=postgres password=secret
|
||||
|
||||
# Store email configuration
|
||||
botserver vault put gbo/email server=mail.example.com user=admin password=secret
|
||||
|
||||
# Store API keys
|
||||
botserver vault put gbo/llm api_key=sk-xxx endpoint=https://api.openai.com
|
||||
```
|
||||
|
||||
### Retrieve Secrets
|
||||
|
||||
Get secrets from a Vault path.
|
||||
|
||||
```bash
|
||||
botserver vault get <path> [key]
|
||||
```
|
||||
|
||||
**Examples:**
|
||||
|
||||
```bash
|
||||
# Get all secrets at a path (values are masked)
|
||||
botserver vault get gbo/tables
|
||||
|
||||
# Get a specific key value
|
||||
botserver vault get gbo/tables password
|
||||
|
||||
# Get drive credentials
|
||||
botserver vault get gbo/drive
|
||||
```
|
||||
|
||||
**Output:**
|
||||
|
||||
```
|
||||
Secrets at gbo/tables:
|
||||
host=localhost
|
||||
port=5432
|
||||
database=botserver
|
||||
username=gbuser
|
||||
password=67a6...
|
||||
```
|
||||
|
||||
> **Note:** Sensitive values (password, secret, key, token) are automatically masked in output.
|
||||
|
||||
### List Secret Paths
|
||||
|
||||
Shows all configured secret paths.
|
||||
|
||||
```bash
|
||||
botserver vault list
|
||||
```
|
||||
|
||||
**Output:**
|
||||
|
||||
```
|
||||
Configured secret paths:
|
||||
gbo/tables - Database credentials
|
||||
gbo/drive - S3/MinIO credentials
|
||||
gbo/cache - Redis credentials
|
||||
gbo/email - SMTP credentials
|
||||
gbo/directory - Zitadel credentials
|
||||
gbo/llm - AI API keys
|
||||
gbo/encryption - Encryption keys
|
||||
gbo/meet - LiveKit credentials
|
||||
gbo/alm - Forgejo credentials
|
||||
gbo/vectordb - Qdrant credentials
|
||||
gbo/observability - InfluxDB credentials
|
||||
gbo/stripe - Payment credentials
|
||||
gbo/custom - Custom database
|
||||
```
|
||||
|
||||
### Health Check
|
||||
|
||||
Check Vault connection status.
|
||||
|
||||
```bash
|
||||
botserver vault health
|
||||
```
|
||||
|
||||
**Output (success):**
|
||||
|
||||
```
|
||||
* Vault is healthy
|
||||
Address: http://10.16.164.100:8200
|
||||
```
|
||||
|
||||
**Output (failure):**
|
||||
|
||||
```
|
||||
x Vault not configured
|
||||
Set VAULT_ADDR and VAULT_TOKEN environment variables
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Complete Setup Example
|
||||
|
||||
Here's a complete workflow to set up Vault and migrate secrets:
|
||||
|
||||
```bash
|
||||
# 1. Install Vault in a container
|
||||
botserver install vault --container --tenant pragmatismo
|
||||
|
||||
# 2. Install Vector DB for embeddings
|
||||
botserver install vector_db --container --tenant pragmatismo
|
||||
|
||||
# 3. Get Vault container IP
|
||||
lxc list pragmatismo-vault
|
||||
|
||||
# 4. Set environment variables
|
||||
export VAULT_ADDR=http://<vault-ip>:8200
|
||||
export VAULT_TOKEN=<root-token-from-init>
|
||||
|
||||
# 5. Migrate existing secrets
|
||||
botserver vault migrate /opt/gbo/bin/system/.env
|
||||
|
||||
# 6. Verify migration
|
||||
botserver vault health
|
||||
botserver vault get gbo/tables
|
||||
botserver vault get gbo/drive
|
||||
botserver vault get gbo/email
|
||||
|
||||
# 7. Update .env to use Vault only
|
||||
cat > /opt/gbo/bin/system/.env << EOF
|
||||
RUST_LOG=info
|
||||
VAULT_ADDR=http://<vault-ip>:8200
|
||||
VAULT_TOKEN=<root-token>
|
||||
SERVER_HOST=0.0.0.0
|
||||
SERVER_PORT=5858
|
||||
EOF
|
||||
|
||||
# 8. Restart botserver
|
||||
botserver restart
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Secret Paths Reference
|
||||
|
||||
### gbo/tables
|
||||
|
||||
Database connection credentials.
|
||||
|
||||
| Key | Description |
|
||||
|-----|-------------|
|
||||
| `host` | Database server hostname |
|
||||
| `port` | Database port |
|
||||
| `database` | Database name |
|
||||
| `username` | Database user |
|
||||
| `password` | Database password |
|
||||
|
||||
### gbo/drive
|
||||
|
||||
S3/MinIO storage credentials.
|
||||
|
||||
| Key | Description |
|
||||
|-----|-------------|
|
||||
| `server` | Storage server hostname |
|
||||
| `port` | Storage port |
|
||||
| `use_ssl` | Enable SSL (`true`/`false`) |
|
||||
| `accesskey` | Access key ID |
|
||||
| `secret` | Secret access key |
|
||||
| `org_prefix` | Organization prefix for buckets |
|
||||
|
||||
### gbo/email
|
||||
|
||||
SMTP email configuration.
|
||||
|
||||
| Key | Description |
|
||||
|-----|-------------|
|
||||
| `from` | Sender email address |
|
||||
| `server` | SMTP server hostname |
|
||||
| `port` | SMTP port |
|
||||
| `username` | SMTP username |
|
||||
| `password` | SMTP password |
|
||||
| `reject_unauthorized` | Reject invalid certs |
|
||||
|
||||
### gbo/llm
|
||||
|
||||
AI/LLM configuration.
|
||||
|
||||
| Key | Description |
|
||||
|-----|-------------|
|
||||
| `api_key` | API key for cloud LLM |
|
||||
| `model` | Model identifier |
|
||||
| `endpoint` | API endpoint URL |
|
||||
| `local` | Use local LLM (`true`/`false`) |
|
||||
| `url` | Local LLM server URL |
|
||||
| `model_path` | Path to local model file |
|
||||
| `embedding_model_path` | Path to embedding model |
|
||||
| `embedding_url` | Embedding server URL |
|
||||
|
||||
### gbo/stripe
|
||||
|
||||
Payment processing credentials.
|
||||
|
||||
| Key | Description |
|
||||
|-----|-------------|
|
||||
| `secret_key` | Stripe secret key |
|
||||
| `professional_plan_price_id` | Professional plan price ID |
|
||||
| `personal_plan_price_id` | Personal plan price ID |
|
||||
|
||||
### gbo/cache
|
||||
|
||||
Redis/Valkey credentials.
|
||||
|
||||
| Key | Description |
|
||||
|-----|-------------|
|
||||
| `password` | Cache password |
|
||||
|
||||
### gbo/directory
|
||||
|
||||
Zitadel identity provider.
|
||||
|
||||
| Key | Description |
|
||||
|-----|-------------|
|
||||
| `url` | Zitadel server URL |
|
||||
| `project_id` | Project ID |
|
||||
| `client_id` | OAuth client ID |
|
||||
| `client_secret` | OAuth client secret |
|
||||
| `masterkey` | Master encryption key |
|
||||
|
||||
### gbo/encryption
|
||||
|
||||
Encryption keys.
|
||||
|
||||
| Key | Description |
|
||||
|-----|-------------|
|
||||
| `master_key` | Master encryption key |
|
||||
|
||||
---
|
||||
|
||||
## Troubleshooting
|
||||
|
||||
### Vault Connection Issues
|
||||
|
||||
```bash
|
||||
# Check if Vault is running
|
||||
lxc exec pragmatismo-vault -- systemctl status vault
|
||||
|
||||
# Check Vault seal status
|
||||
lxc exec pragmatismo-vault -- vault status
|
||||
|
||||
# Unseal Vault if sealed
|
||||
lxc exec pragmatismo-vault -- vault operator unseal <unseal-key>
|
||||
```
|
||||
|
||||
### Component Installation Fails
|
||||
|
||||
```bash
|
||||
# Check logs
|
||||
tail -f botserver-stack/logs/<component>.log
|
||||
|
||||
# Verify container exists
|
||||
lxc list | grep <tenant>-<component>
|
||||
|
||||
# Check container logs
|
||||
lxc exec <tenant>-<component> -- journalctl -xe
|
||||
```
|
||||
|
||||
### Missing Dependencies
|
||||
|
||||
```bash
|
||||
# Install system dependencies
|
||||
sudo apt-get install -y libpq-dev libssl-dev liblzma-dev
|
||||
```
|
||||
|
|
@ -404,6 +404,7 @@
|
|||
- [Console (XtreeUI)](./18-appendix-external-services/console.md)
|
||||
|
||||
- [Appendix C: Maintenance](./19-maintenance/README.md)
|
||||
- [CLI Reference](./19-maintenance/cli-reference.md)
|
||||
- [Updating Components](./19-maintenance/updating-components.md)
|
||||
- [Component Reference](./19-maintenance/component-reference.md)
|
||||
- [Security Auditing](./19-maintenance/security-auditing.md)
|
||||
|
|
|
|||
Loading…
Add table
Reference in a new issue