Introduction

GitOps gained traction as it was introduced into the Kubernetes ecosystem via ArgoCD. ArgoCD is the current synonym for GitOps. To enable the GitOps pattern, the platform needs to allow declarative configuration of the entity. When mentioning a platform, it can refer to any platform that serves a purpose. GitOps existed long before Kubernetes, with various implementations of the pattern. ArgoCD, however, standardized the approach and introduced it to a wider audience.

Does it have to be only for Kubernetes? Absolutely not. Let's learn more about it.

What is GitOps?

GitOps is a pattern of managing state where state is defined, using a declarative way, in the git repository.

You have 3 elements:

• Git
• Definition
• Reconciler

How does it work? Definitions are stored in Git. A reconciler detects changes in the repository, compares them with the current platform state, and, when possible, applies the necessary updates to match the desired state. The reconciler is also responsible for tracking both the desired state and the current state on the platform, a process known as drift detection.

Why has it become so popular?

Managing a large number of servers, configurations, application deployments, and more can quickly become difficult to maintain cleanly. This challenge led to the evolution of the “X as Code” pattern, where “X” could represent infrastructure, application deployments, dashboards, configurations, etc.

And what better tool to manage textual changes than Git, a veteran in the field, battle-tested for decades.

Key Success Factors:

• Declarative definitions: clearly state the desired state of your system.
• Git for change management: track and version textual changes easily.
• Reconciler: implements the desired changes and acts as a watchdog to detect and correct drift.
• Visualizations: provide clear representations of all entities managed by the reconciler.
• Kubernetes popularity: widespread adoption of Kubernetes has accelerated the adoption of GitOps and “X as Code” practices.

Implementing GitOps outside of Kubernetes is appealing, but tooling is scarce right now. Implementing usually relies on custom tooling and glue to implement it correctly. The problem is the reconciler.

Docker GitOps with simplecontainer

Docker currently doesn't have a GitOps reconciler. The reason is simple: it relies on imperative deployments rather than declarative ones. This makes the situation a little tricky.

Docker Compose solves the problem of a declarative approach and enables users to write declarative definitions of container deployment using YAML. Docker Compose is used for single-node deployments, but it doesn't implement a reconciler for the GitOps approach. There are a few hobby projects in the wild that tried to implement a GitOps reconciler for Compose files.

Simplecontainer implements GitOps reconciler naturally as an integral part of its engine. While also using declarative orchestration of the containers, this GitOps implementation allows a similar experience to one user would have using ArgoCD on the Kubernetes.

Why use GitOps outside Kubernetes?

Kubernetes is a powerhouse for distributed container orchestration, offering a huge list of features. But with that power comes significant overhead: compute, memory, and engineering resources needed to maintain it.

For many projects, Kubernetes is overkill — it can easily overwhelm smaller teams or projects. At the same time, containers themselves are highly beneficial, and running them is straightforward.

The GitOps pattern is powerful, and it would be a shame not to leverage it outside of Kubernetes.

Why use simplecontainer?

To address these challenges, Simplecontainer was created. It provides a middle ground for teams seeking a Kubernetes-like experience while working directly with Docker. Maintenance is simplified, as it primarily focuses on managing the Docker system you already have in place.

What Simplecontainer Brings to the Table

• Runs as a container on top of Docker.
• Simple setup — get started quickly.
• Supports both single-node and multi-node clusters.
• Dynamic clustering — add or remove nodes while running.
• High availability — prevents single points of failure through replication.
• Integrated GitOps reconciler built directly into the engine.
• Ideal for small to medium projects and home labs.

With Simplecontainer, you can leverage:

• Declarative definitions similar to Docker Compose.
• Kubernetes-like features, including: GitOps workflows (ArgoCD-style), clustering, secrets and configuration management, container replication, and load balancing.
• All using technologies you already know, with new features that are simple to learn and use.

Setting Up Your Docker Cluster with simplecontainer.io

What is better than a video tutorial to show how to do it?

Or if you want a quick solution:

curl -sL https://raw.githubusercontent.com/simplecontainer/smr/refs/heads/main/scripts/production/smrmgr.sh -o smrmgr
chmod +x smrmgr
sudo mv smrmgr /usr/local/bin
sudo smrmgr install
smrmgr start

That's it. Really. Only prerequisites:

• Docker already running

Managing Deployments with GitOps

Declarative containers definition

We will reference existing examples located in the examples repository.

The definition below defines container deployment of busybox. This Pack can be applied directly, but the GitOps approach will enable all the features mentioned above.

prefix: simplecontainer.io/v1
kind: containers
meta:
  group: example
  name: busybox
spec:
  image: busybox
  tag: 1.37.0
  replicas: 1
  entrypoint: ["sleep"]
  args: ["3600"]

GitOps for Docker with simplecontainer

prefix: simplecontainer.io/v1
kind: gitops
meta:
  group: examples
  name: plain-auto
spec:
  repoURL: "https://github.com/simplecontainer/examples"
  revision: "main"
  automaticSync: true
  directoryPath: "/tests/minimal"

This GitOps object does automatic sync of the Pack located in the examples repository under the /tests/minimal path.

When this GitOps definition is applied to the simplecontainer node, GitOps next steps happens:

• GitOps reconciler clones the repository
• Path /tests/minimal is examined to check if it is a valid Pack, and all definitions are valid
• All definitions are applied in the correct order
• When external changes happen to the objects owned by the GitOps reconciler, they are immediately rechecked for drift
• Every N minutes, the git repository is polled for changes, and these are applied if changes are detected

This completely enables the GitOps pattern for the Docker containers. In the end, if you wish to run docker ps or another docker commands on the machine where simplecontainer is running, you can verify all these steps are working correctly.

A more detailed article about GitOps deployments is given below.

Deploy docker containers using GitOps approach

If you were searching for the tool like ArgoCD to implement GitOps pattern for Docker containers - you are on the right place. Simplecontainer enables the GitOps approach to deploying containers on single or cluster of docker daemon hosts with simplecontainer enabled nodes. This allows to pull the latest changes

blog.simplecontainerAdnan Selimovic

Incorporating GitOps into CI/CD

One more aspect of the GitOps controller of the simplecontainer is that it is bidirectional. What this means is that you can make changes to the Pack and apply commits to the repository.

This is a common approach where you want external pipelines to make changes in the Git repository to trigger reconcile to the changes. One example of this is building a new container image and pushing it to the repository. The problem remains: how to make updates to the definition files related to the deployment.

Simplecontainer offers a standardized way of solving this. The CI/CD pipeline only needs to have configured access to the control plane of the simplecontainer node. It falls down to import context via:

smrctl context import $ENCRYPTED_STRING $DECRYPTION_KEY
smrctl commit gitops/examples/plain-auto containers/example/busybox "spec: {tag: $CI_COMMIT_TAG}"

Assuming we have applied the GitOps object we mentioned before, this will update the containers definition above and will trigger reconciliation to the newest state. All while changes are already committed in the Git repository.

You can see a more detailed article about bidirectional GitOps reconciler on the link below.

Bidirectional GitOps controller for Docker with Simplecontainer

Reasoning GitOps mantra defines the Git repository as the source of the truth. GitOps controller tracks the changes on the Git repository and reconcile the state on the controlling receiving end. Usually controller implements health checking and drift detection to force the GitOps state if any manual change occurs. In

blog.simplecontainerAdnan Selimovic

Best Practices and Tips

Some tips and best practices:

• Leverage the GitOps App of Apps pattern: one GitOps definition to deploy other GitOps definitions
• If resources are critical, one can use one node to handle all GitOps reconciler while containers are deployed to another node or nodes
• Use bidirectional GitOps for CI/CD integration to have a standard and secure way of handling commits to the repositories
• Try out the dashboard to leverage GitOps visualizations

Check out how GitOps is visualized in this video.

Conclusion

Simplecontainer gives a lightweight solution to orchestrate Docker containers. The complexity of the setup is running a container on top of the Docker engine.

It brings out the GitOps pattern for containers outside of Kubernetes. With the Dashboard visualizations of the GitOps objects is also a thing. Completely new GitOps experience for container deployment - targeting also platforms that relies on Docker to run their systems. Be that on-prem, virtual machines, or cloud - it will work without any problem since it is platform agnostic.

It is easy to start with simplecontainer and take it out for a test ride. So you can conclude for yourself instead of us doing that for you.

If you find us interesting, you can drop a star on the GitHub project.

GitHub - simplecontainer/smr: Simplecontainer manager a.k.a smr. Standalone and cluster mode, GitOps, Secrets, Reconciliation, and YAML definitions for Docker.

Simplecontainer manager a.k.a smr. Standalone and cluster mode, GitOps, Secrets, Reconciliation, and YAML definitions for Docker. - GitHub - simplecontainer/smr: Simplecontainer manager a.k.a smr.…

GitHubsimplecontainer

Have you already tried simplecontainer? Want to write/promote your article related to the simplecontainer directly on our blog? Reach us at [email protected]