Smr
Simplecontainer is a lightweight and secure runtime and orchestration layer for isolated container workloads, built for edge and cloud.
Install / Use
/learn @simplecontainer/SmrREADME
Simplecontainer
Quickest start
[!IMPORTANT] ⚠️️ Don't run
smrmgr startas root. It will not work. Ensure that non-root user has access to the/var/run/docker.sock.
curl -sL https://smrmgr.simplecontainer.io/ -o smrmgr
chmod +x smrmgr
sudo mv smrmgr /usr/local/bin
sudo smrmgr install
smrmgr start
Verify installation:
smrctl ps
NODE RESOURCE PORTS IMAGE STATE ENGINE STATE SMR STATE
──────────────────────────────────────────────────────────────────────────────────────────────────────
Overview
Setting up orchestrator on top of docker nodes in seconds with simplecontainer. Control and orchestrate docker daemons like a professional.
Simplecontainer is a container orchestration platform that transforms Docker daemons into managed nodes with GitOps capabilities. It provides enterprise-grade features like overlay networking, secrets management, and multi-node clustering while maintaining the simplicity of Docker management.
Key Features
- GitOps Deployment: Deploy containers using Git repositories as the source of truth
- Bidirectional GitOps Controller: Gitops controller enables interface for applying patches to the git
- Overlay Networking: Secure container communication using Flannel with WireGuard encryption
- Multi-Node Clustering: Scale across multiple Docker daemons with RAFT consensus
- Dependency Management: Reliable container startup ordering with readiness probes
- Secrets & Configuration: Built-in secret and configuration management
- mTLS Security: Encrypted control plane communication
- Real-time Dashboard: Web UI for monitoring and management
Quick Start
Prerequisites
- Docker installed and running (Installation Guide)
- For WireGuard networking: WireGuard package (Installation Guide)
Installation
- Download and install tooling(smrmgr.sh, smr, and smrctl):
curl -sL https://smrmgr.simplecontainer.io/ -o smrmgr
chmod +x smrmgr
sudo mv smrmgr /usr/local/bin
sudo smrmgr install
- Start a single node with default configuration:
[!IMPORTANT] ⚠️️ Don't run this command as root. It will not work. Ensure that non-root user has access to the
/var/run/docker.sock.
smrmgr start
- Use the CLI client:
smrctl ps
NODE RESOURCE PORTS IMAGE STATE ENGINE STATE SMR STATE
──────────────────────────────────────────────────────────────────────────────────────────────────────
Running dashboard
After starting node, dashboard can be started on the local machine.
Dashboard comes as container package (Pack) that makes running it easy. You can use the already available Dashboard pack to install it and run it directly on the Simplecontainer node.
Localhost
Add these to /etc/hosts file:
127.0.0.1 authentik.dashboard.localhost
127.0.0.1 proxy.dashboard.localhost
127.0.0.1 api.dashboard.localhost
127.0.0.1 dashboard.localhost
After that run:
smrctl pack pull simplecontainer/dashboard:0.0.1
mkcert dashboard.localhost proxy.dashboard.localhost api.dashboard.localhost authentik.dashboard.localhost
smrctl apply simplecontainer/dashboard --set user=$USER --set traefik.certificate="$(cat dashboard.localhost+3.pem)" --set traefik.key="$(cat dashboard.localhost+3-key.pem)"
That's it. This pack runs:
-
Authentik
-
Postgres
-
Traefik
-
Dashboard
-
Proxy-manager
-
Just access https://dashboard.locahost and you should see the login form.
[!IMPORTANT] ⚠️️ Authentik user needs to be setup first. Visit https://authentik.dashboard.localhost/if/flows/initial-setup to create an admin user.
After applying dashboard pack, success of the deployment can be verified:
smrctl ps
NODE RESOURCE IMAGE PORTS ENGINE STATE SMR STATE
smr-development-node-1 containers/authentik/authentik-authentik-worker-1 ghcr.io/goauthentik/server:latest (pulled) - running (docker) running (1s)
smr-development-node-1 containers/authentik/authentik-authentik-1 ghcr.io/goauthentik/server:latest (pulled) 9000 running (docker) running (1s)
smr-development-node-1 containers/authentik/authentik-pg-1 postgres:15 (pulled) - running (docker) running (1s)
smr-development-node-1 containers/authentik/authentik-redis-1 redis:alpine (pulled) - running (docker) running (1s)
smr-development-node-1 containers/dashboard/dashboard-dashboard-oss-1 quay.io/simplecontainer/dashboard-oss:latest (pulled) 3000 running (docker) running (1s)
smr-development-node-1 containers/dashboard/dashboard-proxy-manager-oss-1 quay.io/simplecontainer/proxy-manager-oss:latest (pulled) 5443, 5480 running (docker) running (1s)
smr-development-node-1 containers/traefik/traefik-traefik-1 traefik:v3.5.0 (pulled) 80:80, 443:443, 8080 running (docker) running (1s)
Deploy First Container
Deploy a basic container definition on Docker using simplecontainer:
smrctl apply https://raw.githubusercontent.com/simplecontainer/examples/refs/heads/main/tests/minimal/definitions/Containers.yaml
smrctl ps
Expected output:
NODE RESOURCE PORTS DEPS ENGINE STATE SMR STATE
simplecontainer-node containers/example/example-busybox-1 - - running (docker) running (9s)
Architecture
Simplecontainer supports three deployment modes:
- Single Node: Standalone Docker daemon management
- Multiple Isolated Nodes: Independent Simplecontainer instances
- Clustered Nodes: Distributed container orchestration
Core Components
- Control Plane: REST API for container management (port 1443)
- RAFT Consensus: Distributed state management (port 9212)
- Embedded etcd: Local key-value store (port 2379, localhost only)
- Flannel Networking: Overlay network with WireGuard encryption
- DNS Server: Isolated DNS resolution for containers
Deployment Modes
Single Node Deployment
Localhost Access Only
smrmgr start
External Access
Replace smr.example.com with your domain:
smrmgr start -d smr.example.com
smrctl context export --api smr.example.com:1443
From external machines:
smrctl context import PASTE_EXPORTED_CONTEXT_HERE
smrctl ps
Cluster Deployment
Node 1 (Cluster Leader)
smrmgr start -d smr-1.example.com
smrctl context export --api smr-1.example.com:1443
Node 2+ (Joining Nodes)
[!IMPORTANT] ⚠️️ The smr binary is importing context not the smrctl!
smr agent import -y PASTE_EXPORTED_OUTPUT
smrmgr start -d smr-2.example.com -j
Container Management
Simplecontainer uses YAML definitions to manage containers and related resources:
Core Objects
- Containers: Define container specifications
- Configuration: Application configuration management
- Secrets: Secure credential storage
- Resources: Shared resources between containers
- GitOps: Git-based deployment automation
- CertKey: TLS certificate management
- HttpAuth: HTTP authentication configuration
GitOps Workflow
- Create GitOps definition:
smrctl apply https://raw.githubusercontent.com/simplecontainer/examples/refs/heads/main/tests/gitops-apps/definitions/gitops-plain.yaml
- Check GitOps status:
smrctl ps gitops
- Trigger synchronization:
smrctl sync gitops/examples/plain-manual
- Verify deployment:
smrctl ps
Direct Application Deployment
For immediate deployment without GitOps:
git clone https://github.com/simplecontainer/examples
smrctl apply examples/tests/dependency-readiness-simple
This example demonstrates:
- Secret management
- Configuration handling
- Resource sharing
- Container dependencies
- Readiness checks
Advanced Features
Dependency Management
Containers can depend on other containers being ready:
dependencies:
- prefix: "simplecontainer.io/v1"
group: "mysql"
name: "*" # Wildcard to wait for all replicas
Or
dependencies:
- prefix: "simplecontainer.io/v1"
group: "mysql"
name: "mysql-mysql-1" # wait for specific replica
Readiness Probes
Ensure containers are ready before marking them as available:
spec:
readiness:
- name: "mysql"
timeout: "60s"
command: ["mysqladmin", "ping", "-h", "localhost", "-p(( .password ))"]
Server-Side Rendering
Use secrets and configuration in container definitions:
spec:
configuration:
username: "root"
password: (( lookup "secret/mysql/password:password" | base64decode ))
Network Ports
- 1443: Control plane API (TCP)
- 9212: RAFT protocol communication (TCP)
- *2379
