docs: clarify container commands must run on host, add vault/vectordb examples
- Add warning that container create commands must run on HOST system - Add runtime dependencies section with install script reference - Add examples for creating vault and vectordb containers - Update troubleshooting with dependency installation instructions
This commit is contained in:
parent
da1b634eef
commit
83fdfa6226
3 changed files with 156 additions and 6 deletions
|
|
@ -2,6 +2,58 @@
|
|||
|
||||
botserver installs itself automatically through the bootstrap process. Just run the binary.
|
||||
|
||||
## Runtime Dependencies
|
||||
|
||||
Before running the botserver binary, you must install required system libraries on the **host system**.
|
||||
|
||||
### Quick Install (Recommended)
|
||||
|
||||
Download and run the dependency installer:
|
||||
|
||||
```bash
|
||||
curl -fsSL https://raw.githubusercontent.com/GeneralBots/botserver/main/scripts/install-dependencies.sh | sudo bash
|
||||
```
|
||||
|
||||
Or if you have the script locally:
|
||||
|
||||
```bash
|
||||
sudo ./scripts/install-dependencies.sh
|
||||
```
|
||||
|
||||
### Manual Install (Debian/Ubuntu)
|
||||
|
||||
```bash
|
||||
sudo apt update
|
||||
sudo apt install -y \
|
||||
libpq5 \
|
||||
libssl3 \
|
||||
liblzma5 \
|
||||
zlib1g \
|
||||
ca-certificates \
|
||||
curl \
|
||||
wget
|
||||
|
||||
# For container support (LXC)
|
||||
sudo snap install lxd
|
||||
sudo lxd init --auto
|
||||
```
|
||||
|
||||
### Manual Install (Fedora/RHEL)
|
||||
|
||||
```bash
|
||||
sudo dnf install -y \
|
||||
libpq \
|
||||
openssl-libs \
|
||||
xz-libs \
|
||||
zlib \
|
||||
ca-certificates \
|
||||
curl \
|
||||
wget \
|
||||
lxc
|
||||
```
|
||||
|
||||
> ⚠️ **Common Error**: If you see `error while loading shared libraries: libpq.so.5`, install `libpq5` (Debian/Ubuntu) or `libpq` (Fedora/RHEL).
|
||||
|
||||
## System Requirements
|
||||
|
||||
| Resource | Minimum | Production |
|
||||
|
|
@ -123,6 +175,19 @@ Requires CUDA installed and 12GB+ VRAM.
|
|||
| **Docker** | Production, microservices | [Docker Deployment](../chapter-07-gbapp/docker-deployment.md) |
|
||||
| **LXC** | Isolated components, Linux | [Container Deployment](../chapter-07-gbapp/containers.md) |
|
||||
|
||||
> ⚠️ **IMPORTANT**: Container create commands (`botserver install ... --container`) must be run from the **host system**, not inside a container.
|
||||
|
||||
### Example: Create Vault and VectorDB
|
||||
|
||||
```bash
|
||||
# Run on HOST system
|
||||
botserver install vault --container --tenant mycompany
|
||||
botserver install vector_db --container --tenant mycompany
|
||||
|
||||
# Verify containers
|
||||
lxc list | grep mycompany
|
||||
```
|
||||
|
||||
## Troubleshooting
|
||||
|
||||
| Issue | Solution |
|
||||
|
|
|
|||
|
|
@ -2,6 +2,8 @@
|
|||
|
||||
botserver uses LXC (Linux Containers) for isolated component deployment with system-level containerization.
|
||||
|
||||
> ⚠️ **IMPORTANT**: All container create and management commands must be run from the **host system**, not from inside a container. The botserver binary manages LXC containers from the host level.
|
||||
|
||||
## What is LXC?
|
||||
|
||||
- **System containers** - Full Linux userspace (lightweight VMs)
|
||||
|
|
@ -11,6 +13,8 @@ botserver uses LXC (Linux Containers) for isolated component deployment with sys
|
|||
|
||||
## Automatic Setup
|
||||
|
||||
Run on the **host system**:
|
||||
|
||||
```bash
|
||||
./botserver --container
|
||||
```
|
||||
|
|
@ -58,6 +62,8 @@ Data persists even if containers are deleted.
|
|||
|
||||
## Common Operations
|
||||
|
||||
Run these commands on the **host system**:
|
||||
|
||||
```bash
|
||||
# List containers
|
||||
lxc list
|
||||
|
|
@ -114,10 +120,35 @@ lxc restore default-tables backup-2024-01-15
|
|||
| Easy cleanup/reinstall | Simple deployment |
|
||||
| Security isolation | Direct service access |
|
||||
|
||||
## Example: Create Vault and VectorDB Containers
|
||||
|
||||
Run on the **host system**:
|
||||
|
||||
```bash
|
||||
# Install Vault for secrets management
|
||||
botserver install vault --container --tenant mycompany
|
||||
|
||||
# Install VectorDB (Qdrant) for embeddings
|
||||
botserver install vector_db --container --tenant mycompany
|
||||
|
||||
# Verify containers are running
|
||||
lxc list | grep mycompany
|
||||
|
||||
# Get container IPs
|
||||
lxc list mycompany-vault -c n4 --format csv
|
||||
lxc list mycompany-vectordb -c n4 --format csv
|
||||
|
||||
# Test services
|
||||
curl http://<vault-ip>:8200/v1/sys/health
|
||||
curl http://<vectordb-ip>:6333/health
|
||||
```
|
||||
|
||||
## Migration
|
||||
|
||||
### Local → Container
|
||||
|
||||
Run on the **host system**:
|
||||
|
||||
```bash
|
||||
pg_dump botserver > backup.sql
|
||||
./botserver --container
|
||||
|
|
@ -126,6 +157,8 @@ lxc exec default-tables -- psql -U gbuser botserver < backup.sql
|
|||
|
||||
### Container → Local
|
||||
|
||||
Run on the **host system**:
|
||||
|
||||
```bash
|
||||
lxc exec default-tables -- pg_dump -U gbuser botserver > backup.sql
|
||||
./botserver uninstall tables
|
||||
|
|
|
|||
|
|
@ -2,6 +2,8 @@
|
|||
|
||||
botserver provides a command-line interface for managing components, secrets, and services.
|
||||
|
||||
> ⚠️ **IMPORTANT**: All container create commands (`botserver install ... --container`) must be run from the **host system**, not from inside a container. The botserver binary manages LXC containers from the host level.
|
||||
|
||||
## General Usage
|
||||
|
||||
```bash
|
||||
|
|
@ -43,19 +45,52 @@ botserver <command> [options]
|
|||
botserver install <component> [--container] [--tenant <name>]
|
||||
```
|
||||
|
||||
> ⚠️ **Run from host**: Container install commands must be executed on the host machine, not inside any container.
|
||||
|
||||
**Examples:**
|
||||
|
||||
```bash
|
||||
# Install vault locally
|
||||
botserver install vault
|
||||
|
||||
# Install vault in an LXC container with tenant name
|
||||
# Install vault in an LXC container with tenant name (run on HOST)
|
||||
botserver install vault --container --tenant pragmatismo
|
||||
|
||||
# Install vector database
|
||||
# Install vector database (run on HOST)
|
||||
botserver install vector_db --container --tenant pragmatismo
|
||||
```
|
||||
|
||||
**Example: Create Vault and VectorDB containers**
|
||||
|
||||
This example shows how to create both Vault (secrets management) and VectorDB (Qdrant for embeddings) containers from scratch:
|
||||
|
||||
```bash
|
||||
# Run these commands on the HOST system, not inside a container
|
||||
|
||||
# Step 1: Install Vault container
|
||||
botserver install vault --container --tenant mycompany
|
||||
|
||||
# Step 2: Install VectorDB (Qdrant) container
|
||||
botserver install vector_db --container --tenant mycompany
|
||||
|
||||
# Step 3: Verify containers are running
|
||||
lxc list | grep mycompany
|
||||
|
||||
# Expected output:
|
||||
# | mycompany-vault | RUNNING | 10.x.x.x (eth0) | ... |
|
||||
# | mycompany-vectordb | RUNNING | 10.x.x.x (eth0) | ... |
|
||||
|
||||
# Step 4: Get container IPs for configuration
|
||||
lxc list mycompany-vault -c n4 --format csv
|
||||
lxc list mycompany-vectordb -c n4 --format csv
|
||||
|
||||
# Step 5: Test Vault health
|
||||
curl http://<vault-ip>:8200/v1/sys/health
|
||||
|
||||
# Step 6: Test VectorDB health
|
||||
curl http://<vectordb-ip>:6333/health
|
||||
```
|
||||
|
||||
**Available Components:**
|
||||
|
||||
| Component | Description |
|
||||
|
|
@ -463,13 +498,15 @@ botserver version --all
|
|||
|
||||
## Complete Setup Example
|
||||
|
||||
Here's a complete workflow to set up Vault and migrate secrets:
|
||||
Here's a complete workflow to set up Vault and migrate secrets.
|
||||
|
||||
> ⚠️ **Run all commands on the HOST system**, not inside any container.
|
||||
|
||||
```bash
|
||||
# 1. Install Vault in a container
|
||||
# 1. Install Vault in a container (run on HOST)
|
||||
botserver install vault --container --tenant pragmatismo
|
||||
|
||||
# 2. Install Vector DB for embeddings
|
||||
# 2. Install Vector DB for embeddings (run on HOST)
|
||||
botserver install vector_db --container --tenant pragmatismo
|
||||
|
||||
# 3. Get Vault container IP
|
||||
|
|
@ -632,8 +669,23 @@ lxc exec <tenant>-<component> -- journalctl -xe
|
|||
|
||||
### Missing Dependencies
|
||||
|
||||
If you see errors like `error while loading shared libraries: libpq.so.5`, install the runtime dependencies:
|
||||
|
||||
```bash
|
||||
# Install system dependencies
|
||||
# Quick install (recommended) - run on HOST system
|
||||
curl -fsSL https://raw.githubusercontent.com/GeneralBots/botserver/main/scripts/install-dependencies.sh | sudo bash
|
||||
|
||||
# Or manual install (Debian/Ubuntu)
|
||||
sudo apt-get install -y libpq5 libssl3 liblzma5 zlib1g ca-certificates curl wget
|
||||
|
||||
# Or manual install (Fedora/RHEL)
|
||||
sudo dnf install -y libpq openssl-libs xz-libs zlib ca-certificates curl wget
|
||||
```
|
||||
|
||||
For development/building from source:
|
||||
|
||||
```bash
|
||||
# Install development dependencies
|
||||
sudo apt-get install -y libpq-dev libssl-dev liblzma-dev
|
||||
```
|
||||
|
||||
|
|
|
|||
Loading…
Add table
Reference in a new issue