Robert Helewka
b4d60f2f38
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.
185 lines
4.9 KiB
Markdown
185 lines
4.9 KiB
Markdown
# 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)
|