Jamie/Homelab
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
a3f6855f32530b4aa6af2cc31706372dfc41b64d
Homelab/README.md
Jamie Miller a3f6855f32 Docs: update Discord agent configuration and fix syntax issues 
- Update AGENTS.md with current Discord agent configuration
  - Add discord-agent service details
  - Update storage structure to include discord-agent directory
- Update README.md Discord agent integration section
  - Correct LLM configuration from OpenCode to Ollama
  - Update environment variables and configuration details
  - Fix storage structure documentation
- Update RESTORE.md Discord agent restoration steps
  - Correct service configuration for Ollama integration
  - Add proper troubleshooting steps
  - Update environment variable documentation
- Fix docker-compose.yaml Discord agent environment variables
  - Add DISCORD_BOT_TOKEN, OLLAMA_ENDPOINT, OLLAMA_MODEL
  - Correct database and network configuration
- Add AGENTS.md to .gitignore tracked files
- Remove old discord agent versions and test files
- Create working discord_agent.py and health_check.py
2026-02-06 04:34:43 +00:00

330 lines
8.9 KiB
Markdown
Raw Blame History

# Docker Compose Infrastructure Documentation
## Overview
This infrastructure manages a comprehensive self-hosted environment including media management (Jellyfin, *arr stack), document management (Paperless-ngx), AI services (Open WebUI, LiteLLM), photo management (Immich), genealogy tools (GrampsWeb), and various utilities.
## Architecture
### Internal Docker Services
| Service Categories | Service | Role / Component | Web UI Port |
|---|---|---|---|
| Media & Arr Stack | Jellyfin | Media server with hardware transcoding | 8096 |
| Media & Arr Stack | Jellyseerr | Media request management | 5055 |
| Media & Arr Stack | Radarr | Movie management | 7878 |
| Media & Arr Stack | Sonarr | TV show management | 8989 |
| Media & Arr Stack | Lidarr | Music management | 8686 |
| Media & Arr Stack | Bazarr | Subtitle management | 6767 |
| Media & Arr Stack | Prowlarr | Indexer manager | 9696 |
| Media & Arr Stack | qBittorrent | Download client | 7070 |
| Data Management | Paperless | Document management interface | 8100 |
| Data Management | Stirling-PDF | PDF manipulation tools | 8090 |
| Data Management | OnlyOffice | Document collaboration server | 8091 |
| Local AI | Open WebUI | LLM interface | 3000 |
| Data Management | Immich | Photo management | 2283 |
| Data Management | Syncthing | File synchronization | 8384 |
| Management & Infrastructure | Gitea | Git service | 8418 |
| Data Management | GrampsWeb Jamie | Genealogy UI | 5511 |
| Data Management | GrampsWeb Helen | Genealogy UI | 5512 |
| Data Management | Speedtest Tracker | Network performance | 8180 |
| Management & Infrastructure | NPM Admin | NPM admin UI | 81 |
| Data Management | Maloja | Music scrobbling | 42010 |
| Data Management | Multi-Scrobbler | Cross-platform scrobbler | 9078 |
| Data Management | WYGIWYH | Financial tracking | 9008 |
| Management & Infrastructure | Portainer | Container management UI | 9443 |
| Management & Infrastructure | Homepage | Service dashboard | 7575 |
### Discord Agent Integration
### Discord Bot Service
- **Service**: Discord Agent Bot
- **Role**: AI-powered Discord bot using Ollama LLM
- **Container**: `discord-agent`
- **Network**: `internal_net`, `db_net`
- **Web UI**: Discord (no direct web interface)
- **Configuration**: `/docker/discord-agent/config/agent-config.yaml`
- **Data**: `/docker/discord-agent/data/`
### Features
- **AI Integration**: Uses Ollama LLM (mistral-3:8b) at `http://192.168.0.31:11434`
- **Modular Architecture**: Cogs for service integrations
- **Database Support**: MySQL for conversation persistence
- **Caching**: Redis for improved performance (configurable)
- **Security**: Discord role-based permissions
- **Logging**: Configurable logging levels (default: INFO)
- **Rate Limiting**: Built-in rate limiting for API calls
### Available Commands
- `!agent` - Chat with the AI assistant
- `!status` - Check bot status and latency
- `!help` - Show available commands
- Service integration commands (configurable)
### Configuration
- **Main Config**: `config/agent-config.yaml` (YAML-based with env var substitution)
- **Discord Token**: Sourced from `DISCORD_BOT_TOKEN` environment variable
- **Ollama Config**: Model, endpoint, temperature, top_p, top_k parameters
- **Integrations**: Configurable service integrations in YAML
### Environment Variables
```
DISCORD_BOT_TOKEN=your_discord_bot_token_here
OLLAMA_ENDPOINT=http://192.168.0.31:11434
OLLAMA_MODEL=mistral-3:8b
TZ=Pacific/Auckland
```
### Bot Architecture
- **Main Bot**: `discord_agent.py` - Core Discord bot implementation
- **Base Cog**: `cogs/base_cog.py` - Base functionality and commands
- **Integration Cog**: `cogs/integration_cog.py` - Service integrations
- **Config**: YAML-based configuration with environment variable substitution
- **Database**: MySQL with asyncpg driver for conversation history
### Security
- Runs on internal networks only
- Discord role-based access control
- Configurable rate limiting to prevent abuse
- No direct database access from external networks
### Network Segmentation
- **media_net**: Media services and *arr applications
- **db_net**: Database services (internal only)
- **web_net**: Web-accessible services
- **internal_net**: Internal service communication
## Storage Structure
### Local Docker Configs (`/docker/`)
```
/docker/
├── Homepage/
├── Arrs/ (Prowlarr, Radarr, Sonarr, Lidarr, Bazarr, Jellyfin, Jellyseerr)
├── qBittorrent/
├── discord-agent/ (Discord bot with Ollama LLM)
├── paperless/
├── stirling/
├── immich/
├── syncthing/
├── gitea/
├── gramps-jamie/
├── gramps-helen/
├── speedtest-tracker/
├── rustdesk/
├── redbot/
├── maloja/
├── scrobble/
└── litellm/
```
### NAS Storage (`/mnt/Nas-Storage/data/`)
```
/mnt/Nas-Storage/data/
├── media/
│ ├── movies/
│ ├── tv/
│ ├── music/
│ └── images/
└── torrents/
└── soulsync/
```
## Prerequisites
### Required Environment Variables (.env file)
```
# System
PUID=1000
PGID=1000
TZ=Pacific/Auckland
# URLs
JELLYFIN_URL=https://your-jellyfin-domain.com
PAPERLESS_URL=https://your-paperless-domain.com
WYGIWYH_URL=https://your-wygiwyh-domain.com
HOMEPAGE_ALLOWED_HOSTS=your-homepage-domain.com
# Nginx Proxy Manager
NPM_PASSWORD=your_secure_password
# Paperless
PAPERLESS_DB_ROOT_PASSWORD=your_secure_password
PAPERLESS_DB_NAME=paperless
PAPERLESS_DB_USER=paperless
PAPERLESS_DB_PASSWORD=your_secure_password
PAPERLESS_SECRET_KEY=your_secret_key
# Immich
IMMICH_POSTGRES_PASSWORD=your_secure_password
# LiteLLM
GROQ_API_KEY=your_groq_api_key
LITELLM_MASTER_KEY=your_master_key
# Slskd
SLSKD_USERNAME=your_username
SLSKD_PASSWORD=your_secure_password
# Speedtest Tracker
SPEEDTEST_DB_NAME=speedtest
SPEEDTEST_DB_USER=speedtest
SPEEDTEST_DB_PASSWORD=your_secure_password
SPEEDTEST_APP_KEY=base64:your_generated_key
# WYGIWYH
WYGIWYH_DB_DATABASE=wygiwyh
WYGIWYH_DB_USER=wygiwyh
WYGIWYH_DB_PASSWORD=your_secure_password
WYGIWYH_SECRET_KEY=your_secret_key
WYGIWYH_ALLOWED_HOSTS=localhost,127.0.0.1,your-domain.com
# RedBot
REDBOT_TOKEN=your_discord_bot_token
```
### System Requirements
- Docker Engine 20.10+
- Docker Compose V2
- Sufficient storage for media and databases
- Intel GPU for Jellyfin hardware transcoding (optional)
## Installation
1. Clone/Download this repository
2. Create required directories
```bash
# See directory_structure.sh for automated setup
chmod +x directory_structure.sh
./directory_structure.sh
```
3. Create .env file
```bash
cp .env.example .env
# Edit .env with your values
nano .env
```
4. Set correct permissions
```bash
sudo chown -R $PUID:$PGID /docker
sudo chown -R $PUID:$PGID /mnt/Nas-Storage/data
```
5. Start services
```bash
docker compose up -d
```
## Maintenance
### Backup Strategy
**Critical Data to Backup:**
- `/docker/` - All service configurations
- Database volumes (see docker-compose.yaml)
- `.env` file (store securely, contains secrets)
**Optional (can be regenerated):**
- Media files on NAS
### Updates
Watchtower automatically updates containers daily. To manually update:
```
docker compose pull
docker compose up -d
```
### Logs
View logs for any service:
```
docker compose logs -f [service_name]
```
### Resource Limits
- Portainer: 512MB RAM limit
- Log rotation: 10MB max, 3 files
## Hardware Acceleration
Jellyfin is configured for Intel GPU transcoding:
- Device: `/dev/dri/renderD128`
- Group: `104` (render group)
Verify GPU access:
```
ls -l /dev/dri/renderD128
```
## Security Considerations
1. Secrets Management: Store `.env` securely, never commit to version control
2. Network Segmentation: Database network is internal-only
3. Container Security: `no-new-privileges:true` on supported services
4. Reverse Proxy: Use NPM for SSL termination and authentication
5. Updates: Watchtower keeps containers updated
## Troubleshooting
### Service won't start
```
docker compose logs [service_name]
docker compose restart [service_name]
```
### Database connection issues
```
# Check database is healthy
docker compose ps
# Verify network connectivity
docker compose exec [service] ping [db_service]
```
### Permission errors
```
# Verify ownership
ls -la /docker/[service]/
# Fix if needed
sudo chown -R $PUID:$PGID /docker/[service]/
```
### Storage full
```
# Check Docker disk usage
docker system df
# Clean up unused resources
docker system prune -a
```
## Contributing Services
To add new services:
1. Add service definition to appropriate section
2. Assign to correct network(s)
3. Add volume mounts under `/docker/[service]/`
4. Update this README with service description
5. Add required environment variables to `.env.example`
## License
This is a personal infrastructure setup. Adapt as needed for your use case.
## Support
For issues with specific services, consult their official documentation:
- Jellyfin: https://jellyfin.org/docs/
- Paperless-ngx: https://docs.paperless-ngx.com/
- Immich: https://immich.app/docs/
- And so on...
---
**Last Updated**: January 2026
Reference in New Issue View Git Blame Copy Permalink