selfhosted-templates/homelab/setup.org

Homelab Setup

• Domain Name
• Port Forwarding
• Firewall Rules
• Configuration
• Start Containers
• Administration Setup
• Maintenance

This walks you through setup of this homelab docker-compose template into a working production environment.

Domain Name

In order for this to work, you're going to need a domain name. Do a search for the best domain name registrars and pick one. Then search up domain names you would like until you find something available. Then, as long as you aren't trying to get something fancy like .gg or .ai, the yearly payments shouldn't be too bad.

Once you have purchased it, you'll need to create an A record for that domain pointing to your IP address (i.e. the IP from your VPS, or the public IP of your home). Then, you'll need CNAME records for each subservices to point to the domain name you chose. Here is an example:

Domain: example.com

Type	Host	Value
A Record	@	142.251.32.46
CNAME Record	nextcloud	example.com
CNAME Record	gitea	example.com
CNAME Record	freshrss	example.com
CNAME Record	homepage	example.com

The following setup would:

• Redirect example.com to 142.251.32.46
• Redirect nextcloud.example.com (a subdomain of example.com) to whatever example.com is redirected to (142.251.32.46)
• Redirect gitea.example.com (another subdomain of example.com) to whatever example.com is redirected to (142.251.32.46)
• etc…

As you can see, every single subdomain points to the exact same IP address. However, Nginx Proxy will decide what to show you based on what subdomain you're connecting to. In this sense, you can only connect to the services by supplying the correct subdomain (you can't necessarily connect to your Nextcloud instance via a local IP, like 192.168.1.43).

Port Forwarding

You only need to care about port forwarding if you are setting this up on your home network. Port forwarding redirects traffic on any ports you specify from your public IP address to an internal IP address on your network. On your server, run the following command to get your internal IP address.

ip a

Next, in your router settings, you'll want to first configure the server to have a static IP address. Then, you can port forward outside connections to the IP address of your server.

For this setup, Nginx Proxy requires ports 443 and 80 (443 is for HTTPS while 80 is for HTTP). So to successfully port forward, you'll need 2 rules:

• External Port 443 -> [Server Local IP Address (i.e. 192.168.1.43)] Port 443
• External Port 80 -> [Server Local IP Address (i.e. 192.168.1.43)] Port 80

As a bonus, in this example, Gitea is configured to use SSH on port 2321, so you can port forward that as well:

• External Port 2321 -> [Server Local IP Address (i.e. 192.168.1.43)] Port 2321

Remember to keep in mind, anything you port forward in this manner will be publicly accessible to the internet. If anything that doesn't require authentication is port forwarded, anyone can go and mess with it.

Firewall Rules

In order to make sure everything works, the server's firewall must be configured to allow access to the ports we need. If you're setting this up on a home network, you may need to make these same configuration changes on your router's firewall as well (many modern routers will automatically update the firewalls once you've set up port forwarding though).

This part isn't too bad; simply allow incoming access on the ports we mentioned earlier:

• Allow Incoming Port 443
• Allow Incoming Port 80
• Allow Incoming Port 2321

In my config (GitLab, GitHub), all that needs to be set are the rules inside of firewall.nix:

{ config, pkgs, ... }:

{
  # Firewall
  networking.firewall.enable = true;
  # Open ports in the firewall.
  networking.firewall.allowedTCPPorts = [ 443 80 2321 ];
  networking.firewall.allowedUDPPorts = [ 443 80 ];
}

If you use something like Ubuntu or Debian, then you probably have UFW (Uncomplicated Firewall) installed. Look at its documentation to find out how to allow access to the necessary ports.

If you're setting this up on your home network and it doesn't work after you've done all this, check your router settings, since you may have to apply the exact same firewall rules to your router as well.

Configuration

In the docker-compose.yml file, configure the following:

• MOST IMPORTANT: CHANGE ALL THE PASSWORDS IN ALL THE ENVIRONMENT FILES (found in the env directory)

  • THEY ALL SAY CHANGEME SO THERE IS NO EXCUSE FOR MISSING THIS
• Set the VIRTUAL_HOST, LETSENCRYPT_HOST and LETSENCRYPT_EMAIL for each service accordingly
• Set the time zone (TZ) for the containers that request it

Start Containers

Once everything is properly configured and you've double-checked it, you can start all the necessary containers by running:

# inside of homelab directory
sudo docker-compose up -d

Administration Setup

Now, immediately navigate to each public-facing service (Nextcloud, Gitea, FreshRSS, Heimdall). If everything went correctly, you should be greeted with an installation page to complete. This is where you will configure an admin account for the website, so make sure to do it fast before some script kiddy compromises your server!

Maintenance

For more details on maintaining this environment, see maintenance.org.