From Docker to Kubernetes

An Introduction to Kubernetes

If you’re anything like me, your homelab journey went something like this:

  1. You started your homelab with Docker containers. Deploying a working webserver using docker is trivial, fun, and painless. It was great, but there was something missing. It was still a bit too manual.
  2. You moved from Docker to Docker Compose. Doing so was a natural step to take, so you could create more complex deployments using a single command. You actually had a working environment and everything is running smoothly, but why stop there?
  3. You looked at Kubernetes, because it’s what the cool kids are using, and promptly ran away screaming.

If you have collided with the Kubernetes learning cliff, fear not. This guide is designed to introduce Kubernetes in a way that makes sense to docker users, and move from a docker compose workflow to an entirely kubernetes based workflow.


The whole purpose of this guide is set up a working Kubernetes environment with minimal hardware requirements. For this system, all we need is:

  • A download of Debian (This guide will be using Debian Bullseye)
  • A USB stick to load the installation
  • A single x86 computer or VM of some description (this guide is using a Dell 9020m usff desktop). Anything celeron or higher should be fine.

Working Assumptions

This guide is going to assume some pre-existing knowledge:

  • You know how to use Docker Compose, and may use docker compose to run your environment currently.
  • You know how to use pre-built images, like the ones at
    • You may not know how to create a docker container from scratch using a dockerfile. That’s fine
  • You don’t have a clue about Kubernetes. Good! That’s who this guide is for.

Why Should we Learn Kubernetes?

Why would you want to follow this guide? Most of what we will be doing can be done with a docker compose setup, with less steps and less work. It’s a good question, but there are multiple advantages to designing your setup in kubernetes:

  • People don’t use docker in production. They use kubernetes. Getting familiar with the kubernetes terminology and workflows has direct benefits to learning a production environment.
  • Speaking of production, having a home setup is about bolstering your resume. Being able to set up a working kubernetes environment is something you can put on your resume and it’s very attractive to employers.
  • Docker compose is great for infrastructure as code, but it is not an automated system. Kubernetes lets you automate your entire deployment process from start to finish.
  • You’re building a system that can scale. We are sticking to a single node to lower the barrier of entry, but this guide would be nearly identical for a 3 node cluster.
  • If you are a developer, your goal is to have your test/dev environment be as close to production as possible. If you’re developing in docker and deploying in kubernetes, there’s lots of room for error between those two steps. If you start in kubernetes and finish in kubernetes, your dev environment will be set up nearly identical to a production workflow.
  • Kubernetes is write-once, use anywhere. Once you have your helm chart designed, you can deploy your project to a single node setup (like we will be doing), or to AWS/Azure/a production datacenter with very little (or no) change.
  • Learning is fun!


Throughout this first part of the series, We will be setting up a single node kubernetes environment:

  • Setting up a single node kubernetes workflow with a web management interface
  • Creating basic container deployment
  • Setting up a distributed filing system with backups
  • Routing our services using an ingress controller
  • Encrypting our traffic with let’s encrypt
  • Deploying gitea for source control
  • Deploying jellyfin with a helm chart

Sounds like a lot doesn’t it? We’ll take it slow, one step at a time, and build to the finale.

Future Roadmap

This first series is going to cover replacing your docker-compose workflow with a kubernetes based one. However, that’s really just scratching the surface of what constitutes devops. Further series will tackle:

  • A CI/CD Pipeline
  • Image Builds within kubernetes
  • Designing Helm Charts
  • Further authentication methods, such as oauth proxying and oidc federation (gitea supports both!)
  • High availability (more hardware will be required for this one) with harvester
  • horizontal scaling (this is a huge topic just on it’s lonesome)

But let’s not get ahead of ourselves.

Installing Debian

With the intro out of the way, let’s begin with Installing Debian!