You probably don't need ArgoCD - good-enough GitOps with git and docker compose

huangchengsir — Thu, 18 Jun 2026 13:31:20 +0000

Every time someone starts self-hosting - a homelab, a few internal services for a small team - they tend to fall down the same rabbit hole: should I run K8s? And if I run K8s, do I need ArgoCD or Flux for GitOps? Two weeks later they've read a pile of Helm charts and CRDs and still haven't deployed a single service.

Let me say the quiet part out loud: for a single host, or three-to-five machines, you do not need ArgoCD. The part of GitOps you actually want - "the git repo is the source of truth, changes deploy themselves, I can roll back, and there's a record" - you can get 90% of it with git + docker compose and about twenty lines of script, with no control plane to babysit.

What "good-enough GitOps" actually is

GitOps boils down to two things:

Declarative: the desired state lives in git (for self-hosting, that's your docker-compose.yml).
Pull-based: the machine pulls changes and reconciles itself, instead of you SSHing in to type commands.

On one docker host, the minimal version looks like this: a webhook (or a 60-second git fetch) notices the tracked branch moved, and runs:

git pull --ff-only
docker compose pull
docker compose up -d --remove-orphans

--remove-orphans matters: services you delete from the compose file actually get stopped, instead of lingering forever. That's it - you now have a working GitOps loop: edit compose -> push -> the machine reconciles itself.

The two things that will actually bite you

The good-enough version runs, but there are two traps anyone who's done this knows:

1. Zero-downtime

Plain docker compose up -d recreates the container - old one stops, new one starts, with a few seconds of gap in between. Fine for background jobs, but for anything user-facing those few seconds are a 502.

compose up --wait (v2.17+) at least waits for the healthcheck before calling the deploy a success, which catches the "starts then crashes" case;
for true zero-downtime you end up running two service names (blue/green) behind a reverse proxy, flipping traffic once the new one is healthy, then stopping the old.

Don't expect compose to do graceful rolling updates for you. It doesn't.

2. Rollback

This is the one most people skip and the one that hurts most. If your image tag is :latest, then "rollback" means "edit the file and pray" - you have no idea which version last worked.

The fix: pin image tags to the git commit SHA (myapp:9f8322f, not myapp:latest), and record which SHA is currently live. Now rollback degrades to "re-deploy the previous SHA" - deterministic and repeatable. Without it, your GitOps quietly turns into "git pull and hope".

When you should reach for a heavier tool

The boundary is clear:

One machine: the twenty-line script is genuinely fine. Don't overthink it.
3+ machines, or you need an audit trail of who deployed what, when: this is where hand-rolled scripts start accruing debt - you need concurrent multi-host deploys, unified rollback, a record of who triggered it. That's when a thicker tool starts paying for itself.

But note: that threshold is much later than most people assume. For the vast majority of self-hosting, you're still on the "twenty-line script is fine" side.

I eventually packaged this up

I understood all of the above, and still got tired of re-typing the webhook + pull + compose + SHA-pinning + rollback-record dance every time I set up a new machine. So I bundled it - along with the CI build step before it, agentless multi-host SSH deploys, and container management - into a single Go binary called Pipewright: scp one file to a server, run it, open the browser, and you get a visual pipeline + one-click deploy + a container panel, with no other runtime dependencies (the Vue frontend is compiled into the binary via embed.FS, SQLite by default).

It's basically the "good-enough GitOps" above, productized, with the zero-downtime and SHA-based rollback gaps filled in. MIT licensed, aimed at solo devs and small teams - not trying to replace GitLab for a 200-engineer org.

Repo: https://github.com/huangchengsir/pipewright

But even if you never touch it, the takeaway stands: for self-hosted GitOps, you probably don't need ArgoCD. Start with git + compose, and only add weight when you actually hit the wall.

Issues and pushback welcome.

I built a self-hosted CI/CD + deploy + ops platform that fits in one Go binary

huangchengsir — Tue, 16 Jun 2026 15:51:21 +0000

I run a handful of small VPS boxes for side projects. For a while my "deploy setup" was the usual trio: a CI runner (Jenkins, then Drone), something to push releases to servers (Ansible / Kamal scripts), and Portainer to actually see what was running and poke at containers.

On a 2GB box, wiring and babysitting three separate tools was more overhead than the apps I was shipping. So a few weeks ago I started building the thing I actually wanted: CI/CD + multi-server deployment + basic ops, in a single Go binary with zero runtime dependencies.

It's called Pipewright. You scp one file to a server, run it, open the browser — that's the whole install.

What it actually does

Visual pipeline builder — a two-level (stage → job) DAG canvas. Horizontal links run serially, vertical ones run in true parallel. It round-trips with .pipewright.yml, so you can click or commit your pipeline.
Isolated builds — version-pinned, container-isolated build steps with dependency caching; artifacts (images / JARs / dist bundles) you can push to a private registry.
Agentless deploys over SSH — zero-downtime switchover + rollback on failure, fan-out to multiple servers with partial-failure visibility.
Server & container ops — manage containers / images / stacks / volumes / networks across hosts, live stats, logs, and an in-browser terminal.
It can update itself — checks GitHub for the latest release and does a download → checksum verify → atomic replace → restart, from the UI.

The stack

Go backend, Vue 3 frontend, everything embedded into the one binary. SQLite by default (zero setup), MySQL if you want it. Auth is argon2id + CSRF, credentials live in an encrypted vault (never echoed back in plaintext), and there's an append-only audit log. ~50MB binary, runs comfortably on a tiny box.

What I learned building it

Embedding the whole frontend into the Go binary (embed.FS) is underrated. One artifact, no nginx, no separate static host.
Self-update is a great forcing function. The moment your tool updates itself in production, you stop being sloppy about release artifacts, checksums, and atomic file replacement. I've been dogfooding Pipewright to ship its own releases.
"One binary for all of it" is a real design tension. It's tempting to keep adding surface area. I keep reminding myself the goal is the opposite of Jenkins-at-scale: the lightest thing that still does the full build → deploy → watch loop for a few servers.

What it's NOT

It's not trying to replace GitLab/Jenkins for a 200-engineer org. No multi-tenant RBAC, no massive plugin ecosystem. If you're running a big org, use the big tools. If you're a solo dev or small team who just wants build → deploy → ops without standing up three services, that's exactly who I built it for.

It's early (a few weeks old) and I'm actively building. I'd genuinely love feedback — especially on whether the "all-in-one binary" framing makes sense to you, or whether it's doing too much.

Repo (MIT, screenshots + one-command quickstart): https://github.com/huangchengsir/pipewright

Thanks for reading 🙏

DEV Community: huangchengsir