Rodrigo Rodriguez (Pragmatismo) 1b269f567f Add version command docs and security best practices

2025-12-18 11:06:29 -03:00

11 KiB

Raw Blame History

CLI Reference

botserver provides a command-line interface for managing components, secrets, and services.

General Usage

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
`version`	Show version information

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
`--version`, `-v`	Show version

Component Management

Install a Component

botserver install <component> [--container] [--tenant <name>]

Examples:

# 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

botserver remove <component> [--container] [--tenant <name>]

List Components

botserver list [--container] [--tenant <name>]

Shows all available components and their installation status.

Check Status

botserver status <component> [--container] [--tenant <name>]

Service Control

Start Services

botserver start [--container] [--tenant <name>]

Starts all installed components.

Stop Services

botserver stop

Stops all running components.

Restart Services

botserver restart [--container] [--tenant <name>]

Vault Commands

The vault subcommand manages secrets stored in HashiCorp Vault.

Prerequisites

⚠️ SECURITY WARNING: Never expose VAULT_TOKEN in shell history or scripts. Use a secrets file with restricted permissions (600) or environment injection.

Vault commands require these environment variables:

# Secure method: use a file with restricted permissions
echo "VAULT_TOKEN=<your-vault-token>" > ~/.vault-token
chmod 600 ~/.vault-token
source ~/.vault-token

export VAULT_ADDR=http://<vault-ip>:8200

Migrate Secrets from .env

Migrates secrets from an existing .env file to Vault.

botserver vault migrate [env_file]

Arguments:

Argument	Description	Default
`env_file`	Path to .env file	`.env`

Example:

# 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:

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.

botserver vault put <path> <key=value> [key=value...]

Examples:

# 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.

botserver vault get <path> [key]

Examples:

# 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.

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.

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

Version Information

Show botserver version and component status.

botserver version [--all]

Options:

Option	Description
`--all`	Show detailed info: build, components, Vault status

Examples:

# Simple version
botserver version
# Output: botserver 6.1.0

# Detailed version with all components
botserver version --all

Output with --all:

botserver 6.1.0

Build Information:
  rustc: rustc 1.83.0 (90b35a623 2024-11-26)
  target: x86_64
  os: linux

Installed Components:
  * vault (installed)
  * tables (installed)
  * cache (installed)

Available Components: 15

Secrets:
  Vault: connected

Complete Setup Example

Here's a complete workflow to set up Vault and migrate secrets:

# 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 (SECURE METHOD)
cat > /opt/gbo/bin/system/.env << EOF
RUST_LOG=info
VAULT_ADDR=http://<vault-ip>:8200
SERVER_HOST=0.0.0.0
SERVER_PORT=5858
EOF

# Store token separately with restricted permissions
echo "VAULT_TOKEN=<root-token>" > /opt/gbo/secrets/vault-token
chmod 600 /opt/gbo/secrets/vault-token
chown root:root /opt/gbo/secrets/vault-token

# 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

# 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

# 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

# Install system dependencies
sudo apt-get install -y libpq-dev libssl-dev liblzma-dev

Security Best Practices

🔒 SECURITY NOTES

Token Management

NEVER commit tokens or secrets to version control
NEVER pass tokens as command-line arguments (visible in ps)
ALWAYS use environment variables or secure files with chmod 600
ROTATE Vault tokens regularly (recommended: every 30 days)

File Permissions

# Secure your secrets directory
chmod 700 /opt/gbo/secrets
chmod 600 /opt/gbo/secrets/*
chown -R root:root /opt/gbo/secrets

Vault Hardening

# Enable audit logging
botserver vault put gbo/audit enabled=true

# Use short-lived tokens in production
# Configure token TTL in Vault policies

Network Security

Run Vault behind a firewall
Use TLS for Vault connections in production
Restrict Vault access to specific container IPs

# Example: Only allow botserver container to reach Vault
iptables -A INPUT -p tcp --dport 8200 -s 10.16.164.33 -j ACCEPT
iptables -A INPUT -p tcp --dport 8200 -j DROP

11 KiB Raw Blame History

CLI Reference

General Usage

Commands Overview

Global Options

Component Management

Install a Component

Remove a Component

List Components

Check Status

Service Control

Start Services

Stop Services

Restart Services

Vault Commands

Prerequisites

Migrate Secrets from .env

Store Secrets

Retrieve Secrets

List Secret Paths

Health Check

Version Information

Complete Setup Example

Secret Paths Reference

gbo/tables

gbo/drive

gbo/email

gbo/llm

gbo/stripe

gbo/cache

gbo/directory

gbo/encryption

Troubleshooting

Vault Connection Issues

Component Installation Fails

Missing Dependencies

Security Best Practices

Token Management

File Permissions

Vault Hardening

Network Security

11 KiB

Raw Blame History