I've been running a homelab Kubernetes cluster for a while now. It’s a simple two-node k3s setup with Traefik handling ingress and a Cloudflare Tunnel for external access. It’s been a great space to experiment and learn.

But deployment was still a pain.

Recently, I had a frontend app sitting in a GitLab repo, and every time I wanted to deploy, it turned into a small ritual. SSH into the server, pull the latest image, restart containers, and hope everything still worked. It got the job done, but it wasn’t something I trusted or enjoyed.

This post walks through how I moved from that setup to a full GitOps workflow using GitLab CI and ArgoCD. No prior ArgoCD experience, just figuring things out step by step until a simple `git push` became enough to deploy.

## The Starting Point

Going into this, my setup was pretty straightforward. I had a k3s cluster running on two Ubuntu nodes: one control plane and one worker, both on my local network. Traefik came bundled with k3s, so ingress was already handled. For external access, I was using a Cloudflare Tunnel running via `cloudflared` pods in a dedicated namespace, routing traffic from `*.demolamalomo.xyz` into the cluster.

The app itself was a frontend project. A Node.js app that builds into static files and gets served with nginx. The code lived in GitLab, and I was already using GitLab’s container registry to store images from earlier CI builds.

The CI pipeline, however, was doing too much. It built the image, then SSH-ed into the server to stop containers, remove them, pull new images, and restart everything. It worked most of the time, but it was fragile, hard to debug, and rolling back meant doing everything manually again.

## The Options I Considered

Throughout my deployment journey, I explored a couple of options before arriving at ArgoCD.

1. **Manual build and deploy** was basically what I was already doing. Build locally, push the image, run `kubectl apply`. The issue with this is that there’s no automation, no audit trail, and plenty of room for error.
2. **GitLab CI/CD handling everything** was the next step. The pipeline builds the image, pushes it, and deploys directly to the cluster using `kubectl`. This is where a lot of teams start, and honestly, it worked reasonably well for me too. But the CI was doing a lot of work, and it can get really messy with a lot of echoing and sshing commands. For context, below is a section of one of my CI build:

```bash
- echo "$ID_RSA_DEV_HOMELAB" > id_rsa_homelab
    - chmod 600 id_rsa_homelab
    - apk update && apk add openssh-client
    - echo "stop existing docker container & remove images"
    - echo "Port $STAGE_SVR_PORT_HOMELAB"
    - echo "User $DEV_SERVER_USER_HOMELAB"
    - echo "Host $STAGE_SVR_IP_HOMELAB"
    - echo "VM $STAGE_VM_IP_HOMELAB"
    - echo "Service $SERVICE_NAME_HOMELAB"
    - ssh -i id_rsa_homelab -p $STAGE_SVR_PORT_HOMELAB -o StrictHostKeyChecking=no $DEV_SERVER_USER_HOMELAB@$DEV_SVR_IP_HOMELAB "docker stop $SERVICE_NAME_HOMELAB || true"
......
```

3. **GitOps with ArgoCD** takes a different approach. CI still builds and pushes images, but it never talks to the cluster directly. Instead, it updates a Git repo that contains the Kubernetes manifests. ArgoCD, running inside the cluster, watches that repo and syncs any changes.The thing I liked most was that I could look at a repository and immediately know what should be running in the cluster.

That was the point where ArgoCD clicked for me. I liked the fact that I could open a repo and know exactly what was deployed. Rollbacks also become much simpler, by just reverting a commit. So I went with **ArgoCD**.

## Installing ArgoCD

I’d never used ArgoCD before, so this part was new. Thankfully, installation was straightforward:

```bash
kubectl create namespace argocd
kubectl apply -n argocd -f https://raw.githubusercontent.com/argoproj/argo-cd/stable/manifests/install.yaml
```

After a minute or so, everything was running, and I could start exploring the dashboard.

To access the dashboard, I started with a simple port-forward:

```bash
kubectl port-forward svc/argocd-server -n argocd 8080:443
```

The default login is `admin`, and the initial password is stored in a Kubernetes secret:

```bash
kubectl -n argocd get secret argocd-initial-admin-secret -o jsonpath="{.data.password}" | base64 -d
```

I also installed the ArgoCD CLI, which made it easier to create applications and debug sync issues without constantly switching to the browser.

Later on, I exposed ArgoCD through Traefik and my Cloudflare Tunnel so I could access it remotely, but the port-forward was more than enough to get started.

![ArgoCD UI](https://paper-attachments.dropboxusercontent.com/s_2A415A66514362A902F36E27BA0662B25C280357D4A31FB4FA73DA4B634FE1E6_1775396935665_Screenshot+2026-04-05+at+14.48.16.png)

## Understanding the Two-Repo Pattern

One thing that took me a while to wrap my head around was the idea of maintaining two repositories. At first it felt unnecessary. Why split things up when everything belongs to the same application?

But after working with it for a bit, the separation started to make sense.

The **application repo** is where development happens. Code changes, Dockerfile, and CI configuration (`.gitlab-ci.yml`).

The **GitOps repo** is different. Its only job is to describe what's running in the cluster. Deployments, Services, and Ingress definitions. ArgoCD watches this repo and syncs the cluster whenever something changes.

The benefit became obvious pretty quickly. My application repo changes all the time with feature work, bug fixes, and random experiments, while the GitOps repo changes much less often because it only reflects what should be running in the cluster.

![ArgoCD workflow](https://paper-attachments.dropboxusercontent.com/s_2A415A66514362A902F36E27BA0662B25C280357D4A31FB4FA73DA4B634FE1E6_1775397646668_mermaid-diagram.png)

My GitOps repo (`homelab-gitops`) ended up looking like this:

```bash
homelab-gitops/
  clohea-admin/   # my application folder
    deployment.yaml
    service.yaml
    ingress.yaml
```

## Setting up the GitLab CI Pipeline

My existing `.gitlab-ci.yml` was doing too much. The new version only needed to do two things: build the image and update the GitOps repo.

The build stage pushes two tags:

- `:latest` for general use
- a commit hash tag like `:a1b2c3d`, which is what goes into the manifests

That commit-specific tag is important because it gives ArgoCD a concrete change to detect.

```yaml
docker-build-homelab-dev:
    image: docker:latest
    stage: build
    services:
        - docker:dind
    before_script:
        - echo $CI_JOB_TOKEN | docker login -u "$CI_REGISTRY_USER" --password-stdin $CI_REGISTRY
    script:
        - echo "$DEV_ENV" > $CI_PROJECT_DIR/.env
        - docker build -f ./Dockerfile --pull -t "$CI_REGISTRY_IMAGE:latest" -t "$CI_REGISTRY_IMAGE:$CI_COMMIT_SHORT_SHA" .
        - docker push "$CI_REGISTRY_IMAGE:latest"
        - docker push "$CI_REGISTRY_IMAGE:$CI_COMMIT_SHORT_SHA"
    only:
        - homelab-dev
```

The deploy stage updates the GitOps repo:

```yaml
update-manifest:
    stage: deploy
    image: alpine:latest
    before_script:
        - apk add --no-cache git sed
        - git config --global user.email "ci@gitlab.com"
        - git config --global user.name "GitLab CI"
    script:
        - git clone https://deploy-token:${GITOPS_TOKEN}@gitlab.com/clohea-fe/homelab-gitops.git
        - cd homelab-gitops
        - 'sed -i "s|image: .*|image: ${CI_REGISTRY_IMAGE}:${CI_COMMIT_SHORT_SHA}|" clohea-admin/deployment.yaml'
        - git add .
        - git diff --cached --quiet && echo "No changes" || git commit -m "Update frontend image to $CI_COMMIT_SHORT_SHA" && git push
    only:
        - homelab-dev
```

One thing that tripped me up: the `sed` command needs to use double quotes so that the shell expands the CI variables. My first attempt used single quotes, which meant `$CI_REGISTRY_IMAGE` was treated as literal text. The `sed` command found nothing to replace, `git commit` found nothing to commit, and the pipeline failed with `exit code 1`. A small thing, but the kind of mistake that costs you 30 minutes of staring at logs.

**A Note on the GITOPS_TOKEN**
The `update-manifest` job needs write access to the GitOps repo. I created a **Project Access Token** in the GitOps repo (Settings > Access Tokens) with `write_repository` scope, then stored it as a CI/CD variable called `GITOPS_TOKEN` in the app repo (Settings > CI/CD > Variables), with the "Mask variable" option checked so it doesn't leak into logs.

I could also have used a Personal Access Token, which would work across all my repositories, but a Project Access Token scoped to just the GitOps repo is cleaner from a security standpoint.

## The Kubernetes Manifests

The GitOps repo itself stayed pretty simple. For this application, I only needed three manifests:

- A Deployment
- A Service
- An Ingress

Nothing fancy. Just enough to get the application running and exposed through Traefik.

```yaml
apiVersion: apps/v1
kind: Deployment
metadata:
    name: webapp-service
    namespace: frontend
spec:
    replicas: 2
    selector:
        matchLabels:
            app: webapp-service
    template:
        metadata:
            labels:
                app: webapp-service
        spec:
            imagePullSecrets:
                - name: gitlab-registry-cred
            containers:
                - name: webapp-service
                  image: registry.gitlab.com/clohea-fe/clohea-admin/webapp-service:INITIAL_TAG
                  ports:
                      - containerPort: 3000
```

Since the registry is private, I created an image pull secret:

```bash
kubectl create secret docker-registry gitlab-registry-cred \
  --namespace frontend \
  --docker-server=registry.gitlab.com \
  --docker-username=<deploy-token-username> \
  --docker-password=<deploy-token-value>
```

The service routes traffic internally:

```yaml
apiVersion: v1
kind: Service
metadata:
    name: webapp-service
    namespace: frontend
spec:
    selector:
        app: webapp-service
    ports:
        - port: 80
          targetPort: 3000
```

And the ingress exposes it via Traefik:

```yaml
apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
    name: webapp-service
    namespace: frontend
spec:
    ingressClassName: traefik
    rules:
        - host: admin-portal.demolamalomo.xyz
          http:
              paths:
                  - path: /
                    pathType: Prefix
                    backend:
                        service:
                            name: webapp-service
                            port:
                                number: 80
```

## Connecting ArgoCD to the GitOps Repo

For ArgoCD to watch the GitOps repo, it needs credentials since it's a private GitLab repo. I created a deploy token in the GitOps repo with `read_repository` scope, then added the repo to ArgoCD using the UI.

**Settings > Repositories > + CONNECT REPO**

![Add repository to ArgoCD](https://paper-attachments.dropboxusercontent.com/s_2A415A66514362A902F36E27BA0662B25C280357D4A31FB4FA73DA4B634FE1E6_1775418533445_Screenshot+2026-04-05+at+20.48.03.png)

Another option to do this is to use the CLI:

```bash
argocd repo add https://gitlab.com/clohea-fe/homelab-gitops.git \
  --username <deploy-token-username> \
  --password <deploy-token-value>
```

Then I created the application by entering the repository URL, the path to the application folder in the GitOps repo, and a few other required settings.

**Application > + NEW APP**

![New App](https://paper-attachments.dropboxusercontent.com/s_2A415A66514362A902F36E27BA0662B25C280357D4A31FB4FA73DA4B634FE1E6_1775418812700_Screenshot+2026-04-05+at+20.51.21.png)

I can also use the CLI by running the command below

```bash
argocd app create frontend \
  --repo https://gitlab.com/clohea-fe/homelab-gitops.git \
  --path clohea-admin \
  --dest-server https://kubernetes.default.svc \
  --dest-namespace frontend \
  --sync-policy automated \
  --auto-prune \
  --self-heal
```

Quick breakdown of the flags:

- `--sync-policy automated`: syncs on every commit
- `--auto-prune`: removes deleted resources
- `--self-heal`: reverts manual cluster changes

## The Debugging Marathon

If I'm being honest, the setup didn't just work on the first try. Here's a condensed version of the issues I hit, because I think they're genuinely useful for anyone doing this for the first time.

**Image pull errors.** The first deployment failed with a `403 Forbidden` because Kubernetes couldn't authenticate with GitLab's private container registry. The fix was creating the `docker-registry` secret and adding `imagePullSecrets` to the deployment manifest. Then it failed again with `not found` — the image tag referenced in the manifest didn't exist in the registry because my build job hadn't pushed a commit-hash tag yet.

**Name mismatches.** My ingress was referencing a service called `frontend`, but the actual service was named `webapp-service`. A simple typo that resulted in a 502 from Traefik. `kubectl describe ingress` made this obvious once I thought to look.

**Port mismatch.** This one was subtle. The deployment had `containerPort: 80` and the service was targeting port 80, but nginx inside the container was actually listening on port 3000. The Docker image had a custom nginx config that bound to 3000 instead of the default 80. Running `kubectl exec` and checking `netstat -tlnp` inside the pod revealed the mismatch immediately.

## The End Result

Once everything was wired up and the bugs were resolved, the flow became exactly what I wanted:

- I push code to the `homelab-dev` branch.
- GitLab CI builds the Docker image and pushes it to the registry with both a `:latest` and a commit-hash tag.
- The `update-manifest` job clones the GitOps repo, updates the image tag in the deployment manifest, and pushes.
- ArgoCD detects the new commit within seconds.
- ArgoCD syncs the manifests to the cluster, Kubernetes pulls the new image, and the app is live.

The ArgoCD dashboard shows the full picture. Sync status, pod health, the Git commit that triggered the deployment. If something goes wrong, I can see exactly which commit caused it and revert.

![ArgoCD Dashboard](https://paper-attachments.dropboxusercontent.com/s_2A415A66514362A902F36E27BA0662B25C280357D4A31FB4FA73DA4B634FE1E6_1775420456749_Screenshot+2026-04-05+at+21.19.00.png)

The entire deployment chain is now traceable through Git commits. No more SSH-ing into servers or chained server commands. Just `git push`, and everything takes care of itself.


I got tired of SSH-ing into servers every time I needed to deploy a simple app. So I spent an evening setting up GitLab CI, ArgoCD, and a GitOps workflow in my homelab. Here's what worked, what broke, and what I learned along the way.

From Manual Deploys to GitOps: How I Automated my Homelab with ArgoCD and GitLab CI

If you work with Docker, you’ve probably run into this at some point.

You spin up a Postgres or MySQL container for a project. Everything is running fine. Then you want to look at the data. Maybe a migration behaved strangely, maybe you want to insert a quick test row, or maybe you just want to confirm what’s actually in the database.

That’s when things get annoying.

You either drop into the terminal and start typing `psql` commands, install a desktop tool like pgAdmin and wait for it to load, or spin up another heavy container just to get a UI. It always feels like more effort than it should be just to inspect your own data.

I kept running into this friction, and eventually I decided to stop working around it and build something that fits how I actually use Docker.

That’s how **DockAdmin** started.

## What is DockAdmin?

DockAdmin is a lightweight database admin UI that runs directly inside your Docker environment. You add it to your compose file, run your stack, and immediately get a clean browser interface for managing your database.

```yaml
services:
    postgres:
        image: postgres:16
        environment:
            POSTGRES_USER: admin
            POSTGRES_PASSWORD: admin
            POSTGRES_DB: myapp

    dockadmin:
        image: demlabz/dockadmin
        ports:
            - '3000:3000'
```

No extra configuration, no setup wizard, and no external tools to install. It’s just another container that gives you a database UI.

It supports PostgreSQL, MySQL, and SQLite, which covers most everyday development use cases.

## Why Build Another Database Admin Tool?

There are already plenty of tools out there, but most of them don’t fit naturally into a Docker-first workflow.

Desktop tools are powerful, but they live outside your container environment. That means installing them, configuring connections, and maintaining them separately. That feels excessive when you only need to inspect a few rows or quickly test something.

[Adminer](https://www.adminer.org/en/) comes much closer to what I wanted. It’s lightweight, runs in a container, and uses database credentials for authentication, which keeps things simple. But the interface feels dated, and the overall experience doesn’t match what modern developer tooling looks like today.

[phpMyAdmin](https://www.phpmyadmin.net/) is also container-friendly, but it’s MySQL-only and carries a lot of historical baggage.

What I really wanted was something simple like Adminer, but with a modern UI, proper multi-database support, and a design that feels native to Docker from the start. That combination didn’t really exist, so I built DockAdmin.

## Why Rust on the backend?

Choosing Rust was a practical decision.

The full DockAdmin Docker image is around 15 MB, which is smaller than many `node_modules` directories. Rust compiles to a single static binary, so the runtime container only needs Alpine Linux and the compiled executable. There’s no interpreter, no runtime dependency chain, and no garbage collector to manage.

The backend uses Axum as the web framework and SQLx for database access. Axum is fast and ergonomic, and SQLx provides compile-time query checking with async support across Postgres, MySQL, and SQLite.

Here’s the Dockerfile:

```Dockerfile
# Frontend Build
FROM node:22-alpine AS frontend
WORKDIR /ui
COPY ui/package*.json ./
RUN npm install
COPY ui .
RUN npm run build

# Backend Build
FROM rust:1-alpine AS backend
WORKDIR /backend
COPY backend/Cargo.toml backend/Cargo.lock ./
RUN mkdir src && echo "fn main() {}" > src/main.rs
RUN cargo build --release
COPY backend/src ./src
RUN touch src/main.rs
RUN cargo build --release
RUN strip target/release/backend

# Runtime
FROM alpine:latest
COPY --from=backend /backend/target/release/backend ./dockadmin
COPY --from=frontend /ui/dist ./ui
EXPOSE 3000
CMD ["./dockadmin"]
```

It’s a straightforward multi-stage build that compiles the frontend, compile the backend, and copy both into a minimal runtime container. Stripping debug symbols trims the binary further, and the final image starts quickly and uses very little memory.

## The Frontend Stack

The UI is built with **React 19**, **TypeScript**, and **shadcn/ui** components on top of **Radix UI** and **Tailwind CSS**. Routing is handled by **TanStack Router**, and the SQL editor uses **CodeMirror 6**.

The goal was to make the interface feel like a tool you’d actually enjoy using, not just something functional. shadcn/ui helped a lot here because it provides polished components without forcing a rigid design system.

The frontend compiles into static files that the Rust backend serves directly, so there’s no separate frontend server at runtime.

## What You Can Do With It

Here's a quick rundown of the features in the current release (v0.1.0):

**Connect to Your Database**

Open `localhost:3000`, pick your database type, enter your credentials, and you're in. When running inside Docker Compose, you use the container name as the host (e.g., `postgres` or `mysql`). That's the whole auth flow. Your database credentials are your login, the same approach Adminer uses, and it works really well.

![Auth page](https://paper-attachments.dropboxusercontent.com/s_F7A81FD18698A2A0DAA2E49AE47E9EE5806BC2A0C98ACE1794ED3FBA3C1217AC_1771168431303_auth.png)

**Browse and Edit Data**

Click on any table and you'll see your data in a clean, paginated grid. You can scroll through records, and get a feel for what's in there.

Need to change or add something? Use the CRUD buttons to add, edit, or delete a row.

![CRUD operation](https://paper-attachments.dropboxusercontent.com/s_F7A81FD18698A2A0DAA2E49AE47E9EE5806BC2A0C98ACE1794ED3FBA3C1217AC_1771168583152_add_row.png)

**Create Tables Visually**

You can create new tables without writing any SQL. The table builder lets you define columns, set data types, and toggle constraints like primary key, not null, and unique. You can also set up foreign key relationships to other tables, including ON DELETE and ON UPDATE cascade rules.

![Create Table](https://paper-attachments.dropboxusercontent.com/s_F7A81FD18698A2A0DAA2E49AE47E9EE5806BC2A0C98ACE1794ED3FBA3C1217AC_1771168634065_create_table.png)

**Explore Your Schema**

The schema viewer gives you a quick look at any table's structure. You can check the column names, data types, constraints, and foreign key relationships. It's handy when you need to understand how a database is set up without digging through migration files.

![Schema view](https://paper-attachments.dropboxusercontent.com/s_F7A81FD18698A2A0DAA2E49AE47E9EE5806BC2A0C98ACE1794ED3FBA3C1217AC_1771168698838_schema_view.png)

**Write Raw SQL**

For those times when a UI just won't cut it, there's a built-in SQL editor powered by CodeMirror. It has syntax highlighting, and you can run any query and see results right there. Great for quick debugging, running one-off scripts, or testing complex queries.

![SQL Editor](https://paper-attachments.dropboxusercontent.com/s_F7A81FD18698A2A0DAA2E49AE47E9EE5806BC2A0C98ACE1794ED3FBA3C1217AC_1771168745174_sql_editor.png)

## What I learned Building It

Supporting multiple databases consistently was harder than expected. Postgres, MySQL, and SQLite all expose schema information differently. Listing tables, reading constraints, handling relationships. Each database has its own quirks, and building one abstraction layer across all of them required more edge-case handling than I initially planned.

Docker image optimization was another learning curve. The first image I built was over 100 MB. Getting it down to around 15 MB involved multi-stage builds, Alpine base images, dependency caching, and stripping the binary. Each change helped a little, but together they made a huge difference.

I also learned how important open-source infrastructure is from the beginning. Issue templates, contribution guides, CI/CD pipelines, and automated workflows take time to set up, but they make collaboration much smoother once people start contributing.

## What’s Next

DockAdmin is currently in active development, and there’s a clear roadmap:

- Data export to SQL and CSV
- File import
- Full-text search
- Multi-database sessions

These are all areas where community feedback and contributions can shape what it becomes.

## Try It Out

You can run DockAdmin in seconds:

```bash
docker run -p 3000:3000 demlabz/dockadmin
```

Or add it to your Docker Compose setup:

```yaml
dockadmin:
    image: demlabz/dockadmin
    ports:
        - '3000:3000'
```

The project is open source under MIT and available on [GitHub](https://github.com/Mr-Malomz/dockadmin).

If you find it useful, star the [repo](https://github.com/Mr-Malomz/dockadmin). If something breaks, open an [issue](https://github.com/Mr-Malomz/dockadmin/issues). And if you want to contribute, check the [good-first-issue](https://github.com/Mr-Malomz/dockadmin/issues?q=is%3Aissue%20state%3Aopen%20label%3A%22good%20first%20issue%22) label and the contributing guide.

The stack is Rust and React, so there’s plenty to explore on either side.

Thanks for reading.


DockAdmin is a lightweight, modern database admin UI that runs as a Docker container. It supports PostgreSQL, MySQL, and SQLite. The entire image is ~15MB.

#Docker

From Manual Deploys to GitOps: How I Automated my Homelab with ArgoCD and GitLab CI

I Built a Docker-Native Database Admin UI in Rust. Here’s Why.