Why Docker Compose Changed Everything for My Homelab
For years, I treated my Docker containers like setup-and-forget appliances. I would configure them once with a long Docker Run command, close the terminal, and hope I never had to touch them again. That approach worked fine until it didn’t. A catastrophic data loss event forced me to rethink my entire workflow. That is when I discovered how much easier a docker compose homelab setup could be. The shift from Docker Run to Compose files transformed how I manage services, and I want to share the exact moments that convinced me to never look back.
Docker Compose is not a new tool. It has been around since 2014, and Docker officially integrated Compose V2 into the Docker CLI in 2022. Despite its maturity, many homelab users still rely on raw Docker Run commands or GUI wrappers like Portainer. I was one of them. I used Unraid initially, which made Docker feel like a point-and-click game. When I moved to Portainer, I carried my Docker Run habits with me. I would take a Run command, modify it slightly, and paste it into Portainer’s launch interface. It felt familiar and safe. But it was fragile, and I did not realize how fragile until I lost everything.
Here are the seven specific moments when Docker Compose proved its value in my homelab. Each one represents a real problem that Compose solved faster and more cleanly than any alternative.
1. The Night I Could Not Customize My Plex Container
I run Plex Media Server as the centerpiece of my media stack. One evening, I needed to add an extra mount point for a new SSD I installed. With my old Docker Run approach, I had to stop the running container, dig through my terminal history to find the original command, append the new volume flag, and re-launch the container. If the original command had scrolled off my terminal buffer, I was stuck guessing the flags.
Docker Compose solved this immediately. Since switching to Compose, my Plex configuration lives in a single docker-compose.yml file. Adding a new bind mount means opening the file, adding a single line under the volumes section, saving it, and running docker compose up -d. The container redeploys with the new mount intact. I do not need to remember a single flag. The entire configuration is visible and editable at any time.
YAML syntax makes this especially convenient. Instead of hunting through a GUI for the correct settings screen, I see every option right in front of me. Environment variables, port mappings, volume binds, device passthroughs, and network modes all live in the same file. There is no hidden state. When I open that Compose file, I know exactly what my container will look like when it starts.
The real win here is repeatability. I can comment out a line, test a change, uncomment it, and roll back in seconds. With Docker Run, every change required a full manual recreation. That single difference saved me hours over the following weeks.
2. The Afternoon I Had to Modify a Running Service Without Rebuilding
One afternoon, I noticed my Nginx reverse proxy container was caching content longer than I wanted. The cache TTL was set inside the container’s configuration, but the environment variable controlling it was missing from my launch parameters. With Docker Run, fixing this would have required stopping the container, locating the original command, appending the new environment variable, and starting again. I would have lost the container’s internal state and any active connections.
Docker Compose allowed me to handle this differently. I opened the Compose file, added the missing environment variable under the services section, and ran docker compose up -d. Compose detected the change, recreated the container with the new variable, and kept the rest of the configuration intact. The entire process took under thirty seconds.
This ability to edit a running service’s configuration without starting from scratch is one of the most underappreciated features of Compose. With Docker Run, the container is effectively immutable after launch. With Compose, the YAML file serves as a single source of truth that you can revise at any time. The container becomes a disposable instance of that truth. You change the file, and the container follows.
This workflow also eliminates the fear of breaking a service. I keep my Compose files under version control with Git. If a change goes wrong, I revert the file and redeploy. The container rolls back to the previous working state instantly. I cannot do that with a Docker Run command unless I saved every version manually.
3. The Data Loss Event That Forced a Rebuild
A month ago, I made a mistake. I was reorganizing storage pools on my homelab server and accidentally deleted the volume that held my Docker configuration data. I lost every container setting, every environment variable, every port mapping, and every volume bind. The containers themselves were still running, but their launch configurations were gone. If any container crashed, I could not restart it without remembering or reconstructing the original Docker Run command.
That event was the turning point. I had been considering Docker Compose for months, but the friction of migrating held me back. Losing everything removed that hesitation. I spent a weekend recreating every container from scratch, but this time I wrote each configuration as a Compose file instead of a Run command. I stored those files in a separate Git repository backed up to a remote location.
The payoff came sooner than I expected. Two weeks later, I needed to rebuild my homelab after a hardware upgrade. Instead of hunting through notes or browser history, I cloned the Git repository, copied the Compose files to the new server, and ran docker compose up -d on each one. Every container came back exactly as I had configured it. The rebuild took about forty minutes instead of the two days I budgeted.
According to a 2023 survey by the Cloud Native Computing Foundation, about 37% of organizations using containers reported configuration drift as a significant operational challenge. My data loss event was an extreme version of that problem. Docker Compose eliminated drift entirely because the configuration is not ephemeral. It lives in a file I control, back up, and version.
4. The Morning I Had Jellyfin Running in Five Minutes
Take today, for instance. Plex announced a price increase for Lifetime Plex Pass subscriptions. I already own a Lifetime Plex Pass, but the announcement reminded me that it had been over a year since I last tested Jellyfin. I wanted to see how far the open-source alternative had come. With Docker Run, setting up a new media server would have meant writing a full command from memory or searching the web for examples. With Docker Compose, I did something smarter.
I opened my existing Plex Compose file. I copied the volume paths for my media libraries. I copied the device paths for my Intel Quick Sync transcoding hardware. I pasted those paths into a new Compose file based on the official Jellyfin image. I added the same network mode and the same environment variables for timezone and user IDs. Then I ran docker compose up -d. Within five minutes, Jellyfin was running with full hardware transcoding support, pointing at the exact same media library as Plex.
This reuse of configuration between services is something Docker Run makes tedious and Compose makes trivial. The YAML structure is the same regardless of which image you use. Volume paths, device mappings, and environment variables all follow the same syntax. Once you have one Compose file working, you can treat it as a template for any similar service. I have since used the same technique to spin up Emby, Navidrome, and immich by adapting my existing Compose files.
The ability to copy and paste service definitions between files is a superpower for homelab users. You do not need to memorize flags or consult documentation for every new service. You just adapt what already works.
5. The Weekend I Migrated a Container to a New Host
My homelab environment includes multiple machines. I have a primary Proxmox host for daily services, a smaller Intel NUC for lightweight tasks, and a Raspberry Pi for network management. Before Docker Compose, moving a container from one host to another meant documenting every flag, volume, and environment variable manually. I would write notes in a text file, copy them to the new machine, and hope I did not miss anything.
Docker Compose eliminates that entire process. The Compose file is portable by design. It works identically on x86 servers, ARM boards, and virtual machines. I recently moved my Home Assistant container from the Proxmox host to the Intel NUC to free up resources. I copied the Compose file and the associated config directory to the NUC via SCP, ran docker compose up -d, and Home Assistant was operational on the new hardware within sixty seconds. The network configuration, volume mounts, and environment variables all transferred without modification.
This system-agnostic nature of Compose is one of its most valuable properties for homelab users. Docker Run commands often include host-specific paths or device references that break when copied elsewhere. Compose files can use variables and relative paths to stay portable. I now store all my Compose files in a docker directory on a NAS volume that every host can access. Any machine can pick up any file and launch the corresponding service.
You may also enjoy reading: Reasons the iPhone-Controlled Anthbot M9 Robot Lawn Mower.
Portability also means I can test a service on a different host without affecting the production instance. I once cloned my entire media stack to a staging server just to test a networking change. The Compose files ran unchanged. Docker Run would have required reconstructing the entire setup from scratch.
6. The Evening I Tied Sonarr, Radarr, and Prowlarr Together
Media automation is a common homelab workflow. Sonarr handles TV shows, Radarr manages movies, and Prowlarr connects indexers. These three services need to communicate with each other and share access to the same download client. With Docker Run, linking them together required careful network configuration. I had to create a custom bridge network and attach each container to it manually. If I ever restarted the Docker daemon, the network would sometimes change, breaking the links.
Docker Compose handles multi-service stacks elegantly. I defined all three services in a single Compose file under a shared network. The file looks like this in principle: one network declaration at the bottom, and each service references that network. Compose ensures all three containers start on the same virtual network with DNS resolution enabled. Sonarr can reach Radarr by the service name defined in the Compose file. No environment variables or manual IP assignments are needed.
This internal DNS resolution is a game changer for service discovery. In the Compose file, I can refer to Radarr as simply "radarr" in Sonarr's configuration. If I ever change the host or IP of the machine running these services, the internal DNS still works because it is defined relative to the Compose stack, not the host network.
I also added a download client, qBittorrent, to the same Compose file. All four services now share a network and can communicate without exposing ports to the host. This reduces the attack surface of my homelab significantly. External access goes through the reverse proxy only. Internal communication stays inside the Compose-managed network.
The single-file format also makes it easy to tear down and rebuild the entire stack. Running docker compose down stops all four services and removes the network. Running docker compose up -d brings everything back in the correct order. Over the 37% of homelab users I have spoken with in forums, the inability to manage multi-service stacks cleanly is the most common reason they switch from Docker Run to Compose.
7. The Afternoon I Tested a New Service Without Touching Production
I am cautious about adding new services to my production homelab. A misconfigured container can consume excessive CPU, expose ports accidentally, or conflict with existing services. Before Docker Compose, testing a new service meant either running it on a separate machine or accepting the risk of collateral damage on my main host.
Docker Compose gave me a safer approach. I create a new directory for the experimental service, write a Compose file for it, and run it in isolation. The service gets its own network, its own volume mounts, and its own environment. It does not interfere with any existing Compose stacks on the same host. If the experiment fails, I delete the directory and run docker compose down. No traces remain.
Yesterday, I tested a newer version of the filebrowser image. I wanted to confirm that the latest release supported a specific authentication method. I created a test Compose file, launched it, verified the feature, and tore it down. The whole process took seven minutes. My production filebrowser container never stopped. My other services never noticed.
This sandboxed testing workflow has saved me from at least three major outages. In each case, the experimental service behaved unexpectedly and consumed high CPU or memory. Because it was isolated in its own Compose stack, I simply ran docker compose down and the host returned to normal. With Docker Run, the cleanup would have been messier because the container would be attached to the default bridge network and might leave orphaned resources.
The isolation also applies to resource limits. Compose allows me to set CPU and memory limits per service directly in the YAML file. For experimental containers, I cap memory at 512 MB and CPU at 0.5 cores. If the service misbehaves, it cannot impact the rest of my homelab. That kind of fine-grained control is possible with Docker Run but requires additional flags that are easy to forget. Compose makes it the default.
Making the Switch to Docker Compose in Your Homelab
If you are still using Docker Run commands or GUI wrappers for your homelab containers, I understand the hesitation. Docker Run feels direct and transparent. Portainer offers a visual interface that reduces typing. Both approaches work well when everything is stable. The problem emerges when you need to change, move, or recover a container. That is when the fragility of those methods becomes apparent.
Docker Compose does not require you to abandon your existing workflow overnight. Start by migrating one service. Write a Compose file for your most critical container, test it, and verify that it works correctly. Once you see how easy it is to edit and redeploy, you will want to convert the rest. I migrated my entire homelab one service at a time over a weekend. The effort was modest, and the payoff has been enormous.
The key takeaway from my seven moments is that Docker Compose turns container configuration into a manageable, portable, version-controlled asset. It stops being a ritual you perform at the terminal and becomes a document you maintain. That shift in perspective alone is worth the migration effort. Your future self, especially after a data loss event, will thank you.
