docs: rewrite README with structured overview and quick start guide
Replaces the minimal project description with a comprehensive README including a component overview table, quick start instructions, common Ansible operations, and links to detailed documentation. Aligns with Red Panda Approval™ standards.
This commit is contained in:
184
docs/lobechat.md
Normal file
184
docs/lobechat.md
Normal file
@@ -0,0 +1,184 @@
|
||||
# LobeChat
|
||||
|
||||
Modern AI chat interface with multi-LLM support, deployed on **Rosalind** with PostgreSQL backend and S3 storage.
|
||||
|
||||
**Host:** rosalind.incus
|
||||
**Port:** 22081
|
||||
**External URL:** https://lobechat.ouranos.helu.ca/
|
||||
|
||||
## Quick Deployment
|
||||
|
||||
```bash
|
||||
cd ansible
|
||||
ansible-playbook lobechat/deploy.yml
|
||||
```
|
||||
|
||||
## Architecture
|
||||
|
||||
```
|
||||
┌──────────┐ ┌────────────┐ ┌──────────┐ ┌───────────┐
|
||||
│ Client │─────▶│ HAProxy │─────▶│ LobeChat │─────▶│PostgreSQL │
|
||||
│ │ │ (Titania) │ │(Rosalind)│ │ (Portia) │
|
||||
└──────────┘ └────────────┘ └──────────┘ └───────────┘
|
||||
│
|
||||
├─────────▶ Casdoor (SSO)
|
||||
├─────────▶ S3 (File Storage)
|
||||
├─────────▶ SearXNG (Search)
|
||||
└─────────▶ AI APIs
|
||||
```
|
||||
|
||||
## Required Vault Secrets
|
||||
|
||||
Add secrets to `ansible/inventory/group_vars/all/vault.yml`:
|
||||
|
||||
### 1. Key Vaults Secret (Encryption Key)
|
||||
|
||||
```yaml
|
||||
vault_lobechat_key_vaults_secret: "your-generated-secret"
|
||||
```
|
||||
|
||||
**Purpose:** Encrypts sensitive data (API keys, credentials) stored in the database.
|
||||
|
||||
**Generate with:**
|
||||
```bash
|
||||
openssl rand -base64 32
|
||||
```
|
||||
|
||||
ℹ️ This secret must be at least 32 bytes (base64 encoded). If changed after deployment, previously stored encrypted data will become unreadable.
|
||||
|
||||
### 2. NextAuth Secret
|
||||
|
||||
```yaml
|
||||
vault_lobechat_next_auth_secret: "your-generated-secret"
|
||||
```
|
||||
|
||||
**Purpose:** Signs NextAuth.js JWT tokens for session management.
|
||||
|
||||
**Generate with:**
|
||||
```bash
|
||||
openssl rand -base64 32
|
||||
```
|
||||
|
||||
### 3. Database Password
|
||||
|
||||
```yaml
|
||||
vault_lobechat_db_password: "your-secure-password"
|
||||
```
|
||||
|
||||
**Purpose:** PostgreSQL authentication for the `lobechat` database user.
|
||||
|
||||
### 4. S3 Secret Key
|
||||
|
||||
```yaml
|
||||
vault_lobechat_s3_secret_key: "your-s3-secret-key"
|
||||
```
|
||||
|
||||
**Purpose:** Authentication for S3 file storage bucket.
|
||||
|
||||
**Get from Terraform:**
|
||||
```bash
|
||||
cd terraform
|
||||
terraform output -json lobechat_s3_credentials
|
||||
```
|
||||
|
||||
### 5. AI Provider API Keys (Optional)
|
||||
|
||||
```yaml
|
||||
vault_lobechat_openai_api_key: "sk-proj-..."
|
||||
vault_lobechat_anthropic_api_key: "sk-ant-api03-..."
|
||||
vault_lobechat_google_api_key: "AIza..."
|
||||
```
|
||||
|
||||
**Purpose:** Server-side AI provider access. Users can also provide their own keys via the UI.
|
||||
|
||||
| Provider | Get Key From |
|
||||
|----------|-------------|
|
||||
| OpenAI | https://platform.openai.com/api-keys |
|
||||
| Anthropic | https://console.anthropic.com/ |
|
||||
| Google | https://aistudio.google.com/apikey |
|
||||
|
||||
### 6. AWS Bedrock Credentials (Optional)
|
||||
|
||||
```yaml
|
||||
vault_lobechat_aws_access_key_id: "AKIA..."
|
||||
vault_lobechat_aws_secret_access_key: "wJalr..."
|
||||
vault_lobechat_aws_region: "us-east-1"
|
||||
```
|
||||
|
||||
**Purpose:** Access AWS Bedrock models (Claude, Titan, Llama, etc.)
|
||||
|
||||
**Requirements:**
|
||||
- IAM user/role with `bedrock:InvokeModel` permission
|
||||
- Model access enabled in AWS Bedrock console for the region
|
||||
|
||||
## Host Variables
|
||||
|
||||
Defined in `ansible/inventory/host_vars/rosalind.incus.yml`:
|
||||
|
||||
| Variable | Description |
|
||||
|----------|-------------|
|
||||
| `lobechat_user` | Service user (lobechat) |
|
||||
| `lobechat_directory` | Service directory (/srv/lobechat) |
|
||||
| `lobechat_port` | Container port (22081) |
|
||||
| `lobechat_db_*` | PostgreSQL connection settings |
|
||||
| `lobechat_auth_casdoor_*` | Casdoor SSO configuration |
|
||||
| `lobechat_s3_*` | S3 storage settings |
|
||||
| `lobechat_syslog_port` | Alloy log collection port (51461) |
|
||||
|
||||
## Dependencies
|
||||
|
||||
| Service | Host | Purpose |
|
||||
|---------|------|---------|
|
||||
| PostgreSQL | Portia | Database backend |
|
||||
| Casdoor | Titania | SSO authentication |
|
||||
| HAProxy | Titania | HTTPS termination |
|
||||
| SearXNG | Oberon | Web search |
|
||||
| S3 Bucket | Incus | File storage |
|
||||
|
||||
## Ansible Files
|
||||
|
||||
| File | Purpose |
|
||||
|------|---------|
|
||||
| `lobechat/deploy.yml` | Main deployment playbook |
|
||||
| `lobechat/docker-compose.yml.j2` | Docker Compose template |
|
||||
|
||||
## Operations
|
||||
|
||||
### Check Status
|
||||
|
||||
```bash
|
||||
ssh rosalind.incus
|
||||
cd /srv/lobechat
|
||||
docker compose ps
|
||||
docker compose logs -f
|
||||
```
|
||||
|
||||
### Update Container
|
||||
|
||||
```bash
|
||||
ssh rosalind.incus
|
||||
cd /srv/lobechat
|
||||
docker compose pull
|
||||
docker compose up -d
|
||||
```
|
||||
|
||||
### Database Access
|
||||
|
||||
```bash
|
||||
psql -h portia.incus -U lobechat -d lobechat
|
||||
```
|
||||
|
||||
## Troubleshooting
|
||||
|
||||
| Issue | Resolution |
|
||||
|-------|------------|
|
||||
| Container won't start | Check vault secrets are defined |
|
||||
| Database connection failed | Verify PostgreSQL on Portia is running |
|
||||
| SSO redirect fails | Check Casdoor application config |
|
||||
| File uploads fail | Verify S3 credentials from Terraform |
|
||||
|
||||
## References
|
||||
|
||||
- [Detailed Service Documentation](services/lobechat.md)
|
||||
- [LobeChat Official Docs](https://lobehub.com/docs)
|
||||
- [GitHub Repository](https://github.com/lobehub/lobe-chat)
|
||||
Reference in New Issue
Block a user