Skip to content

Configuration#

traefik#

Traefik (pronounced traffic) is a modern HTTP reverse proxy and load balancer that makes deploying microservices easy.

It is the core of the entire homelab stack as it routes all incoming traffic to the correct service. It is the first service that you should start with:

Infrastructure Configuration#

Warning

You must set up your router, Google OAuth, CloudFlare, DuckDNS, and Traefik before you can start any other services. Setting up Traefik with everything requires a bit of time. See the instructions in the Traefik 🚦 section for more details.

Once you have all of the pre-requisites set up, you can use the core-up command to start just the Traefik services. See the Command Line documentation for more info.

All services are configured via a .env file at the root of the project and a few secret files in the secrets directory. These files are used to define settings and credentials for all services that are deployed. You can copy the example files to get started:

cp docs/example.env .env
cp -r docs/example-secrets/ secrets/
  • .env - Environment variables that are used by the docker-compose.yaml files
  • secrets/google_oauth.secret - The Google OAuth API credentials and user whitelist
  • secrets/cloudflare_api_key.secret - The CloudFlare API key (singular, plaintext key)
📄 .env 

################################################################################
# ENVIRONMENT SETUP
#
# * commented out lines are the default
################################################################################

DOMAIN_NAME="example.com"
ADMIN_USER="admin"

# Optional Secondary Domain
# SECONDARY_DOMAIN_NAME="example.dev"

TZ="America/Denver"
PUID="1000" # id -u
PGID="1000" # id -g

# UNIVERSAL_RESTART_POLICY="unless-stopped"

# Uncomment to test with Let's Encrypt (HTTPS) Staging Environment
# LETS_ENCRYPT_ENV="https://acme-staging-v02.api.letsencrypt.org/directory"

##################################################################
# DIRECTORY SETUP
#
# * You must customize these paths to match your own setup
# * For my personal setup, I have a NAS mounted at /media/storage
##################################################################

DOCKER_DIRECTORY="/path/to/this/repo"

COMPLETED_DOWNLOADS="/media/storage/downloads"
INCOMPLETE_DOWNLOADS="/downloads/incomplete"
MOVIE_DIR="/media/storage/movies"
TV_DIR="/media/storage/tv"
BOOKS_DIR="/media/storage/books"
# PLEX_TRANSCODE_DIR="/tmp"

##################################################################
# NETWORKING VARIABLES
#
# * You must customize these variables to match your own setup
# * These are the default values for my local network
##################################################################

PHYSICAL_SERVER_IP="192.168.1.55" # ip route get 1 | awk '{print $7}')
PHYSICAL_SERVER_NETWORK="192.168.1.0/24"

DUCKDNS_TOKEN=XXXXXX-XXX-XXXXX-XXXXX
DUCKDNS_SUBDOMAIN=example
CLOUDFLARE_EMAIL=[email protected]

##################################################################
# APP VARIABLES
##################################################################

### SHARED DATABASE (POSTGRES)
# POSTGRES_USER="postgres"
# POSTGRES_USER="postgres"
POSTGRES_PASSWORD="SharedDatabasePassword"
# POSTGRES_MULTIPLE_DATABASES="umami"

### TRANSMISSION (VPN + TORRENTS)
OPENVPN_PROVIDER=NORDVPN
OPENVPN_USERNAME=[email protected]
OPENVPN_PASSWORD=XXXXXXXXXXXXXX

### PLEX (CLAIM TOKEN)
PLEX_CLAIM=XXXXXXXXXXXXXX

### LLM (NEXT-WEB + SLACK BOT)
OPENAI_API_KEY="sk-XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX"
ANTHROPIC_API_KEY="sk-ant-XXXXXXXXXXXXXXXXXXXXXXXXXX"
SLACK_BOT_TOKEN=xoxb-XXXXXXXXXXX-XXXXXXXXXXX-XXXXXXXXXXX
SLACK_APP_TOKEN=xapp-1-XXXXXXXXXX-XXXXXXXXXX-XXXXXXXXXX
# SLACK_APP_LOG_LEVEL="INFO"

📄 secrets/google_oauth.secret 

providers.google.client-id=GoogleClientID
providers.google.client-secret=GoogleClientSecret
secret=RandomSecretString
whitelist=[email protected]
whitelist=[email protected]
whitelist=[email protected]

📄 secrets/cloudflare_api_key.secret 

xxxxxxxx-xxxxxxxxxxxxx-xxxxxxxxxx

App Deployment#

Which apps to deploy are defined in the docker-compose.yaml files. For example, To disable specific apps in the media profile, you would comment out the include directive in the root docker-compose.yaml file.

📄 docker-compose.yaml 

################################################################################
# HOMELAB
################################################################################

include:
    #############################################################################
    # TRAEFIK (CORE)
    #############################################################################

    - apps/traefik/docker-compose.yaml # Traefik (Reverse Proxy)
    - apps/duckdns.yaml # DuckDNS (Dynamic DNS)
    - apps/oauth.yaml # OAuth (Authentication)
    - apps/socket-proxy.yaml # Docker Socket Proxy (Security)

    #############################################################################
    # MEDIA
    #############################################################################

    - apps/heimdall.yaml # Heimdall (Landing Page)
    - apps/plex.yaml # Plex (Media Server)
    - apps/sonarr.yaml # Sonarr (TV Show Downloads)
    - apps/radarr.yaml # Radarr (Movie Downloads)
    - apps/prowlarr.yaml # Prowlarr (Indexer)
    - apps/overseerr.yaml # Overseerr (Media Requests)
    - apps/tautulli.yaml # Tautulli (Plex Analytics)
    - apps/transmission.yaml # Transmission (Torrents Behind VPN)
    - apps/sabnzbd.yaml # SABnzbd (Usenet Downloading)
    - apps/nzbhydra.yaml # NZBHydra2 (Usenet Browsing)
    # - apps/readarr.yaml # Readarr (Ebook Downloads)
    # - apps/calibre.yaml # Calibre (Books Management)
    # - apps/calibre-web.yaml # Calibre Web-UI

    #############################################################################
    # UTILITIES
    #############################################################################

    - apps/watchtower.yaml #  Watchtower (Container Updating)
    # - apps/postgres.yaml # PostgreSQL (Shared Database)
    # - apps/sftpgo.yaml # SFTPGo (File Management)
    # - apps/pihole.yaml # Pi-hole (DNS Ad-Blocking)
    # - apps/portainer.yaml # Portainer (Container Management)

    #############################################################################
    # MISCELLANEOUS
    #
    # * Note the existing services that are disabled by default.
    #############################################################################

    # - apps/chat-gpt-next-web.yaml # ChatGPT Next Web
    # - apps/chatgpt-in-slack.yaml # ChatGPT Slack Bot
    # - apps/libreoffice.yaml # LibreOffice (Office Suite)
    # - apps/umami.yaml # Umami Analytics
    # - apps/homeassistant/docker-compose.yaml # Home Assistant (Smart Home)
    # - apps/healthchecks.yaml # Healthchecks (Monitoring)

################################################################################
# NETWORK CONFIGURATION
################################################################################

networks:
    traefik:
        driver: bridge
        ipam:
            config:
                - subnet: 192.168.90.0/24
    docker:
        driver: bridge
        ipam:
            config:
                - subnet: 192.168.91.0/24
    internal:
        driver: bridge
        ipam:
            config:
                - subnet: 192.168.92.0/24

App Configuration#

Each app has its own configuration process - see the Applications documentation for more information about a specific app.

When connecting these applications together, it is important to note that they all share a common docker network. This means that when you're trying to connect to a service you can simply use a service name as the hostname. For example, if you're trying to connect to the sonarr service from the ombi service you can simply use http://sonarr:8989 as the hostname.