Docker-Compose Files for Homelab

This repository contains Docker-Compose files used to manage and orchestrate various services within my homelab environment. Each configuration is tailored for efficient deployment, management, and scaling of containerized applications. Feel free to explore, use, and modify these files to suit your own homelab needs. Contributions and suggestions are welcome!

Table of Contents

1. Introduction
2. Prerequisites
3. Usage
   • Cloning the Repository
   • Directory Structure
   • Starting Services
4. Secret Management
   • How It Works
   • Prerequisites
   • Initialising a New Machine
   • Adding a New Service .env
5. Available Services
6. Configuration
7. Contributing
8. License
9. Contact

Introduction

This repository aims to simplify the setup and management of containerized services in a homelab environment using Docker Compose. Each service is defined in a separate compose file, making it easy to start, stop, and configure as needed.

Prerequisites

Before using these Docker-Compose files, ensure you have the following installed:

• Docker
• Docker-Compose

Usage

Cloning the Repository

Clone the repository to your local machine using:

git clone https://github.com/andronics/homelab-docker-compose.git
cd homelab-docker-compose

Directory Structure

The repository is organized as follows:

homelab-docker-compose/
├── audiobookshelf/
│   └── .env
│   └── compose.yml
├── service2/
│   └── compose.yml
└── README.md

Starting Services

Navigate to the directory of the desired service. If available copy .env.sample to .env by executing:

$ cp '.env.sample' '.env'

$ docker compose up -d

This command starts the service in detached mode.

Secret Management

All .env files in this repository are encrypted at rest using a custom git-crypt implementation built on top of OpenSSL AES-256-CBC. Git's clean/smudge filter mechanism transparently encrypts files on git add and decrypts them on git checkout — no manual steps required once the key is in place.

How It Works

Working directory          Git object store
─────────────────          ────────────────
plaintext .env  ──clean──▶  encrypted blob  (what GitHub sees)
plaintext .env  ◀─smudge──  encrypted blob  (restored on checkout)

• clean — runs on git add; pipes the file through openssl enc -aes-256-cbc -pbkdf2 -salt before writing to the index.
• smudge — runs on git checkout; pipes the stored blob through openssl dec -aes-256-cbc -pbkdf2 to restore plaintext in the working tree.

The filter is wired up in .git/config:

[filter "git-crypt"]
    clean    = git-crypt clean
    smudge   = git-crypt smudge
    required = true

And applied to all *.env files via .gitattributes:

*.env filter=git-crypt diff=git-crypt

The encryption key is resolved in priority order:

1. GIT_CRYPT_KEY environment variable
2. pass show git/crypt-key (GPG-encrypted password store)

Secret Management Prerequisites

• pass with a GPG key configured, or the GIT_CRYPT_KEY environment variable set
• openssl (ships with most Linux distros and macOS)
• The git-crypt script installed to your $PATH

Initialising a New Machine

1. Install the git-crypt script:

# Place the script somewhere on your PATH, e.g.
cp git-crypt ~/.local/bin/git-crypt
chmod +x ~/.local/bin/git-crypt

2. Make the encryption key available:

# Option A — password store (recommended)
pass insert git/crypt-key   # paste the shared key when prompted

# Option B — environment variable
export GIT_CRYPT_KEY='<shared-key>'

3. Initialise the git filters in the cloned repo:

git-crypt init

This configures the clean/smudge filters in .git/config. Existing .env files will be decrypted automatically on the next git checkout or by running:

git checkout -- .

Adding a New Service .env

1. Create the .env file in the service directory.
2. Force-add it (.env is in .gitignore as a fallback safety net):

git add -f <service>/.env
git commit -m "feat(<service>): Add encrypted .env"

The clean filter encrypts the file before it ever touches the index. Verify the stored blob is ciphertext with:

git show HEAD:<service>/.env | xxd | head -3
# Should start with: 53 61 6c 74 65 64 5f 5f  (ASCII "Salted__")

Available Services

• Audiobookshelf: Audiobook & Podcast Server
• Authentik: Identity Provider & SSO Solution
• Baserow: No-Code Database Platform
• Bazarr: Subtitle Management for Sonarr & Radarr
• Booklore: Book Library Management
• Calibre: Powerful eBook Manager
• Checkmk: Infrastructure Monitoring
• Code: VS Code In The Browser
• Cross-seed: Torrent Cross-Seeding Automation
• Crowdsec: Curated Threat Intelligence Powered By The Crowd
• Emby: Media Server That Streams Audio & Video To Various Devices
• Error-pages: Custom Error Pages For Traefik
• Flaresolverr: Proxy Server To Bypass Cloudflare Protection
• Homer: Full Static HTML/JS Dashboard
• Immich: Photo & Video Management Solution
• Kavita: Multi Format Digital Library
• Lidarr: Music Collection Manager For Usenet And BitTorrent
• Metube: YouTube-DL Web Interface
• MQTT: Message Broker Service
• N8N: Workflow Automation Platform
• Navidrome: Your Music Collection From Anywhere
• NordVPN: VPN Container Network
• Nuclio: Serverless Functions Platform
• OpenWebUI: Web UI For LLM Interactions
• Portainer: Container Management
• Prowlarr: Indexer Manager & Proxy For *ARR PVR Apps
• qBittorrent: BitTorrent Client
• Radarr: Movie Collection Manager
• Readarr: Book Collection Manager
• Recyclarr: TRaSH Guides Sync For Sonarr & Radarr
• ROMM: ROM Library Manager
• Searxng: Privacy-Respecting Metasearch Engine
• Seedbox: Seedbox Management
• Sonarr: Television Collection Manager
• Tdarr: Distributed Transcoding System
• Termix: Terminal Service
• Tor: Overlay Network Enabling Anonymous Communication
• Traefik: Cloud Native Application Proxy
• Traktarr: Trakt Monitoring Daemon That Adds New TV Series & Movies
• TVmaze-sync: TV Show Tracking Sync
• Unpackerr: Monitors Downloads And Automatically Extracts Archives
• Whisparr: Adult Content Management

For detailed information on each service, refer to the respective compose.yml file and any accompanying documentation within the service directory.

Configuration

Each service directory contains a compose.yml file which can be customized to fit your needs. Common configurations include:

• Ports
• Environment variables
• Volumes

Modify these settings according to your specific requirements before starting the services.

Contributing

Contributions are welcome! If you have improvements or additional services to add, please fork the repository, create a new branch, and submit a pull request. Ensure your code adheres to the following guidelines:

• Follow the existing directory and file naming conventions.
• Test your changes before submitting.
• Provide a clear description of your changes in the pull request.

License

This project is licensed under the MIT License. See the LICENSE file for details.

Contact

For questions, suggestions, or feedback, please open an issue on GitHub or contact me at andronics@gmail.com.