Skip to content

🚧 Development

The development of my homelab is mainly done by watching YouTube videos and occasionally browsing Reddit.

🛠 Installation

Repo

Generally, the repo is meant to be used as a centralized location for my homelab config files and setup instructions.

This repo is cloned into each container and VM and then updated and maintained on that container and VM.

(
    [ -d ~/git/nicholaswilde ] || mkdir -p ~/git/nicholaswilde
    cd ~/git/nicholaswilde && \
    git clone [email protected]:nicholaswilde/homelab.git && \
    cd homelab
)

📦 Containers & VMs

I use different installation methods for the containers and VMs depending on what is available.

📜 Proxmox Helper Script

If a it exists as a Proxmox Helper Script, I'll use that.

📦 LXC

If that doesn't exist, I'll clone a Debian LXC and manually install the app. Generally, I like to stick with LXCs because of their lower overhead.

💻 VM

I'll use a VM if I need to pass through a device or the installation is complicated. I'll clone an existing Debian or Ubuntu VM and do a manual installation.

Docker

Sometimes if the installation is really complicated, I'll use Docker inside of and LXC or VM. I generally try to avoid Docker containers because of the overhead of Docker being installed in the container or VM.

🔧 Tools

📦 apt

Tools are generally installed, generally, using apt.

Note

I try to avoid using other package systems, such as pip or npm, to avoid the overhead of having those package systems installed.

📦 reprepro

If a deb file is available for download for the tool, I'll add it to my reprepro registry and install the tool using apt. Updating the tool is then just a matter of running apt update using Ansible.

📥 installer

If the tool is only available to download as a binary file, I'll use my installer container.

⚙ Config

Config files are backed up into this repo so that can be replicated or referenced when lost.

💾 Backups

The original files are copied into the original config location with a .bak extension before making any changes to them.

Example 
cp /etc/prometheus/prometheus.yml /etc/prometheus/prometheus.yml.bak

Generally, config files are moved to the repo for remote backup and then symlinked back to the original location.

Note

The app service needs to be stopped and restarted when moving the config files.

Example 
(
  systemctl stop prometheus.service
  cp /etc/prometheus/prometheus.yml /root/git/nicholaswilde/homelab/pve/prometheus/prometheus.yml
  ln -s /root/git/nicholaswilde/homelab/pve/prometheus/prometheus.yml /etc/prometheus/prometheus.yml
  systemctl stop prometheus.service
)

Warning

Some apps have trouble starting their service when using symlinked config files.

🔒 Encrypted Files

If the config file contains secrets, the file is encrypted and saved in the repo and the unencrypted file is added to .gitignore.

Encrypted files will end in .enc and are encrypted using SOPS and age.

Example 
sops -d --input-type dotenv --output-type dotenv .env.enc > .env

📝 .env Files

.env files are used to store variables and secrets. There are used whenever possible.

Template Files

Template files end in .tmpl and are not used by the app and are meant to be copied.

Example 
cp .env.tmpl .env

🔀 Workflow

  1. Create VM or LXC container.
  2. Ensure that python3 is installed on the container.
  3. Run setup playbook.
  4. Add to Ansible inventory.
  5. Setup app.
  6. Backup config files to repo on cintainer.
  7. Add to AdGuardHome.
  8. Run AdGuardHome sync.
  9. Add to Traefik.
  10. Add to homepage.
  11. Add to homelab docs.
  12. Add to WatchYourLAN.
  13. Add to Beszel.
  14. Add to authentik.

📄 New Document Pages

New pages for this site can be created using jinja2 and the .template.md.j2 file.

homelab/docs

APP_NAME="New App" task new > apps/new-app.md

jinja2 .template.md.j2 -D app_name="New App" -D app_port=8080 -D config_path=/opt/new-app > apps/new-app.md

🚀 Upgrades

Upgrades via Proxmox Helper Scripts

The helper scripts can update the app in the LXC/VM.

Docker Upgrades

Docker tags are scanned by Mend Renovate , which opens a PR if a newer version is available.

The PR is then merged and then the repo is pulled and updated on the LXC/VM and then Docker Compose performs a pull and restarts the Docker container.

The old and unused images are then purged to save space in the LXC/VM.

Warning

The below commands purge any unused Docker images! Use at your own risk!

homelab/docker/appname

task upgrade

(
  git pull origin
  docker compose up --force-recreate --build -d
  docker image prune -a -f
)

⏰ Cronjobs

Cronjobs ⏰ are run on some containers to periodically perform functions, usually to sync files.

Edit job

crontab -e

0 2 * * * * /foo.sh

🤝 Services

Systemd services are used to keep processes running in the background.

The services are usually created automatically if installed via a package manager, such as apt 📦.

Apps that are manually installed, such as Ventoy, need a service to keep them running after restarts.

Docker containers don't require services because they are managed by the restart policy.

💾 Logs

Logs are used to debug applications. They may be looked at once or followed get to real time updates.

📦 LXC Logs

Example 
journalctl -xeu prometheus.service

Docker Logs

Example 
docker logs immich-server

docker logs immich-server -f

🔗 References