homelab/services/README.md

Docker Compose Services

This directory contains Docker Compose configurations for various services deployed in the homelab environment.

Migration Information

Migration Date: 2025-12-02 Source: GitLab instance at https://vulcan.apophisnetworking.net/jramos/homelab Target: Gitea instance at http://192.168.2.102:3060/jramos/homelab Migration Tool: Claude Code automated migration

All service configurations have been migrated from the legacy GitLab instance to this repository as part of the infrastructure consolidation effort.

Services Overview

ByteStash

Directory: bytestash/ Port: 5000 Description: Code snippet and text snippet management system with JWT-based authentication Image: ghcr.io/jordan-dalby/bytestash:latest Key Features:

• Snippet storage and organization
• User account management
• OIDC/SSO support (configurable)
• Debug mode available

Deployment:

cd bytestash
docker compose up -d

FileBrowser

Directory: filebrowser/ Port: 8095 Description: Web-based file browser providing file management through a web interface Image: filebrowser/filebrowser:latest Key Features:

• Full filesystem access (mounted at root /)
• User and group ID configuration
• SQLite database for settings
• Customizable via settings.json

Deployment:

cd filebrowser
docker compose up -d

Note: Review volume mounts before deployment - currently configured to mount entire filesystem.

GitLab Utilities

Directory: gitlab/ Description: Quality of Life (QoL) scripts and systemd configurations for GitLab management Contents:

• QoL Scripts/sync-npm-certs.sh: Script to sync Nginx Proxy Manager certificates
• QoL Config Files/sync-npm-certs.service: Systemd service unit
• QoL Config Files/sync-npm-certs.timer: Systemd timer for automated certificate sync

Purpose: Automates certificate synchronization between Nginx Proxy Manager and GitLab instance.

Paperless-ngx

Directory: paperless-ngx/ Port: 8000 URL: https://atlas.apophisnetworking.net Description: Document management system with OCR, full-text search, and automated organization Images:

• ghcr.io/paperless-ngx/paperless-ngx:latest (webserver)
• postgres:17 (database)
• redis:8 (message broker)
• gotenberg:8.20 (document conversion)
• apache/tika:latest (text extraction)

Key Features:

• OCR for scanned documents
• Automated document processing
• Tag and organization system
• PostgreSQL backend
• Redis task queue
• Tika integration for file parsing
• Gotenberg for document conversion

Deployment:

cd paperless-ngx
docker compose up -d

Environment Configuration: Check .env file or Portainer environment variables for production deployment.

Portainer

Directory: portainer/ Ports:

• 8000 (Edge agent)
• 9443 (Web UI - HTTPS)

Description: Docker container management platform with web UI Image: portainer/portainer-ce:latest Key Features:

• Docker container management
• Stack deployment
• Image registry management
• User access control
• Remote agent support

Deployment:

cd portainer
docker compose up -d

Note: Uses external volume portainer_data - ensure volume exists before deployment.

Speedtest Tracker

Directory: speedtest-tracker/ Ports:

• 8180 (HTTP)
• 8143 (HTTPS)

Description: Automated internet speed test tracker with historical data and public dashboard Image: lscr.io/linuxserver/speedtest-tracker:latest Key Features:

• Scheduled speed tests (cron: daily at midnight)
• SQLite database
• Public dashboard view
• Historical speed test data
• LinuxServer.io image with PUID/PGID support

Deployment:

cd speedtest-tracker
docker compose up -d

General Deployment Instructions

Prerequisites

• Docker Engine 20.10+
• Docker Compose v2.0+
• Sufficient disk space for volumes
• Network ports available (check port conflicts)

Standard Deployment Workflow

1. Review Configuration

   cd services/<service-name>
   cat docker-compose.yaml
   

2. Configure Environment Variables (if applicable)

   # Copy example env file if available
   cp .env.example .env
   # Edit with actual values
   nano .env
   

3. Create Required Directories

   # Ensure volume mount points exist
   # Example for bytestash:
   mkdir -p /home/jramos/docker/bytestash/data
   

4. Deploy Stack

   docker compose up -d
   

5. Verify Deployment

   docker compose ps
   docker compose logs -f
   

6. Configure Reverse Proxy (if using NPM)

   • Access Nginx Proxy Manager at http://192.168.2.101:81
   • Create proxy host pointing to service IP:PORT
   • Configure SSL certificate via Let's Encrypt
   • Set appropriate forwarding scheme (http/https)

Maintenance Commands

View Logs:

cd services/<service-name>
docker compose logs -f

Restart Service:

docker compose restart

Update Service:

docker compose pull
docker compose up -d

Stop Service:

docker compose down

Remove Service and Volumes (DESTRUCTIVE):

docker compose down -v

Directory Structure

services/
├── README.md                    # This file
├── bytestash/
│   ├── docker-compose.yaml
│   └── .gitkeep
├── filebrowser/
│   ├── docker-compose.yaml
│   └── .gitkeep
├── gitlab/
│   ├── QoL Config Files/
│   │   ├── sync-npm-certs.service
│   │   └── sync-npm-certs.timer
│   └── QoL Scripts/
│       └── sync-npm-certs.sh
├── paperless-ngx/
│   ├── docker-compose.yaml
│   └── .env
├── portainer/
│   ├── docker-compose.yaml
│   └── .gitkeep
└── speedtest-tracker/
    ├── docker-compose.yaml
    └── .gitkeep

Volume Mounts and Data Locations

Services use the following host paths for persistent data:

Service	Host Path	Purpose
ByteStash	/home/jramos/docker/bytestash/data	Snippet storage
FileBrowser	/home/docker/filebrowser/	Database and settings
Paperless-ngx	/home/jramos/paperless-ngx/consume	Document intake directory
Speedtest Tracker	/home/jramos/docker/speedtest-tracker/config	Configuration and database
Portainer	portainer_data (Docker volume)	Application data

Important: Ensure these directories exist with appropriate permissions before deploying services.

Network Configuration

All services are configured to use host networking or specific port mappings. If deploying behind Nginx Proxy Manager (CT 102 at 192.168.2.101):

1. Services should be accessible via internal IPs and ports
2. NPM handles external HTTPS access and SSL termination
3. Use http scheme in NPM when forwarding to backend services
4. Enable "Force SSL" in NPM for external HTTPS access

Security Considerations

Environment Files

• .env files are excluded from git via .gitignore
• Never commit credentials or API keys
• Use strong, unique passwords for database services
• Rotate JWT secrets and app keys regularly

Secrets in Docker Compose Files

Several services have embedded secrets in their docker-compose.yaml files:

• ByteStash: JWT_SECRET: your-secret (CHANGE THIS)
• Paperless-ngx: Database password paperless (CHANGE THIS)
• Speedtest Tracker: APP_KEY (already generated, but sensitive)

Action Required: Create .env files and move secrets out of docker-compose.yaml files.

Network Exposure

• Review port mappings before deployment
• Consider using Docker networks instead of host port binding
• Use NPM for external access with SSL
• Implement authentication on all services

Troubleshooting

Service Won't Start

1. Check logs: docker compose logs -f
2. Verify port availability: netstat -tulpn | grep <port>
3. Check volume permissions: ls -la /path/to/volume
4. Validate docker-compose.yaml syntax: docker compose config

Cannot Access Service Externally

1. Verify service is running: docker compose ps
2. Test local access: curl http://localhost:<port>
3. Check NPM proxy host configuration
4. Verify DNS resolution
5. Check firewall rules: iptables -L -n -v

Database Connection Errors (Paperless-ngx)

1. Verify PostgreSQL container is running
2. Check database credentials in environment variables
3. Ensure database initialization completed: docker compose logs db
4. Verify network connectivity between containers

Permission Denied Errors

1. Check PUID/PGID settings in docker-compose.yaml
2. Verify host directory ownership: chown -R <user>:<group> /path/to/volume
3. Check SELinux context (if applicable): ls -Z /path/to/volume

Migration Notes

Post-Migration Tasks

• Review all .env files and update with production values
• Change default passwords and secrets in docker-compose files
• Verify volume mount paths exist on target system
• Test each service deployment individually
• Configure NPM proxy hosts for external access
• Update DNS records if service URLs changed
• Backup existing service data before redeployment
• Document any service-specific configuration changes

Known Issues

• FileBrowser: Mounts entire filesystem root - review and restrict as needed
• Paperless-ngx: Contains .env file with secrets - ensure it's excluded from git
• GitLab Utilities: May require path adjustments depending on GitLab installation location

Contributing

When adding new services to this directory:

1. Create a new subdirectory with service name (lowercase, hyphenated)
2. Include docker-compose.yaml (or docker-compose.yml)
3. Add .env.example if service requires environment variables
4. Document service in this README under "Services Overview"
5. Update directory structure diagram
6. Test deployment from scratch before committing
7. Ensure .gitignore excludes sensitive files

Additional Resources

• Docker Compose Documentation
• Nginx Proxy Manager Docs
• Proxmox Homelab Documentation
• n8n Setup Guide

Support

For homelab-specific questions or issues:

• Check existing documentation in /home/jramos/homelab/
• Review CLAUDE_STATUS.md for current infrastructure state
• Consult service-specific documentation linked in each service section

---

Last Updated: 2025-12-02 Maintainer: jramos Repository: http://192.168.2.102:3060/jramos/homelab