Skip to content

Installation

Beta Software Warning

This software has not reached version 1.0 and should therefore be considered unstable. While any tagged version should work well on its own, a nice friendly upgrade path from one version to another is not guaranteed.

If you like getting your hands dirty in early versions of software, this is for you. If you prefer to wait till things are stable and friendly, maybe hold off for a while.

Also, if you trash your server or wreck your data, that's on you. Test your backups. Trust nothing.

Requirements

Server

Note

On Debian/Ubuntu the deploy installs docker.io plus the compose v2 plugin itself (falling back to the legacy v1 package where v2 is unavailable, with a docker-compose compatibility shim when only the plugin exists), so a fresh server needs no manual Docker preparation.

Warning

If you are running on an ARM infrastructure such as Raspberry PI, set arm to true. Run: make set arm True

Optional Items

Client Computer

  • Docker installed and working.

Note

Two separate computers are not required, but are highly recommended. The idea is you have a server and then your personal computer, say a laptop or desktop. You deploy from your personal computer to the server. This way your settings are saved on your personal computer, and can be used to re-build the server and restore from backups if anything goes wrong.

Warning

If you do install HomelabOS directly on the server and deploy from there, make sure to back up your settings/ folder from the server to somewhere safe, otherwise you could lose your settings.

Domain Name

A domain configured with a A type DNS record of *.yourdomain.com pointed at your server's IP address. You can also use a subdomain as well, so *.homelab.yourdomain.com would work.

Note

This is optional because you can use Tor to access your services without registering a domain. For best support from 3rd party clients an actual domain is highly recommended. Also certain services do not work through TOR at the moment.

Note

It's easiest to have an actual domain to point at your services, but you can fake it by adding DNS overrides to your /etc/hosts file on *nix and MacOS if needed or for testing.

DNS Settings

You need to point your hlos-dev.wvs.lol, as well as *.hlos-dev.wvs.lol to the IP address your HomelabOS install is accessible at. If you are using a bastion host, then you would point at that IP. If you are using your home IP address, you would point it at that IP. You need to set up a wildcard DNS entry because all the services are served off of subdomains such as emby.hlos-dev.wvs.lol

Warning

If you are not using a real domain, but using /etc/hosts entries to 'fake' it, wildcard entries do not work in /etc/hosts. You need to create an entry for each service enabled. You can use the /var/homelabos/homelab_hosts file.

Changing your domain

If you need to change your domain (or subdomain) simply run make set domain new.domain.com then run make deploy again.

Port Forwarding

Ports 80 and 443 punched through any firewalls and port forwarded at your server in question.

Note

This is optional because if you are using the bastion server or TOR access, you do not need to deal with port forwarding or firewalls.

Cloud Bastion Server

Rather than pointing the domain at your home IP and having to manage DDNS, you can utilize a cloud server to act as a bastion host via Tinc vpn and nginx.

S3 Account

S3 is Amazon's Simple Storage Service which HomelabOS can optionally use to back up to. You can use Amazon's service, or one of many other S3 compatible providers. You can also back up to another HomelabOS instance if that other instance is running Minio, a self-hosted S3 service.

Installation

Video Installation Tutorial

Automatic Set-up

Paranoid method

wget https://gitlab.com/NickBusey/HomelabOS/-/raw/master/install_homelabos.sh
cat install_homelabos.sh

Inspect the script to confirm it is not doing anything malicious.

chmod +x install_homelabos.sh
./install_homelabos.sh

Lazy method

bash <(curl -s https://gitlab.com/NickBusey/HomelabOS/-/raw/master/install_homelabos.sh)

Manual Set-up

  • Download the latest version to your client computer and extract the folder.

Note

If you are using HomelabOS to provision a bastion server, run: make terraform

  • From inside the HomelabOS folder, set up the initial config: make config

Note

You will be prompted for the basic information to get started. The passwords entered here will be stored on the client computer and are used by ansible to configure your server. After you enter the information, HomelabOS will configure your local docker images and build your initial settings/ files.

  • Once you have updated your settings simply deploy HomelabOS with make deploy. You can run make deploy as many times as needed to get your settings correct.

You can check http://208.68.39.86:8181 in a browser to see the Traefik dashboard.

See a full list of commands in the Getting Started Section

SSLIP.io

You can turn on enable_sslip which will expose all your services via sslip.io.

This does not require a domain to test services with. Use https://SERVICE_SUBDOMAIN.SERVER_IP.sslip.io/; the subdomain defaults to the service instance name.

Example for Organizr with a SERVER_IP of 192.168.50.1 you could go to https://organizr.192.168.50.1.sslip.io/

For services using the shared routing template, SSLIP routes honor that instance's auth and https_only settings. Set auth: true in the service's configuration to require basic authentication, or Authelia when enabled. With https_only: true, the HTTP route redirects to HTTPS before authentication. Without auth: true, these routes have no HomelabOS proxy authentication; application login settings still apply.

After updating from a version that omitted these protections on SSLIP routes, redeploy affected services to update their router labels. See alternate-route authentication for details.

If you use an internal IP (192.x.x.x, 10.x.x.x, etc) the services will only be available from the network they belong to, and will have self-signed certificates.

If you use a public IP the services will be available from anywhere and will have valid certificates automatically generated by Traefik via LetsEncrypt.

Enabling Authentik SSO

Authentik is the built-in identity provider for single sign-on across services. To stand it up on a fresh install:

  1. In settings/config.yml set the Authentik block (see config.yml.blank for the full default set):

    authentik:
  enable: true
  bootstrap_enabled: true
  bootstrap_email: you@yourdomain.com

  2. Run make deploy. Traefik obtains certificates for authentik.<your domain> via Let's Encrypt, and the bootstrap flow creates the initial administrator. The generated admin password and API token are written under settings/passwords/.

  3. Log in at https://authentik.<your domain>/. Keep bootstrap_enabled: true — service roles use it to gate their managed OIDC provider provisioning.

  4. Enable any OIDC-capable service (for example make set wikijs.enable true), run make deploy again, and the shared provisioner creates that service's Authentik provider and application automatically. Logging into the service then offers "Sign in with Authentik".

Role-specific login, account-linking and first-run notes live in each service's docs page; the shared provisioner behavior (managed vs preserved fields, per-instance client identity, issuer overrides) is documented in the Authentik page.

Enabling Services

Run make set SERVICENAME.enable true where SERVICENAME is the name of the service you want to enable.

Example

make set miniflux.enable true

Then run make deploy again. That's it. It will take a few minutes for your server to download and start the relevant images.

Warning

Some services expose set up pages on start up. If you don't complete the set up step, there is a chance someone else could beat you to it. If they do just run make reset_one SERVICENAME then make deploy again and the service will reset to it's freshly installed state.

You can SSH into the server, and run systemctl status SERVICENAME where SERVICENAME is the name of the server you want to check is running. It will show you status and/or errors of the service.

Example

systemctl status miniflux

Deploying the same service twice

If you need two of the same service, enabling additional copies is simple.

Open settings/additional_services_config.yml and add the following:

servicename2:
    source_service: servicename
    enable: true

The name you choose is the instance's name everywhere: its systemd unit, its data directory under volumes_root, and — unless you say otherwise — its subdomain. So nextcloud2 is reachable at nextcloud2.YOURDOMAIN:

nextcloud2:
    source_service: nextcloud
    enable: true

Add subdomain: when you want a different address. To duplicate Nextcloud for your skydiving group at skydiving.YOURDOMAIN:

nextcloud_skydiving:
    source_service: nextcloud
    subdomain: skydiving
    enable: true

Run make as usual. No DNS change is needed — services are served off subdomains of your wildcard record.

Note

Prefer instance names without underscores (nextcloud2 over nextcloud_2) when you rely on the default subdomain: underscores are not valid in hostnames, and some applications reject them in URLs.

Syncing Settings via Git

HomelabOS will automatically keep the settings/ folder in sync with a git repo if it has one. So you can create a private repo on your Gitea instance for example, then clone that repo over the settings folder. Now any changes you make to settings/ files will be commited and pushed to that git repo whenever you run make deploy, make update or make config.

Backing up your Vault Password

Danger

This bit is important.

If you installed with the Automatic/One-Liner install, your vault password exists at ~/.homelabos_vault_pass for the user you ran the script as. Make sure to back this password up somewhere safe, and ideally not in your settings/ folder. If someone gains access to your settings/ folder and the vault password, bad things can happen. Store them separately.

Backing up your data

Make sure to back up your /var/homelabos/install directory nightly.

Troubleshooting / FAQ

Network Configuration

It is recommended to register an actual domain to point at your Homelab, but if you can't or would prefer not to, you can use HomelabOS fully inside your network. Simply make up a domain that ends in .local and enter that as your domain in host_vars/myserver.

When HomelabOS make deploy command completes, it creates a file on the server at /var/homelabos/homelabos_hosts. You can take the contents of this file and create local DNS overrides using it. All your requests should complete as expected.

NAS Network Attached Storage Configuration

Different HomelabOS services operate on libraries of media (Airsonic, Plex, and Piwigo as examples). Since these libraries can be large, it makes sense to keep them on another machine with lots of storage.

NAS shares are mounted on the HomelabOS host under /mnt/nas, which defaults to /mnt/nas. By default, NAS is disabled, and the services that can use it will instead use local folders under /mnt/nas.

For example, Emby will map /mnt/nas/Video/TV and /mnt/nas/Video/Movies into its container, and Paperless will mount /mnt/nas/Documents. Check the docker-compose files for each service to see what directories are used.

To configure your NAS, edit the # NAS Config section of settings/config.yml.

  1. Enable NAS by setting nas_enable: True
  2. Set nas_host to the hostname, FQDN, or IP address of your NAS.
  3. Choose your network share type (nfs or smb) and set nas_share_type to that value.
  4. Set your nas_share_path, if applicable. SMB shares will probably not have a value for this, but NFS will.
  5. If authenticating to access SMB shares, set your username and password in nas_user and nas_path.
  6. Set your Windows domain in nas_workgroup, if applicable.

Re-run make deploy to configure and enable your NAS.

Example unRAID configuration 
nas_enable: True
nas_host: unraid.mydomain.com
nas_mount_type: nfs
nas_share_path: /mnt/user
nas_user:
nas_pass:
nas_workgroup:
Example SMB configuration 
nas_enable: True
nas_host: 192.168.1.12
nas_mount_type: smb
nas_share_path: homelab
nas_user: user
nas_pass: 12345
nas_workgroup: WORKGROUP
Last update: September 27, 2026