### Initial Setup Commands

Source: https://context7.com/juftin/homelab/llms.txt

Commands to copy example configuration files and initialize secrets. Ensure you edit the .env and secrets files with your specific values before proceeding.

```bash
# Copy example configuration files
cp docs/example.env .env
cp -r docs/example-secrets/ secrets/

# Edit .env — minimum required fields for the core profile:
#   DOMAIN_NAME       your registered domain (e.g. example.com)
#   DOCKER_DIRECTORY  absolute path to this repository
#   DUCKDNS_TOKEN     token from duckdns.org
#   DUCKDNS_SUBDOMAIN your duckdns subdomain
#   CLOUDFLARE_EMAIL  email for your Cloudflare account
#   PUID / PGID       output of `id -u` / `id -g`
#   TZ                timezone string, e.g. America/Denver

# Edit secrets/google_oauth.secret:
#   providers.google.client-id=GoogleClientID
#   providers.google.client-secret=GoogleClientSecret
#   secret=RandomSecretString
#   whitelist=you@gmail.com

# Edit secrets/cloudflare_api_key.secret:
#   <your cloudflare global API key, single line>

# Initialize the Let's Encrypt ACME certificate storage file (required once):
make config-acme
# Equivalent bash:
mkdir -p appdata/traefik/acme/ && \
  rm -f appdata/traefik/acme/acme.json && \
  touch appdata/traefik/acme/acme.json && \
  chmod 600 appdata/traefik/acme/acme.json

```

--------------------------------

### Start Services with Homelab CLI

Source: https://context7.com/juftin/homelab/llms.txt

Use `homelab up` to start services. You can start all services, a single service by specifying `APP=<service_name>`, or all services with pruning using `ARGS="--remove-orphans"`.

```bash
# Start all services (all profiles)
homelab up
```

```bash
# Start a single service
homelab up APP=sonarr
```

```bash
# Start all services and prune orphaned containers
homelab up ARGS="--remove-orphans"
```

```bash
# Equivalent raw Docker Compose
docker compose --profile all up -d
```

```bash
docker compose --profile all up -d sonarr
```

```bash
docker compose --profile all up -d --remove-orphans
```

--------------------------------

### Docker Compose Configuration Example

Source: https://github.com/juftin/homelab/blob/main/docs/config.md

This is an example of the root docker-compose.yaml file, used to define application deployments and includes.

```yaml
--8<-- "docker-compose.yaml"
```

--------------------------------

### Copy Example Configuration Files

Source: https://github.com/juftin/homelab/blob/main/README.md

Use these commands to copy the example .env and secrets files to your project root to begin configuration. Ensure you are in the project's root directory before executing.

```shell
cp docs/example.env .env
cp -r docs/example-secrets/ secrets/
```

--------------------------------

### Start Core Services

Source: https://github.com/juftin/homelab/blob/main/docs/cli.md

Starts only the core services, such as Traefik and OAuth2. Use the `--profile core` flag with docker compose.

```shell
homelab core-up
```

```shell
make core-up
```

```shell
docker compose --profile core up -d
```

```shell
homelab-compose --profile core up -d
```

--------------------------------

### Start Media Services

Source: https://github.com/juftin/homelab/blob/main/docs/cli.md

Starts only the media services, such as Plex, Sonarr, and Radarr. Use the `--profile media` flag with docker compose.

```shell
homelab media-up
```

```shell
make media-up
```

```shell
docker compose --profile media up -d
```

```shell
homelab-compose --profile media up -d
```

--------------------------------

### Prune orphaned containers with homelab up

Source: https://github.com/juftin/homelab/blob/main/docs/cli.md

Pass additional flags to `docker compose` using the `ARGS` flag. This example demonstrates pruning orphaned containers when starting services.

```shell
homelab up ARGS="--remove-orphans"
```

--------------------------------

### Start homelab services

Source: https://github.com/juftin/homelab/blob/main/docs/cli.md

Commands to start all homelab services. This can be performed using `homelab`, `make`, `docker compose`, or `homelab-compose`. The `-d` flag runs containers in detached mode.

```shell
homelab up
```

```shell
make up
```

```shell
docker compose --profile all up -d
```

```shell
homelab-compose --profile all up -d
```

--------------------------------

### Example .env File Content

Source: https://github.com/juftin/homelab/blob/main/docs/config.md

This is an example of the .env file used for environment variables in docker-compose.yaml files.

```dotenv
--8<-- "docs/example.env"
```

--------------------------------

### Start All Services with `make up`

Source: https://context7.com/juftin/homelab/llms.txt

Command to start all services in detached mode. You can optionally specify a single service using APP=<service> or pass additional Docker Compose arguments via ARGS=.

```bash
make up
# Equivalent with APP flag:
# APP=plex make up
# Equivalent with ARGS flag:
# ARGS="--remove-orphans" make up

```

--------------------------------

### Create Umami PostgreSQL Database

Source: https://github.com/juftin/homelab/blob/main/docs/applications/miscellaneous.md

This SQL snippet is required to set up the PostgreSQL database for Umami. Ensure the database and user are created before starting the Umami service.

```sql
CREATE USER umami WITH PASSWORD '$POSTGRES_PASSWORD';
CREATE DATABASE umami;
GRANT SET ON PARAMETER session_replication_role TO umami;
ALTER DATABASE umami OWNER TO umami;
```

--------------------------------

### Configure Traefik for a New Service

Source: https://github.com/juftin/homelab/blob/main/docs/traefik.md

These examples show how to configure Traefik within a docker-compose setup to make a new service accessible. It includes enabling Traefik for the application and defining routing rules, services, and middleware for authentication.

```yaml
--8<-- "apps/libreoffice.yaml"
```

```yaml
--8<-- "docker-compose.yaml"
```

--------------------------------

### Initialize ACME Certificate Storage for Traefik

Source: https://context7.com/juftin/homelab/llms.txt

Creates and secures the acme.json file for Traefik's Let's Encrypt certificates. Run this once before starting the core profile. To test with Let's Encrypt staging, uncomment LETS_ENCRYPT_ENV in .env.

```bash
homelab config-acme
```

```bash
# Equivalent bash
mkdir -p appdata/traefik/acme/ && \
  rm -f appdata/traefik/acme/acme.json && \
  touch appdata/traefik/acme/acme.json && \
  chmod 600 appdata/traefik/acme/acme.json
```

```bash
# To test with Let's Encrypt staging (avoid rate limits during setup),
uncomment in .env before running core-up:
# LETS_ENCRYPT_ENV="https://acme-staging-v02.api.letsencrypt.org/directory"
```

--------------------------------

### Example Cloudflare API Key Secret File

Source: https://github.com/juftin/homelab/blob/main/docs/config.md

This file stores the Cloudflare API key.

```plaintext
--8<-- "docs/example-secrets/cloudflare_api_key.secret"
```

--------------------------------

### Shell Alias Setup for Homelab

Source: https://context7.com/juftin/homelab/llms.txt

Configure 'homelab' and 'homelab-compose' aliases for convenient command-line access to Makefile targets and Docker Compose commands from any directory. Remember to reload your shell after adding these to your configuration file.

```bash
# Add to ~/.bashrc or ~/.zshrc

# 'homelab' wraps `make` targeting this repo
alias homelab="make --no-print-directory --directory /path/to/this/repo"

# 'homelab-compose' wraps `docker compose` pointing at this repo
alias homelab-compose="docker compose --project-directory /path/to/this/repo"

# Reload your shell
source ~/.bashrc

# Verify
homelab help
# Usage: homelab [target] (APP=service-name)
#
# Homelab 🐳
#   update              Update the service(s) *
#   pull                Pull the latest image(s)*
#   up                  Start the service(s)*
#   down                Stop the service(s)*
#   ...

```

--------------------------------

### Example Google OAuth Secret File

Source: https://github.com/juftin/homelab/blob/main/docs/config.md

This file contains Google OAuth API credentials and user whitelist information.

```plaintext
--8<-- "docs/example-secrets/google_oauth.secret"
```

--------------------------------

### Required .env Fields for Traefik

Source: https://github.com/juftin/homelab/blob/main/docs/traefik.md

After completing the setup, ensure these fields in your .env file are updated with your specific credentials and domain information.

```text
DUCKDNS_TOKEN=XXXXXX-XXX-XXXXX-XXXXX
DUCKDNS_SUBDOMAIN=example
CLOUDFLARE_EMAIL=example@gmail.com
```

--------------------------------

### Build Documentation

Source: https://github.com/juftin/homelab/blob/main/docs/cli.md

Builds the project documentation. The bash command uses `hatch run docs:serve` for live reloading.

```shell
homelab docs
```

```shell
make docs
```

```bash
hatch run docs:serve --livereload --dev-addr localhost:8000
```

--------------------------------

### Display help for homelab commands

Source: https://github.com/juftin/homelab/blob/main/docs/cli.md

Executes the `make help` command and pipes the output through `sed` to remove ANSI escape codes, providing a clean text-based help display.

```shell
make help | sed 's/[0-9;]*m//g'
```

--------------------------------

### PostgreSQL Multi-Database Initialization Script

Source: https://context7.com/juftin/homelab/llms.txt

An entrypoint script for PostgreSQL that creates databases and roles based on the POSTGRES_MULTIPLE_DATABASES environment variable. It runs idempotently on container startup.

```bash
# .env configuration for the postgres service
POSTGRES_PASSWORD="SharedDatabasePassword"
POSTGRES_MULTIPLE_DATABASES="umami,nextcloud,gitea"

# The script is mounted as a PostgreSQL init script.
# It runs on first container startup and creates:
#   - A role named <db> with POSTGRES_PASSWORD
#   - A database named <db> owned by that role
#   - GRANT SET ON PARAMETER session_replication_role TO <db>

# Example: manually invoke against a running postgres container
docker exec -e POSTGRES_USER=postgres \
            -e POSTGRES_PASSWORD=SharedDatabasePassword \
            -e POSTGRES_MULTIPLE_DATABASES=umami,gitea \
            postgres bash /docker-entrypoint-initdb.d/create-databases.sh

# Expected output:
# Multiple database creation requested: umami,gitea
#
# Creating 'umami' database
# Role 'umami' does not exist
# Database 'umami' does not exist
# Successful database creation 'umami'
#
# Creating 'gitea' database
# ...
# Multiple databases created
```

--------------------------------

### Show backup.sh help

Source: https://github.com/juftin/homelab/blob/main/docs/scripts.md

Displays the help message for the backup.sh script. This script can also be invoked via the CLI using `homelab backup`.

```bash
bash scripts/backup.sh --help
```

--------------------------------

### Deploy New Service

Source: https://context7.com/juftin/homelab/llms.txt

Command to bring up a specific application service after its configuration is added.

```bash
# Then bring it up
homelab up APP=myapp
```

--------------------------------

### Show Project Version

Source: https://github.com/juftin/homelab/blob/main/docs/cli.md

Displays the current version of the project. It fetches tags from git to determine the version.

```shell
homelab version
```

```shell
make version
```

```bash
git fetch --unshallow 2>/dev/null || true
git fetch --tags 2>/dev/null || true
echo "homelab $$(git describe --tags --abbrev=0)"
```

--------------------------------

### Show logs for homelab services

Source: https://github.com/juftin/homelab/blob/main/docs/cli.md

Commands to display logs for all homelab services. This can be done using `homelab`, `make`, `docker compose`, or `homelab-compose`. The `-ft` flags follow log output.

```shell
homelab logs
```

```shell
make logs
```

```shell
docker compose --profile all logs -ft
```

```shell
homelab-compose --profile all logs -ft
```

--------------------------------

### Show Help Message

Source: https://github.com/juftin/homelab/blob/main/docs/cli.md

Displays the help message for the homelab CLI and exits. Also available via make.

```shell
homelab help
```

```shell
make help
```

--------------------------------

### Show logs for a specific service

Source: https://github.com/juftin/homelab/blob/main/docs/cli.md

Use the `APP` flag with the `logs` command to view logs for a particular service. If `APP` is not specified, logs for all services are shown.

```shell
homelab logs APP=sonarr
```

--------------------------------

### Profile-Scoped Commands: Core Services

Source: https://context7.com/juftin/homelab/llms.txt

Manage the 'core' profile services (Traefik, OAuth, DuckDNS, socket-proxy) using dedicated commands like `homelab core-up`, `homelab core-down`, and `homelab core-logs`. Ensure the core profile is run first.

```bash
# Start core services only
homelab core-up
# make core-up
# docker compose --profile core up -d
```

```bash
# Stop core services only
homelab core-down
# docker compose --profile core down
```

```bash
# Tail core service logs
homelab core-logs
# docker compose --profile core logs -ft
```

```bash
# Verify Traefik dashboard is reachable (after DNS propagation)
curl -I https://traefik.example.com
# HTTP/2 200
```

--------------------------------

### Show Homelab Service Configuration

Source: https://github.com/juftin/homelab/blob/main/docs/cli.md

Displays the configuration for homelab services. Accepts the `APP` and `ARGS` flags.

```shell
homelab config
```

```shell
make config
```

```shell
docker compose --profile all config
```

```shell
homelab-compose --profile all config
```

--------------------------------

### Follow Service Logs with Homelab CLI

Source: https://context7.com/juftin/homelab/llms.txt

Use `homelab logs` to tail live logs for all or specific services with timestamps. You can specify a service with `APP=<service_name>` or pass extra arguments to Docker Compose logs using `ARGS="--tail=100"`.

```bash
# Follow all logs
homelab logs
```

```bash
# Follow logs for a specific service
homelab logs APP=traefik
```

```bash
# Pass extra arguments to docker compose logs
homelab logs APP=oauth ARGS="--tail=100"
```

```bash
# Equivalent raw Docker Compose
docker compose --profile all logs -ft
```

```bash
docker compose --profile all logs traefik -ft
```

--------------------------------

### Migrate appdata from 1.10.0 to 1.11.0

Source: https://github.com/juftin/homelab/blob/main/docs/migrations.md

Use this script to move media files and service configurations to the top level of the appdata directory during the 1.11.0 migration.

```shell
#!/usr/bin/env bash

sudo mv appdata/media/* appdata/
rm -r appdata/media

sudo mv appdata/core/* appdata/
rm -r appdata/core

sudo mv appdata/utilities/* appdata/
rm -r appdata/utilities

sudo mv appdata/miscellaneous/* appdata/
rm -r appdata/miscellaneous
```

--------------------------------

### Show logs for all services

Source: https://github.com/juftin/homelab/blob/main/docs/cli.md

Executes the `logs` command without the `APP` flag to display logs from all services managed by homelab.

```shell
homelab logs
```

--------------------------------

### Project Structure Overview

Source: https://context7.com/juftin/homelab/llms.txt

This text block outlines the directory structure of the homelab project, detailing the purpose of key files and directories like docker-compose.yaml, .env, Makefile, apps/, and appdata/.

```text
. 
├── docker-compose.yaml          # Root compose file — uses `include` to pull in all apps
├── .env                         # All environment variables and secrets references
├── Makefile                     # CLI wrapper (alias as `homelab`)
├── apps/                        # Per-service Docker Compose YAML files
│   ├── traefik/
│   │   ├── docker-compose.yaml  # Traefik reverse proxy service definition
│   │   └── rules/               # File-provider middleware and TLS rules
│   │       ├── middlewares.yml
│   │       ├── middlewares-chains.yml
│   │       └── tls-opts.yml
│   ├── oauth.yaml
│   ├── plex.yaml
│   ├── sonarr.yaml
│   ├── radarr.yaml
│   ├── litellm/
│   │   ├── docker-compose.yaml
│   │   ├── config.yaml
│   │   ├── bootstrap.sh
│   │   └── valkey.conf
│   └── ...
├── appdata/                     # Persistent volumes (one subdirectory per service)
├── scripts/
│   ├── backup.sh                # appdata tar.gz backup script
│   └── create-databases.sh     # PostgreSQL multi-database init script
└── docs/                        # MkDocs documentation source

```

--------------------------------

### Profile-Scoped Commands: Media Services

Source: https://context7.com/juftin/homelab/llms.txt

Manage the 'media' profile services (Plex, Sonarr, Radarr, etc.) using dedicated commands like `homelab media-up`, `homelab media-down`, and `homelab media-logs`. These commands are equivalent to their raw Docker Compose counterparts for the 'media' profile.

```bash
# Start media services only
homelab media-up
# docker compose --profile media up -d
```

```bash
# Stop media services only
homelab media-down
# docker compose --profile media down
```

```bash
# Tail media service logs
homelab media-logs
# docker compose --profile media logs -ft
```

--------------------------------

### Create and Set Permissions for acme.json

Source: https://github.com/juftin/homelab/blob/main/docs/traefik.md

Use this command to create the acme.json file and set the correct permissions. This is necessary for Traefik to generate SSL certificates.

```shell
mkdir -p appdata/traefik/acme/ && \
  rm -f appdata/traefik/acme/acme.json && \
  touch appdata/traefik/acme/acme.json && \
  chmod 600 appdata/traefik/acme/acme.json
```

--------------------------------

### Migrate config directories from 1.5.0 to 1.6.0

Source: https://github.com/juftin/homelab/blob/main/docs/migrations.md

This script moves service configuration directories to the top-level appdata directory during the 1.6.0 migration. New directories for traefik, media-center, and miscellaneous are created.

```shell
#!/usr/bin/env bash

mkdir -p appdata/traefik
mkdir -p appdata/media-center
mkdir -p appdata/miscellaneous

mv stacks/core/traefik/config appdata/traefik/traefik

mv stacks/media-center/calibre/config appdata/media-center/calibre
mv stacks/media-center/calibre-web/config appdata/media-center/calibre-web
mv stacks/media-center/heimdall/config appdata/media-center/heimdall
mv stacks/media-center/nzbget/config appdata/media-center/nzbget
mv stacks/media-center/ombi/config appdata/media-center/ombi
mv stacks/media-center/plex/config appdata/media-center/plex
mv stacks/media-center/prowlarr/config appdata/media-center/prowlarr
mv stacks/media-center/radarr/config appdata/media-center/radarr
mv stacks/media-center/readarr/config appdata/media-center/readarr
mv stacks/media-center/sftpgo/config appdata/media-center/sftpgo
mv stacks/media-center/sonarr/config appdata/media-center/sonarr
mv stacks/media-center/tautulli/config appdata/media-center/tautulli
mv stacks/media-center/transmission/config appdata/media-center/transmission

mv stacks/miscellaneous/pihole/config appdata/miscellaneous/pihole

sudo mv stacks/media-center/portainer/config appdata/media-center/portainer
```

--------------------------------

### Lint Code with Pre-commit

Source: https://github.com/juftin/homelab/blob/main/docs/cli.md

Lints the codebase using pre-commit hooks. The `pre-commit run --all-files` command ensures all files are checked.

```shell
homelab lint
```

```shell
make lint
```

```bash
pre-commit run --all-files
```

--------------------------------

### Migrate stacks from 1.8.0 to 1.9.0

Source: https://github.com/juftin/homelab/blob/main/docs/migrations.md

Run these commands to rename stacks and create a new utilities stack during the 1.9.0 migration. Ensure the stack is shut down before proceeding.

```shell
#!/usr/bin/env bash

mv appdata/media-center appdata/media
mv appdata/traefik appdata/core

mkdir -p appdata/utilities

mv appdata/miscellaneous/pihole/ appdata/utilities/
sudo mv appdata/media/portainer/ appdata/utilities/
mv appdata/media/sftpgo/ appdata/utilities/
```

--------------------------------

### Configure Plex Media Server

Source: https://context7.com/juftin/homelab/llms.txt

Plex configuration using host network mode for discovery and mounting media/transcoding directories. Requires a one-time claim token.

```yaml
# apps/plex.yaml
services:
    plex:
        image: lscr.io/linuxserver/plex:latest
        profiles: ["media", "all"]
        network_mode: host         # bypasses Traefik — access at http://<server-ip>:32400
        volumes:
            - ${DOCKER_DIRECTORY}/appdata/plex:/config
            - ${TV_DIR}:/tv
            - ${MOVIE_DIR}:/movies
            - ${TRANSCODE_DIR:-/dev/shm}:/transcode   # RAM transcoding
            - ${BOOKS_DIR}:/books
        devices:
            - /dev/dri:/dev/dri   # Intel/AMD hardware transcoding
            - /dev/dvb:/dev/dvb
        environment:
            PUID: ${PUID}
            PGID: ${PGID}
            TZ: ${TZ}
            VERSION: docker
            PLEX_CLAIM: ${PLEX_CLAIM}   # one-time claim token from plex.tv/claim
```

--------------------------------

### Show status of homelab services

Source: https://github.com/juftin/homelab/blob/main/docs/cli.md

Commands to display the status of all homelab services. This can be done using `homelab`, `make`, `docker compose`, or `homelab-compose`. The `docker compose` and `homelab-compose` commands format the output as a table.

```shell
homelab ps
```

```shell
make ps
```

```shell
docker compose --profile all ps --format "table {{.Image}}	{{.Status}}	{{.Ports}}	{{.Name}}"
```

```shell
homelab-compose --profile all ps --format "table {{.Image}}	{{.Status}}	{{.Ports}}	{{.Name}}"
```

--------------------------------

### Migrate stacks from 1.4.0 to 1.5.0

Source: https://github.com/juftin/homelab/blob/main/docs/migrations.md

Execute this script to move existing service directories into a new top-level 'stacks' directory during the 1.5.0 migration.

```shell
#!/usr/bin/env bash

mkdir -p stacks
mv traefik stacks/traefik
mv media-center stacks/media-center
mv miscellaneous stacks/miscellaneous
```

--------------------------------

### Show Core Services Logs

Source: https://github.com/juftin/homelab/blob/main/docs/cli.md

Displays logs for the core services, such as Traefik and OAuth2. Use the `--profile core` flag with docker compose and `-ft` for follow mode.

```shell
homelab core-logs
```

```shell
make core-logs
```

```shell
docker compose --profile core logs -ft
```

```shell
homelab-compose --profile core logs -ft
```

--------------------------------

### Show Media Services Logs

Source: https://github.com/juftin/homelab/blob/main/docs/cli.md

Displays logs for the media services, such as Plex, Sonarr, and Radarr. Use the `--profile media` flag with docker compose and `-ft` for follow mode.

```shell
homelab media-logs
```

```shell
make media-logs
```

```shell
docker compose --profile media logs -ft
```

```shell
homelab-compose --profile media logs -ft
```

--------------------------------

### Backup Application Data with Timestamp

Source: https://context7.com/juftin/homelab/llms.txt

Creates a timestamped tar.gz archive of application data. Specify the backup directory as an argument. Excludes acme.json and portainer data.

```bash
# Backup with timestamp
homelab backup BACKUP_DIR=/mnt/nas/backups
# Creates: /mnt/nas/backups/appdata_202401151430.tar.gz
```

```bash
# Backup without timestamp (overwrites previous backup)
homelab backup-no-timestamp BACKUP_DIR=/mnt/nas/backups
# Creates: /mnt/nas/backups/appdata.tar.gz
```

```bash
# Direct script usage
bash ./scripts/backup.sh appdata /mnt/nas/backups
bash ./scripts/backup.sh appdata /mnt/nas/backups --no-timestamp
```

```bash
# Expected output:
# Preparing backup... 🚀
# Source: /home/user/homelab/appdata 📂
# Target: /mnt/nas/backups/appdata_202401151430.tar.gz 📦
# Backup size: 2.3G ⚖️
# Backup successful ✅
```

--------------------------------

### Show Current Release Version

Source: https://context7.com/juftin/homelab/llms.txt

Displays the latest semantic-release git tag for the current deployment using the `homelab version` command. Includes an equivalent bash command for direct git operations.

```bash
homelab version
# homelab v1.11.0

# Equivalent bash
git fetch --unshallow 2>/dev/null || true
git fetch --tags 2>/dev/null || true
echo "homelab $(git describe --tags --abbrev=0)"
```

--------------------------------

### Inspect Resolved Configuration with Homelab CLI

Source: https://context7.com/juftin/homelab/llms.txt

Use `homelab config` to print the fully resolved Docker Compose configuration, with all environment variable substitutions applied. This can be used for all services or a specific service by specifying `APP=<service_name>`.

```bash
# Show config for all services
homelab config
```

```bash
# Show config for a specific service
homelab config APP=plex
```

```bash
# Equivalent raw Docker Compose
docker compose --profile all config
```

```bash
docker compose --profile all config plex
```

--------------------------------

### Initialize Traefik Acme Configuration

Source: https://github.com/juftin/homelab/blob/main/docs/cli.md

Initializes the `acme.json` file for Traefik. This involves creating the directory, removing any existing file, creating a new empty file, and setting appropriate permissions.

```shell
homelab config-acme
```

```shell
make config-acme
```

```bash
mkdir -p appdata/traefik/acme/ && \
rm -f appdata/traefik/acme/acme.json && \
touch appdata/traefik/acme/acme.json && \
chmod 600 appdata/traefik/acme/acme.json
```

--------------------------------

### Migrate config directories from 0.5.2 to 1.0.0

Source: https://github.com/juftin/homelab/blob/main/docs/migrations.md

This script handles unique migrations for Traefik, Portainer, and Pi-Hole, consolidating configuration files into dedicated 'config' subdirectories as required by the 1.0.0 release.

```shell
#!/usr/bin/env bash

######################################################################
# NOTE:
#
# Traefik, Portainer, and Pi-Hole have unique migrations compared to
# the other services:
# - Traefik - The configuration files are moved to the `traefik/config`
# - Portainer - sudo is required to move the portainer directory
# - Pi-Hole - The configuration files are moved to the `miscellaneous/pihole/config`
######################################################################

# portainer - media-center/portainer becomes media-center/portainer/config
mv media-center/portainer media-center/portainer_temp
mkdir -p media-center/portainer
sudo mv media-center/portainer_temp media-center/portainer/config

# pi-hole - config directories consolidated to miscellaneous/pi-hole/config
mkdir -p miscellaneous/pihole/config
mv miscellaneous/pihole/etc-pihole miscellaneous/pihole/config/pihole
mv miscellaneous/config/etc-dnsmasq.d miscellaneous/pihole/config/dnsmasq.d
rm -r miscellaneous/config/
```

--------------------------------

### Update Services with Homelab CLI

Source: https://context7.com/juftin/homelab/llms.txt

Use `homelab update` to pull the latest images and restart services. This can update all services, a single service by specifying `APP=<service_name>`, or services within a specific profile like `PROFILE=media`.

```bash
# Update all services
homelab update
```

```bash
# Update a single service
homelab update APP=radarr
```

```bash
# Equivalent raw Docker Compose steps
docker compose --profile all pull
docker compose --profile all up -d
```

```bash
# Update only the media profile services
homelab update PROFILE=media
```

--------------------------------

### Restart homelab services

Source: https://github.com/juftin/homelab/blob/main/docs/cli.md

Commands to restart all homelab services. This can be executed using `homelab`, `make`, `docker compose`, or `homelab-compose`.

```shell
homelab restart
```

```shell
make restart
```

```shell
docker compose --profile all restart
```

```shell
homelab-compose --profile all restart
```

--------------------------------

### Configure SABnzbd Host Whitelist

Source: https://github.com/juftin/homelab/blob/main/docs/applications/media.md

Modify the SABnzbd configuration file to allow access from specified hosts. Ensure the container is restarted after changes.

```text
host_whitelist = sabnzbd, sabnzbd.example.com
```

--------------------------------

### Alias for homelab command

Source: https://github.com/juftin/homelab/blob/main/docs/cli.md

Add this to your `.bashrc` or `.zshrc` to use the `homelab` command from anywhere. It wraps the `make` command with specific directory and no-print-directory flags.

```shell
alias homelab="make --no-print-directory --directory /path/to/this/repo"
```

--------------------------------

### Backup Appdata with Timestamp

Source: https://github.com/juftin/homelab/blob/main/docs/cli.md

Backs up the `appdata` directory, appending a timestamp to the archive name (e.g., `appdata_YYYYMMDDHHMM.tar.gz`). Requires the `BACKUP_DIR` variable to be set.

```shell
homelab backup BACKUP_DIR=/backup/dir
```

```shell
make backup BACKUP_DIR=/backup/dir
```

```bash
bash ./scripts/backup.sh appdata /backup/dir
```

--------------------------------

### Stop homelab services (alternative)

Source: https://github.com/juftin/homelab/blob/main/docs/cli.md

Commands to stop all homelab services using an alternative method. This can be performed using `homelab`, `make`, `docker compose`, or `homelab-compose`.

```shell
homelab stop
```

```shell
make stop
```

```shell
docker compose --profile all stop
```

```shell
homelab-compose --profile all stop
```

--------------------------------

### Configure Transmission with OpenVPN

Source: https://context7.com/juftin/homelab/llms.txt

Set up Transmission as a torrent client within an OpenVPN tunnel. Only traffic matching LOCAL_NETWORK bypasses the VPN for LAN access. Requires NET_ADMIN capability.

```yaml
# apps/transmission.yaml
services:
    transmission:
        image: haugene/transmission-openvpn:latest
        profiles: ["media", "all"]
        environment:
            OPENVPN_PROVIDER: ${OPENVPN_PROVIDER}   # e.g. NORDVPN
            OPENVPN_USERNAME: ${OPENVPN_USERNAME}
            OPENVPN_PASSWORD: ${OPENVPN_PASSWORD}
            TRANSMISSION_IDLE_SEEDING_LIMIT_ENABLED: "true"
            TRANSMISSION_IDLE_SEEDING_LIMIT: 0
            TRANSMISSION_DOWNLOAD_DIR: /downloads
            LOCAL_NETWORK: ${PHYSICAL_SERVER_NETWORK}  # e.g. 192.168.1.0/24
            NORDVPN_COUNTRY: US
            NORDVPN_CATEGORY: legacy_p2p
        cap_add:
            - NET_ADMIN
        devices:
            - /dev/net/tun
        labels:
            traefik.http.routers.transmission-rtr.rule: Host(`transmission.${DOMAIN_NAME}`)
            traefik.http.services.transmission-svc.loadbalancer.server.port: 9091
            traefik.http.routers.transmission-rtr.middlewares: chain-oauth-google@file
```

--------------------------------

### Restart Services with Homelab CLI

Source: https://context7.com/juftin/homelab/llms.txt

Use `homelab restart` to restart one or all services without rebuilding images. This command can restart all services or a single service by specifying `APP=<service_name>`.

```bash
# Restart all services
homelab restart
```

```bash
# Restart a single service
homelab restart APP=watchtower
```

```bash
# Equivalent raw Docker Compose
docker compose --profile all restart
```

```bash
docker compose --profile all restart watchtower
```

--------------------------------

### Homelab Project Structure

Source: https://github.com/juftin/homelab/blob/main/docs/index.md

This is a representation of the homelab project's directory structure, illustrating the organization of Docker Compose files, environment variables, secrets, and application data.

```text
.\ndocker-compose.yaml                     # Main Docker Compose File\n.env                                    # Environment Variables and Configuration\nMakefile                                # Makefile for common tasks and docker compose wrappers\nsecrets                                 # Secret Files\n  ├── cloudflare_api_key.secret           # Cloudflare API Key\n  └── google_oauth.secret                 # Google OAuth Credentials and Whitelist\napps                                    # Individual Service Docker Compose Files\n  ├── plex.yaml\n  ├── radarr.yaml\n  ├── ombi.yaml\n  ├── sonarr.yaml\n  ├── oauth.yaml\n  ├── chat-gpt-next-web.yaml\n  ├── watchtower.yaml\n  └── traefik                             # Traefik Reverse Proxy\n      ├── docker-compose.yaml             # Traefik Docker Compose File\n      └── rules                           # Traefik Middlewares and Rules\n          ├── middlewares-chains.yml\n          ├── middlewares.yml\n          └── tls-opts.yml\nappdata                                 # Application Data Persistent Volumes\n    ├── plex                                # Each individual service has its own subdirectory\n    ├── sonarr\n    ├── oauth\n    ├── traefik\n    ├── chat-gpt-next-web\n    ├── utilities\n    └── watchtower\n
```

--------------------------------

### Alias for homelab-compose command

Source: https://github.com/juftin/homelab/blob/main/docs/cli.md

Add this to your `.bashrc` or `.zshrc` to use the `docker compose` command with a specified project directory from anywhere.

```shell
alias homelab-compose="docker compose --project-directory /path/to/this/repo"
```

--------------------------------

### Show Container Status with Homelab CLI

Source: https://context7.com/juftin/homelab/llms.txt

Use `homelab ps` to display a formatted table of running containers, including image, status, ports, and name. The equivalent raw Docker Compose command provides similar output formatting.

```bash
homelab ps
```

```bash
# Equivalent raw Docker Compose
docker compose --profile all ps --format "table {{.Image}}\t{{.Status}}\t{{.Ports}}\t{{.Name}}"
```

```text
# Expected output (example):
# IMAGE                                      STATUS          PORTS                                   NAME
# library/traefik:v3.6                       Up 3 days       0.0.0.0:80->80/tcp, 0.0.0.0:443->443   traefik
# thomseddon/traefik-forward-auth:latest     Up 3 days                                               oauth
# lscr.io/linuxserver/plex:latest            Up 3 days                                               plex
# lscr.io/linuxserver/sonarr:latest          Up 3 days                                               sonarr
```

--------------------------------

### Add New Service with Traefik Labels

Source: https://context7.com/juftin/homelab/llms.txt

Define a new service in its own YAML file and reference it in docker-compose.yaml. Traefik labels configure routing and middleware.

```yaml
# apps/myapp.yaml  — template for a new Traefik-exposed service
services:
    myapp:
        container_name: myapp
        image: lscr.io/linuxserver/myapp:latest
        profiles: ["miscellaneous", "all"]   # choose appropriate profile
        environment:
            PUID: ${PUID}
            PGID: ${PGID}
            TZ: ${TZ}
        volumes:
            - ${DOCKER_DIRECTORY}/appdata/myapp:/config
        security_opt:
            - no-new-privileges:true
        restart: ${UNIVERSAL_RESTART_POLICY:-unless-stopped}
        networks:
            traefik:
        labels:
            traefik.enable: true
            # Router: matches requests for myapp.example.com
            traefik.http.routers.myapp-rtr.rule: Host(`myapp.${DOMAIN_NAME}`)
            traefik.http.routers.myapp-rtr.entrypoints: websecure
            traefik.http.routers.myapp-rtr.service: myapp-svc
            # Service: tells Traefik which internal port to forward to
            traefik.http.services.myapp-svc.loadbalancer.server.port: 8080
            # Middleware: require Google OAuth (or use chain-no-auth for public)
            traefik.http.routers.myapp-rtr.middlewares: chain-oauth-google@file
```

```yaml
# docker-compose.yaml — add the include reference
include:
    - apps/myapp.yaml   # uncomment or add here
```

--------------------------------

### Migrate Calibre-Web Configuration

Source: https://github.com/juftin/homelab/blob/main/docs/migrations.md

Renames the Calibre-Web directory and moves its contents into a new 'config' subdirectory. This process is typical for updating Calibre-Web or reorganizing its configuration files.

```bash
mv media-center/calibre-web media-center/calibre-web_temp
mkdir -p media-center/calibre-web
mv media-center/calibre-web_temp media-center/calibre-web/config
```

--------------------------------

### LiteLLM Docker Compose Configuration

Source: https://context7.com/juftin/homelab/llms.txt

Defines the LiteLLM service, its image, environment variables, command, healthcheck, and Traefik labels. Requires LITELLM_MASTER_KEY and LITELLM_SALT_KEY to be set.

```yaml
services:
    litellm:
        image: ghcr.io/berriai/litellm:main-stable
        profiles: ["llm", "all", "chat"]
        environment:
            DATABASE_URL: "postgresql://litellm:litellm@litellm-db:5432/litellm"
            LITELLM_MASTER_KEY: ${LITELLM_MASTER_KEY:?}    # required
            LITELLM_SALT_KEY: ${LITELLM_SALT_KEY:?}
            OPENAI_API_KEY: ${OPENAI_API_KEY:-}
            ANTHROPIC_API_KEY: ${ANTHROPIC_API_KEY:-}
            GEMINI_API_KEY: ${GEMINI_API_KEY:-}
            REDIS_HOST: litellm-redis
        command: ["--config=/app/config.yaml"]
        healthcheck:
            test: ["CMD-SHELL", "wget --no-verbose --tries=1 http://localhost:4001/health/liveliness || exit 1"]
        labels:
            traefik.http.routers.litellm-rtr.rule: Host(`litellm.${DOMAIN_NAME}`)
            traefik.http.services.litellm-svc.loadbalancer.server.port: 4000
            traefik.http.routers.litellm-rtr.middlewares: chain-rate-limit@file  # no OAuth

    litellm-db:
        image: postgres:17
        profiles: ["llm", "all", "chat"]

    litellm-redis:
        image: valkey/valkey:8.1
        profiles: ["llm", "all", "chat"]

    litellm-bootstrap:
        image: badouralix/curl-jq:debian    # runs once to create API keys
        depends_on:
            litellm:
                condition: service_healthy
        restart: no
```

--------------------------------

### Watchtower Manual Trigger and Homelab Update Command

Source: https://context7.com/juftin/homelab/llms.txt

Provides commands to manually trigger Watchtower for immediate container updates. The `docker exec` command runs Watchtower directly, while `homelab update` is a higher-level script.

```bash
# To manually trigger an immediate update check:
docker exec watchtower /watchtower --run-once

# Or use the homelab update command for immediate pull + restart:
homelab update APP=sonarr
```

--------------------------------

### Pull latest images for homelab services

Source: https://github.com/juftin/homelab/blob/main/docs/cli.md

Commands to pull the latest Docker images for all homelab services. This can be executed via `homelab`, `make`, `docker compose`, or `homelab-compose`.

```shell
homelab pull
```

```shell
make pull
```

```shell
docker compose --profile all pull
```

```shell
homelab-compose --profile all pull
```

--------------------------------

### Backup Appdata Without Timestamp

Source: https://github.com/juftin/homelab/blob/main/docs/cli.md

Backs up the `appdata` directory without a timestamp, overwriting the previous backup (`appdata.tar.gz`). Requires the `BACKUP_DIR` variable to be set.

```shell
homelab backup-no-timestamp BACKUP_DIR=/backup/dir
```

```shell
make backup-no-timestamp BACKUP_DIR=/backup/dir
```

```bash
bash ./scripts/backup.sh appdata /backup/dir --no-timestamp
```

--------------------------------

### Migrate Tautulli Configuration

Source: https://github.com/juftin/homelab/blob/main/docs/migrations.md

Renames the Tautulli directory and moves its contents into a new 'config' subdirectory. This procedure is often followed when updating Tautulli or modifying its directory layout.

```bash
mv media-center/tautulli media-center/tautulli_temp
mkdir -p media-center/tautulli
mv media-center/tautulli_temp media-center/tautulli/config
```

--------------------------------

### Migrate Traefik Configuration

Source: https://github.com/juftin/homelab/blob/main/docs/migrations.md

Moves Traefik configuration files to a new directory structure, separating rules and config. Ensure the temporary directory is cleaned up afterward.

```bash
mv traefik/traefik/ traefik_temp
mkdir -p traefik/traefik/config
mv traefik_temp/rules traefik/traefik/rules
mv traefik_temp/config traefik/traefik/config/traefik
mv traefik_temp/logs traefik/traefik/config/logs
mv traefik_temp/acme traefik/traefik/config/acme
rm -r traefik_temp
```

--------------------------------

### Update homelab services

Source: https://github.com/juftin/homelab/blob/main/docs/cli.md

Commands to update all homelab services to their latest versions. This can be done using `homelab`, `make`, `docker compose`, or `homelab-compose`.

```shell
homelab update
```

```shell
make update
```

```shell
docker compose --profile all pull
docker compose --profile all up -d
```

```shell
homelab-compose --profile all pull
homelab-compose --profile all up -d
```

--------------------------------

### Google OAuth Middleware Configuration

Source: https://context7.com/juftin/homelab/llms.txt

Sets up the 'oauth' service for Google OAuth 2.0 authentication for subdomains. Authorized users are stored in secrets/google_oauth.secret. Requires Google API client ID/secret and a domain name.

```yaml
# apps/oauth.yaml
services:
    oauth:
        image: thomseddon/traefik-forward-auth:latest
        profiles: ["traefik", "core", "all"]
        environment:
            COOKIE_DOMAIN: ${DOMAIN_NAME}
            AUTH_HOST: oauth.${DOMAIN_NAME}
            URL_PATH: /_oauth
            DEFAULT_ACTION: auth
            DEFAULT_PROVIDER: google
            LIFETIME: 2592000   # 30-day cookie lifetime
        secrets:
            - source: google-oauth
              target: /config   # injected at runtime

# secrets/google_oauth.secret format:
# providers.google.client-id=GoogleClientID
# providers.google.client-secret=GoogleClientSecret
# secret=RandomSecretString
# whitelist=you@gmail.com
# whitelist=another@gmail.com
```

--------------------------------

### Stop homelab services

Source: https://github.com/juftin/homelab/blob/main/docs/cli.md

Commands to stop all homelab services. This can be executed using `homelab`, `make`, `docker compose`, or `homelab-compose`.

```shell
homelab down
```

```shell
make down
```

```shell
docker compose --profile all down
```

```shell
homelab-compose --profile all down
```

--------------------------------

### Migrate Calibre Configuration

Source: https://github.com/juftin/homelab/blob/main/docs/migrations.md

Renames the Calibre directory and moves its contents into a new 'config' subdirectory. This is a standard procedure for updating Calibre or restructuring its configuration.

```bash
mv media-center/calibre media-center/calibre_temp
mkdir -p media-center/calibre
mv media-center/calibre_temp media-center/calibre/config
```

--------------------------------

### Stop Services with Homelab CLI

Source: https://context7.com/juftin/homelab/llms.txt

Use `homelab down` to stop and remove containers. This command can stop all services, a single service by specifying `APP=<service_name>`, or be used with equivalent raw Docker Compose commands.

```bash
# Stop all services
homelab down
```

```bash
# Stop a single service
homelab down APP=plex
```

```bash
# Equivalent raw Docker Compose
docker compose --profile all down
```

```bash
docker compose --profile all down plex
```

--------------------------------

### Migrate NZBGet Configuration

Source: https://github.com/juftin/homelab/blob/main/docs/migrations.md

Renames the NZBGet directory and moves its contents into a new 'config' subdirectory. This procedure is often followed when updating NZBGet or modifying its configuration layout.

```bash
mv media-center/nzbget media-center/nzbget_temp
mkdir -p media-center/nzbget
mv media-center/nzbget_temp media-center/nzbget/config
```

--------------------------------

### Migrate Ombi Configuration

Source: https://github.com/juftin/homelab/blob/main/docs/migrations.md

Renames the Ombi directory and moves its contents into a new 'config' subdirectory. This process is typical for updating Ombi or restructuring its configuration.

```bash
mv media-center/ombi media-center/ombi_temp
mkdir -p media-center/ombi
mv media-center/ombi_temp media-center/ombi/config
```

--------------------------------

### Pull Latest Images with Homelab CLI

Source: https://context7.com/juftin/homelab/llms.txt

Use `homelab pull` to download the latest container images without restarting services. This command can pull all images or a single service image by specifying `APP=<service_name>`.

```bash
# Pull all images
homelab pull
```

```bash
# Pull a single service image
homelab pull APP=sonarr
```

```bash
# Equivalent raw Docker Compose
docker compose --profile all pull
```

--------------------------------

### Stop Media Services

Source: https://github.com/juftin/homelab/blob/main/docs/cli.md

Stops only the media services, such as Plex, Sonarr, and Radarr. Use the `--profile media` flag with docker compose.

```shell
homelab media-down
```

```shell
make media-down
```

```shell
docker compose --profile media down
```

```shell
homelab-compose --profile media down
```

--------------------------------

### Migrate Plex Configuration

Source: https://github.com/juftin/homelab/blob/main/docs/migrations.md

Renames the Plex directory and moves its contents into a new 'config' subdirectory. This is a common step when updating Plex or reorganizing its configuration files.

```bash
mv media-center/plex media-center/plex_temp
mkdir -p media-center/plex
mv media-center/plex_temp media-center/plex/config
```

--------------------------------

### Stop Core Services

Source: https://github.com/juftin/homelab/blob/main/docs/cli.md

Stops only the core services, such as Traefik and OAuth2. Use the `--profile core` flag with docker compose.

```shell
homelab core-down
```

```shell
make core-down
```

```shell
docker compose --profile core down
```

```shell
homelab-compose --profile core down
```

--------------------------------

### Stop Services Without Removing with Homelab CLI

Source: https://context7.com/juftin/homelab/llms.txt

Use `homelab stop` to stop containers without removing them, unlike `homelab down`. This command can stop all services or a single service by specifying `APP=<service_name>`.

```bash
# Stop all services
homelab stop
```

```bash
# Stop a single service
homelab stop APP=transmission
```

```bash
# Equivalent raw Docker Compose
docker compose --profile all stop
```

```bash
docker compose --profile all stop transmission
```