Getting Started

Online service setup

This setup uses a public Domain Name to allow publishing local services and to have a recognized TLS certificate. An alternative is to use free subdomains (e.g. duckdns.org) but its support is not included in this setup.

Register a Domain Name, e.g. at OVHcloud - but the registrar does not matter, see next step
Transfer the DNS Zone administration to Cloudflare - Traefik reverse proxy certificate renewal is configured to use Cloudflare

Local configuration

The recommended setup is to setup Proxmox VE and install a Debian- or Ubuntu-based VM to host the Docker services. For development and administrative purposes, a separate VM can be used with additional tools installed. This separation from the Docker host is a best practice, but to simplify the setup these two roles can be unified.

1. Install Proxmox Virtual Environment

–> See Proxmox VE

2. Setup development/admin environment

Option A - Use devcontainer (easy method)

The repository includes a devcontainer configuration. Using Visual Studio Code, the Dev Containers extension and Docker the development (e.g. adding more serives, building the documentation) and administration tasks (e.g. running an Ansible playbook) can be performed on any environment without additional software installation.

Follow the Dev Containers tutorial to get started.

Note: the resulting container image is pretty large (3+ GB) as it includes all software configured in ansible/inventory/group_vars/debian/vars.yaml.

Option B - Use a dev/admin host

The development/administrative host is used for the initial configuration and for development.

Supported OS: Debian/Ubuntu (even in WSL). MacOS is also supported, but only for working with Ansible remotely and applying the mac_base role locally.

Steps:

Clone the repository on a supported OS: git clone <repository url>
Install Ansible with: ansible/bootstrap-ansible.sh
Edit ansible/inventory/inventory.yaml and ansible/playbooks/homelab.yaml, include your host with markosamuli.linuxbrew and debian_developer roles
Run docker/apply-local.sh

3. Install Ubuntu Server VM (Docker host)

Edit the parameters and use the infra/proxmox/create-ubuntu-server-vm.sh script to automatically create an Ubuntu Server LTS virtual machine and start the OS installation.

Note - Alternatives:

Create the VM on the Proxmox GUI, download and attach the installer CD and proceed with manual installation (who does that?)
Use Terraform to deploy the VM via the Proxmox Terraform provider
Install Ubuntu as an LXC container (there could be some limitations)

4. Install and configure the required software using Ansible

Required and recommended software (like Docker, tmux, …) are installed and configured by Ansible.
For details, check the ansible / inventory|roles|playbooks folders.

Execute on the admin host: ansible/apply-homelab.sh

5. Configure Docker environment files

Docker Compose’s variables are defined in .env files with different scopes:

File	Purpose
`docker/hosts/.env`	Common variables, can be used in all hosts and services
`docker/hosts/.env.<service_name>`	Variables scoped to a service
`docker/hosts/<host_name>/.env`	Host-specific variables
`docker/hosts/<host_name>/.env.<service_name>`	Variables scoped to a specific service on a specific host

Use (copy) docker/hosts/.env.example and docker/hosts/example/.env as a starting point of configuration of the Docker-based services.

Warning: The .env* files are not committed to the repository (see: .gitignore) because they contain sensitive information. Ensure these files are backed up!

Sample folder structure:

docker/hosts
├── .env
├── example
│   ├── apply.sh
│   └── .env
├── nas
│   ├── apply.sh
│   └── .env
└── nest
    ├── apply.sh
    └── .env

6. Configure core services

TODO Separate core services, like Traefik

TODO Describe the minimally required (core) service configuration

7. Start the containers

Edit docker/hosts/<hostname>/apply.sh to select which services (stacks) should be started (up function) or stopped (down function).

To apply the changes run run task docker:apply or docker/hosts/<hostname>/apply.sh.

8. Configure the router

After setting up the VM, configure the following on the router:

Fix IP (static DHCP lease) for the Docker host
To enable external access to selected services: Port forward to the VM (In OpenWrt: Network -> Firewall -> Port Forwards)
- HTTPS - Port 443 TCP & UDP
- WireGuard - Port 51820 UDP
Configure the local DNS service to resolve your domain name to the main Docker host. This is to provide uninterrupted DNS name resolution of the local services in case of the internet access fails.

9. Configure addition infrastructure services

TODO Describe configuration

AdGuard
Cloudflare
Monitoring
Backup