Command Line Usage

This project includes a Makefile that provides a variety of commands to manage your deployment.

homelab and homelab-compose

You will see the make command and homelab used interchangeably in this documentation. The homelab command is a convenience wrapper around make so you can easily run the Makefile from anywhere.

Add this to your .bashrc / .zshrc to use the homelab command:

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

If you'd like to use the docker compose command from anywhere, you can do so with the following alias:

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

homelab help

Usage: homelab [target] (APP=service-name)

* pass APP=service-name to specify the service
* pass ARGS=arguments to specify additional arguments

Homelab 🐳
  update               Update the service(s) *
  pull                 Pull the latest image(s)*
  up                   Start the service(s)*
  down                 Stop the service(s)*
  stop                 Stop the service(s)*
  logs                 Show the logs*
  restart              Restart the service(s)*
  ps                   Show the status of the service(s)*
  config               Show the configuration of the service(s)*

Core Services 🧠
  core-up              Start just the core services (traefik, oauth2, etc).
  core-down            Stop just the core services (traefik, oauth2, etc).
  core-logs            Show the logs for the core services (traefik, oauth2, etc).

Media Services 📺
  media-up             Start just the media services (plex, sonarr, radarr, etc).
  media-down           Stop just the media services (plex, sonarr, radarr, etc).
  media-logs           Show the logs for the media services (plex, sonarr, radarr, etc).

Configuration 🪛
  config-acme          Initialize the acme.json file.

Backup 🗂️
  backup               Backup the homelab repo to the ${BACKUP_DIR}.
  backup-no-timestamp  Backup the homelab repo to the ${BACKUP_DIR} without a timestamp.

Development 🛠
  docs                 Build the documentation.
  lint                 Lint the code with pre-commit.

General 🌐
  version              Show the version of the project.
  help                 Show this help message and exit

Commands

The APP flag

Notice that some commands accept an APP flag. This flag is used to specify which docker compose service to run on. If not specified these commands default to all services.

Show logs for a specific serviceShow logs for all services

homelab logs APP=sonarr

homelab logs

The ARGS flag

Some commands accept an ARGS flag to pass additional flags to docker compose. If not specified these arguments default to empty.

Pruning Orphaned Containers

homelab up ARGS="--remove-orphans"

Homelab 🐳

update

Update the homelab service(s) to the latest versions.

* Defaults to all, accepts the APP flag * Accepts the ARGS flag

homelabmakedockerhomelab-compose

homelab update

make update

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

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

pull

Pull the latest images for the homelab service(s).

* Defaults to all, accepts the APP flag * Accepts the ARGS flag

homelabmakedockerhomelab-compose

homelab pull

make pull

docker compose --profile all pull

homelab-compose --profile all pull

up

Start the homelab service(s).

* Defaults to all, accepts the APP flag * Accepts the ARGS flag

homelabmakedockerhomelab-compose

homelab up

make up

docker compose --profile all up -d

homelab-compose --profile all up -d

down

Stop the homelab service(s).

* Defaults to all, accepts the APP flag * Accepts the ARGS flag

homelabmakedockerhomelab-compose

homelab down

make down

docker compose --profile all down

homelab-compose --profile all down

stop

Stop the homelab service(s).

* Defaults to all, accepts the APP flag * Accepts the ARGS flag

homelabmakedockerhomelab-compose

homelab stop

make stop

docker compose --profile all stop

homelab-compose --profile all stop

logs

Show the logs for the homelab service(s).

* Defaults to all, accepts the APP flag * Accepts the ARGS flag

homelabmakedockerhomelab-compose

homelab logs

make logs

docker compose --profile all logs -ft

homelab-compose --profile all logs -ft

restart

Restart the homelab service(s).

* Defaults to all, accepts the APP flag * Accepts the ARGS flag

homelabmakedockerhomelab-compose

homelab restart

make restart

docker compose --profile all restart

homelab-compose --profile all restart

ps

Show the status of the homelab service(s).

homelabmakedockerhomelab-compose

homelab ps

make ps

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

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

config

Show the configuration of the homelab service(s).

* Defaults to all, accepts the APP flag * Accepts the ARGS flag

homelabmakedockerhomelab-compose

homelab config

make config

docker compose --profile all config

homelab-compose --profile all config

Core Services 🧠

core-up

Start just the core services (traefik, oauth2, etc).

homelabmakedockerhomelab-compose

homelab core-up

make core-up

docker compose --profile core up -d

homelab-compose --profile core up -d

core-down

Stop just the core services (traefik, oauth2, etc).

homelabmakedockerhomelab-compose

homelab core-down

make core-down

docker compose --profile core down

homelab-compose --profile core down

core-logs

Show the logs for the core services (traefik, oauth2, etc).

homelabmakedockerhomelab-compose

homelab core-logs

make core-logs

docker compose --profile core logs -ft

homelab-compose --profile core logs -ft

Media Services 📺

media-up

Start just the media services (plex, sonarr, radarr, etc).

homelabmakedockerhomelab-compose

homelab media-up

make media-up

docker compose --profile media up -d

homelab-compose --profile media up -d

media-down

Stop just the media services (plex, sonarr, radarr, etc).

homelabmakedockerhomelab-compose

homelab media-down

make media-down

docker compose --profile media down

homelab-compose --profile media down

media-logs

Show the logs for the media services (plex, sonarr, radarr, etc).

homelabmakedockerhomelab-compose

homelab media-logs

make media-logs

docker compose --profile media logs -ft

homelab-compose --profile media logs -ft

Configuration 🪛

config-acme

Initialize the acme.json file for traefik.

homelabmakebash

homelab config-acme

make config-acme

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

Backup 🗂️

backup

Backup the appdata directory with a timestamp (appdata_YYYYMMDDHHMM.tar.gz).

* You must provide the BACKUP_DIR variable

See the backup script documentation

homelabmakebash

homelab backup BACKUP_DIR=/backup/dir

make backup BACKUP_DIR=/backup/dir

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

backup-no-timestamp

Backup the appdata directory without a timestamp. This overwrites the previous backup (appdata.tar.gz)

* You must provide the BACKUP_DIR variable

See the backup script documentation

homelabmakebash

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

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

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

Development 🛠

docs

Build the documentation.

homelabmakebash

homelab docs

make docs

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

lint

Lint the code with pre-commit.

homelabmakebash

homelab lint

make lint

pre-commit run --all-files

General 🌐

version

Show the version of the project.

homelabmakebash

homelab version

make version

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

help

Show this help message and exit.

homelabmake

homelab help

make help