↓Skip to main content

The Gateway to your Homelab

·750 words·4 mins
Agent IO
Author
Agent IO
Table of Contents

The first and longest-running instance of IO has been the gateway to a homelab. Here’s what that means and how you can put IO to work for you, too.

What’s a Homelab?
#

“A Homelab is a canvas for your technical endeavors, a playground for your curiosity” Joe Karlsson

If “homelab” is a new term for you, r/homelab is a great place to explore, but it can also be overwhelming!

For this discussion, a homelab consists of at least one computer where you are free to explore. You are learning by doing, and you’ve reached a point where you’d like to put something on the web. But how can you do that?

Here’s what you need: a computer, a connection to the internet, an externally-accessible IP address, and a domain that is pointed at that address.

What’s a Gateway?
#

Building on the commonly-agreed idea of API Gateway, we say that a gateway to a homelab handles all of the HTTP and HTTPS requests that come to the homelab and routes them to the right backends.

Why make IO the Gateway to your Homelab?
#

IO can bring capability, safety, and convenience to your homelab.

Capability. You want to run one or more services and make them publicly available on the internet. These can be websites or APIs that work over HTTP or HTTPS (this includes gRPC).

Safety. You want to use HTTPS to connect to your services. You want to require authentication for some or all of your services. You want to be able to block bad traffic to your services.

Convenience. You want to be able to easily configure and manage your services. You want to observe the traffic to and from your services.

What you need to use IO
#

IO will work best if you have a computer running Linux (we use Ubuntu) with Docker installed.

Ideally, the DNS for your domain would be configured with two A records. The first one (below) routes your root domain to your home server, and the second routes all subdomains to your home server.

A	@	[YOUR-IP-ADDRESS]			
A	*	[YOUR-IP-ADDRESS]

You should configure your home router to route these ports to your machine:

  • 80 and 443 to allow HTTP and HTTPS access
  • 22 (optionally) to allow remote SSH connections to your machine
  • 8022 (optionally) to allow remote SSH connections to your IO

Note that the optional ports are only needed if you want to manage your homelab from outside of your network. If you do everything at home or over a VPN like Tailscale, these aren’t needed.

Run IO in your Homelab
#

The best way to run IO is with Docker. See Running IO with Docker for details.

Point IO at your internal services
#

With IO running, create an ingress for each internal service that you want to publish. An ingress needs a domain name and a backend address.

Here’s an ingress configuration for a web site published at mysite.example.com. It assumes that the example.com domain is configured with an A record named * pointing at your local address.

host "mysite.example.com" {
  name    = "mysite"
  backend = "localhost:8080"
}

A quick way to set up a sample web server is to use Python’s http.server component:

$ python -m http.server 8080
Serving HTTP on 0.0.0.0 port 8080 (http://0.0.0.0:8080/) ...

But be careful! This serves files from your current directory, so you should probably do this from an empty directory (or one with a simple index.html file – it can just contain “Hello!”).

Get certificates for your sites from LetsEncrypt
#

You’re going to want to make your site available using HTTPS, and that requires a certificate. This used to be a hassle, but now sites can get certificates automatically from an online service called LetsEncrypt. IO can handle everything: you just need to have a server running at the domain name that you claim.

From the ingress details screen, press f to request (fetch) TLS credentials from LetsEncrypt. LetsEncrypt requires an email address, which you can set on the ingress overview screen.

Now it’s just a small step to the cloud
#

If you’ve done that once, you can easily do it hundreds of times, and once you have some experience managing your homelab IO with IO, you’ll find that it’s easy to set up a system in the cloud that runs everything that you’ve configured your homelab to do, and your cloud-based instance will keep running even when your power or internet access at home goes out.