{"id":24737706,"url":"https://github.com/simplecontainer/smr","last_synced_at":"2025-10-10T06:31:54.733Z","repository":{"id":231604758,"uuid":"782181728","full_name":"simplecontainer/smr","owner":"simplecontainer","description":"Simplecontainer manager a.k.a smr. Standalone and cluster mode, GitOps, Secrets, Reconciliation, and YAML definitions for Docker. ","archived":false,"fork":false,"pushed_at":"2025-10-02T21:02:56.000Z","size":3386,"stargazers_count":71,"open_issues_count":1,"forks_count":1,"subscribers_count":2,"default_branch":"main","last_synced_at":"2025-10-02T21:24:23.498Z","etag":null,"topics":["cluster","containers","docker","flannel","gitops","orchestration","overlay","simplecontainer"],"latest_commit_sha":null,"homepage":"https://simplecontainer.io","language":"Go","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"gpl-3.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/simplecontainer.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":"SECURITY.md","support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null},"funding":{"github":"simplecontainer","patreon":null,"open_collective":null,"ko_fi":null,"tidelift":null,"community_bridge":null,"liberapay":null,"issuehunt":null,"lfx_crowdfunding":null,"polar":null,"buy_me_a_coffee":null,"thanks_dev":null,"custom":null}},"created_at":"2024-04-04T19:48:08.000Z","updated_at":"2025-10-02T21:02:59.000Z","dependencies_parsed_at":"2024-06-29T12:31:00.935Z","dependency_job_id":"dcd1d41a-7951-4e01-9ea4-eb5fb80ee406","html_url":"https://github.com/simplecontainer/smr","commit_stats":null,"previous_names":["qdnqn/smr","simplecontainer/smr"],"tags_count":283,"template":false,"template_full_name":null,"purl":"pkg:github/simplecontainer/smr","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/simplecontainer%2Fsmr","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/simplecontainer%2Fsmr/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/simplecontainer%2Fsmr/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/simplecontainer%2Fsmr/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/simplecontainer","download_url":"https://codeload.github.com/simplecontainer/smr/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/simplecontainer%2Fsmr/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":279002966,"owners_count":26083489,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","status":"online","status_checked_at":"2025-10-10T02:00:06.843Z","response_time":62,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["cluster","containers","docker","flannel","gitops","orchestration","overlay","simplecontainer"],"created_at":"2025-01-27T22:09:07.567Z","updated_at":"2025-10-10T06:31:54.728Z","avatar_url":"https://github.com/simplecontainer.png","language":"Go","funding_links":["https://github.com/sponsors/simplecontainer"],"categories":["Go"],"sub_categories":[],"readme":"# Simplecontainer\n[![Quality Gate Status](https://sonarcloud.io/api/project_badges/measure?project=simplecontainer_smr\u0026metric=alert_status)](https://sonarcloud.io/summary/new_code?id=simplecontainer_smr)\n[![Go Report Card](https://goreportcard.com/badge/github.com/simplecontainer/smr)](https://goreportcard.com/report/github.com/simplecontainer/smr)\n[![OpenSSF Best Practices](https://www.bestpractices.dev/projects/10512/badge)](https://www.bestpractices.dev/projects/10512)\n\n![Simplecontainer GitOps](.github/resources/simplecontainer-gitops-promo.png)\n\n## Quickest start\n\u003e [!IMPORTANT]\n\u003e ⚠️️ Don't run `smrmgr start` as root. It will not work. Ensure that non-root user has access to the `/var/run/docker.sock`.\n\n\n```cgo\ncurl -sL https://smrmgr.simplecontainer.io/ -o smrmgr\nchmod +x smrmgr\nsudo mv smrmgr /usr/local/bin\nsudo smrmgr install\nsmrmgr start\n```\nVerify installation:\n```\nsmrctl ps\nNODE         RESOURCE                             PORTS IMAGE STATE ENGINE STATE     SMR STATE        \n──────────────────────────────────────────────────────────────────────────────────────────────────────\n```\n\n## Overview\n\nSetting up orchestrator on top of docker nodes in seconds with simplecontainer. Control and orchestrate docker daemons like a professional.\n\nSimplecontainer is a container orchestration platform that transforms Docker daemons into managed nodes with GitOps capabilities.\nIt provides enterprise-grade features like overlay networking, secrets management, and multi-node clustering while maintaining the simplicity of Docker management.\n\n### Key Features\n\n- **GitOps Deployment**: Deploy containers using Git repositories as the source of truth\n- **Bidirectional GitOps Controller**: Gitops controller enables interface for applying patches to the git\n- **Overlay Networking**: Secure container communication using Flannel with WireGuard encryption\n- **Multi-Node Clustering**: Scale across multiple Docker daemons with RAFT consensus\n- **Dependency Management**: Reliable container startup ordering with readiness probes\n- **Secrets \u0026 Configuration**: Built-in secret and configuration management\n- **mTLS Security**: Encrypted control plane communication\n- **Real-time Dashboard**: Web UI for monitoring and management\n\n## Quick Start\n\n### Prerequisites\n\n- Docker installed and running ([Installation Guide](https://docs.docker.com/engine/install/))\n- For WireGuard networking: WireGuard package ([Installation Guide](https://www.wireguard.com/install/))\n\n### Installation\n\n1. **Download and install tooling(smrmgr.sh, smr, and smrctl):**\n\n```bash\ncurl -sL https://smrmgr.simplecontainer.io/ -o smrmgr\nchmod +x smrmgr\nsudo mv smrmgr /usr/local/bin\nsudo smrmgr install\n```\n\n2. **Start a single node with default configuration:**\n\n\u003e [!IMPORTANT]\n\u003e ⚠️️ Don't run this command as root. It will not work. Ensure that non-root user has access to the `/var/run/docker.sock`.\n\n```bash\nsmrmgr start\n```\n\n3. **Use the CLI client:**\n\n```bash\nsmrctl ps\nNODE         RESOURCE                             PORTS IMAGE STATE ENGINE STATE     SMR STATE        \n──────────────────────────────────────────────────────────────────────────────────────────────────────\n```\n\n### Running dashboard\n\nAfter starting node, dashboard can be started on the local machine.\n\nDashboard 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.\n\n### Localhost\nAdd these to /etc/hosts file:\n\n```\n127.0.0.1 authentik.dashboard.localhost\n127.0.0.1 proxy.dashboard.localhost\n127.0.0.1 api.dashboard.localhost\n127.0.0.1 dashboard.localhost\n```\n\nAfter that run:\n\n```\nsmrctl pack pull simplecontainer/dashboard:0.0.1\nmkcert dashboard.localhost proxy.dashboard.localhost api.dashboard.localhost authentik.dashboard.localhost\nsmrctl apply simplecontainer/dashboard --set user=$USER --set traefik.certificate=\"$(cat dashboard.localhost+3.pem)\" --set traefik.key=\"$(cat dashboard.localhost+3-key.pem)\"\n```\n\nThat's it. This pack runs:\n\n- Authentik\n- Postgres\n- Traefik\n- Dashboard\n- Proxy-manager\n\n- Just access https://dashboard.locahost and you should see the login form.\n\n\u003e [!IMPORTANT]\n\u003e ⚠️️ Authentik user needs to be setup first. Visit https://authentik.dashboard.localhost/if/flows/initial-setup to create an admin user.\n\nAfter applying dashboard pack, success of the deployment can be verified:\n\n```\nsmrctl ps\nNODE                    RESOURCE                                            IMAGE                                                      PORTS                 ENGINE STATE      SMR STATE     \nsmr-development-node-1  containers/authentik/authentik-authentik-worker-1   ghcr.io/goauthentik/server:latest (pulled)                 -                     running (docker)  running (1s)  \nsmr-development-node-1  containers/authentik/authentik-authentik-1          ghcr.io/goauthentik/server:latest (pulled)                 9000                  running (docker)  running (1s)  \nsmr-development-node-1  containers/authentik/authentik-pg-1                 postgres:15 (pulled)                                       -                     running (docker)  running (1s)  \nsmr-development-node-1  containers/authentik/authentik-redis-1              redis:alpine (pulled)                                      -                     running (docker)  running (1s)  \nsmr-development-node-1  containers/dashboard/dashboard-dashboard-oss-1      quay.io/simplecontainer/dashboard-oss:latest (pulled)      3000                  running (docker)  running (1s)  \nsmr-development-node-1  containers/dashboard/dashboard-proxy-manager-oss-1  quay.io/simplecontainer/proxy-manager-oss:latest (pulled)  5443, 5480            running (docker)  running (1s)  \nsmr-development-node-1  containers/traefik/traefik-traefik-1                traefik:v3.5.0 (pulled)                                    80:80, 443:443, 8080  running (docker)  running (1s)  \n```\n\n\n![Simplecontainer Containers](.github/resources/containers.png)\n![Simplecontainer GitOps](.github/resources/gitops.png)\n\n### Deploy First Container\n\nDeploy a basic container definition on Docker using simplecontainer:\n\n```bash\nsmrctl apply https://raw.githubusercontent.com/simplecontainer/examples/refs/heads/main/tests/minimal/definitions/Containers.yaml\nsmrctl ps\n```\n\nExpected output:\n```\nNODE                    RESOURCE                              PORTS  DEPS  ENGINE STATE      SMR STATE     \nsimplecontainer-node  containers/example/example-busybox-1  -      -     running (docker)  running (9s)  \n```\n\n## Architecture\n\nSimplecontainer supports three deployment modes:\n\n1. **Single Node**: Standalone Docker daemon management\n2. **Multiple Isolated Nodes**: Independent Simplecontainer instances\n3. **Clustered Nodes**: Distributed container orchestration\n\n### Core Components\n\n- **Control Plane**: REST API for container management (port 1443)\n- **RAFT Consensus**: Distributed state management (port 9212)\n- **Embedded etcd**: Local key-value store (port 2379, localhost only)\n- **Flannel Networking**: Overlay network with WireGuard encryption\n- **DNS Server**: Isolated DNS resolution for containers\n\n## Deployment Modes\n\n### Single Node Deployment\n\n#### Localhost Access Only\n```bash\nsmrmgr start\n```\n\n#### External Access\nReplace `smr.example.com` with your domain:\n\n```bash\nsmrmgr start -d smr.example.com\nsmrctl context export --api smr.example.com:1443\n```\n\nFrom external machines:\n```bash\nsmrctl context import PASTE_EXPORTED_CONTEXT_HERE\nsmrctl ps\n```\n\n### Cluster Deployment\n\n#### Node 1 (Cluster Leader)\n```bash\nsmrmgr start -d smr-1.example.com\nsmrctl context export --api smr-1.example.com:1443\n```\n\n#### Node 2+ (Joining Nodes)\n\u003e [!IMPORTANT]\n\u003e ⚠️️ The smr binary is importing context not the smrctl!\n\n```bash\nsmr agent import -y PASTE_EXPORTED_OUTPUT\nsmrmgr start -d smr-2.example.com -j\n```\n\n## Container Management\n\nSimplecontainer uses YAML definitions to manage containers and related resources:\n\n### Core Objects\n\n- **Containers**: Define container specifications\n- **Configuration**: Application configuration management\n- **Secrets**: Secure credential storage\n- **Resources**: Shared resources between containers\n- **GitOps**: Git-based deployment automation\n- **CertKey**: TLS certificate management\n- **HttpAuth**: HTTP authentication configuration\n\n### GitOps Workflow\n\n1. **Create GitOps definition:**\n\n```bash\nsmrctl apply https://raw.githubusercontent.com/simplecontainer/examples/refs/heads/main/tests/gitops-apps/definitions/gitops-plain.yaml\n```\n\n2. **Check GitOps status:**\n\n```bash\nsmrctl ps gitops\n```\n\n3. **Trigger synchronization:**\n\n```bash\nsmrctl sync gitops/examples/plain-manual\n```\n\n4. **Verify deployment:**\n\n```bash\nsmrctl ps\n```\n\n### Direct Application Deployment\n\nFor immediate deployment without GitOps:\n\n```bash\ngit clone https://github.com/simplecontainer/examples\nsmrctl apply examples/tests/dependency-readiness-simple\n```\n\nThis example demonstrates:\n- Secret management\n- Configuration handling\n- Resource sharing\n- Container dependencies\n- Readiness checks\n\n## Advanced Features\n\n### Dependency Management\n\nContainers can depend on other containers being ready:\n\n```yaml\ndependencies:\n  - prefix: \"simplecontainer.io/v1\"\n    group: \"mysql\"\n    name: \"*\" # Wildcard to wait for all replicas\n```\n\nO\n\n```yaml\ndependencies:\n  - prefix: \"simplecontainer.io/v1\"\n    group: \"mysql\"\n    name: \"mysql-mysql-1\" # wait for specific replica\n```\n\n### Readiness Probes\n\nEnsure containers are ready before marking them as available:\n\n```yaml\nspec:\n  readiness:\n    - name: \"mysql\"\n      timeout: \"60s\"\n      command: [\"mysqladmin\", \"ping\", \"-h\", \"localhost\", \"-p(( .password ))\"]\n```\n\n### Server-Side Rendering\n\nUse secrets and configuration in container definitions:\n\n```yaml\nspec:\n  configuration:\n      username: \"root\"\n      password: (( lookup \"secret/mysql/password:password\" | base64decode ))\n```\n\n## Network Ports\n\n- **1443**: Control plane API (TCP)\n- **9212**: RAFT protocol communication (TCP)\n- **2379**: Embedded etcd (localhost only)\n\n## Command Reference\n\n### Basic Commands\n\n```bash\n# List all containers\nsmrctl ps\n\n# List specific resource types\nsmrctl ps gitops | smrctl gitops\nsmrctl ps secrets | smrctl containers\n\n# Get detailed information\nsmrctl get containers/example/busybox-1\n\n# Apply definitions\nsmrctl apply \u003cfile_or_url\u003e\n\n# Sync GitOps resources\nsmrctl sync gitops/example/app\n\n# Import/export contexts\nsmrctl context import \u003ccontext_string\u003e\nsmrctl context export\n```\n\n### Management Commands\n\n```bash\n# Start node\nsmrmgr start [options]\n\n# Install tools\nsmrmgr install\n\n# Export agent context\nsmr agent export --api \u003cendpoint\u003e\n\n# Import agent context\nsmr agent import --node \u003cname\u003e -y \u003ccontext\u003e\n```\n\n## Troubleshooting\n\n### Common Issues\n\n1. **WireGuard not installed**: Install WireGuard package for secure networking\n2. **Port conflicts**: Ensure ports 1443, 9212, and 2379 are available\n3. **Docker socket access**: Simplecontainer needs access to `/var/run/docker.sock`\n4. **Firewall**: Open required ports for cluster communication\n\n### Logs and Debugging\n\n```bash\n# View container logs\nsmr node logs OR docker logs \u003csimplecontainer_container_id\u003e\n\n# Verify cluster connectivity\nsmrctl ps\n```\n\n## Resources\n\n- **Managed infrastructure**: [app.simplecontainer.io](https://app.simplecontainer.io)\n- **Dashboard**: [github.com/simplecontainer/dashboard](https://github.com/simplecontainer/dashboard)\n- **Documentation**: [docs.simplecontainer.io](https://docs.simplecontainer.io)\n- **Blog**: [blog.simplecontainer.io](https://blog.simplecontainer.io)\n- **Container Registry**: [quay.io/repository/simplecontainer/smr](https://quay.io/repository/simplecontainer/smr)\n- **Source Code**: [github.com/simplecontainer/smr](https://github.com/simplecontainer/smr)\n- **Dashboard**: [github.com/simplecontainer/smr](https://github.com/simplecontainer/dashboard)\n- **Examples**: [github.com/simplecontainer/examples](https://github.com/simplecontainer/examples)\n\n## Contributing\n\nWe welcome contributions! Please see our contributing guidelines and code of conduct.\n\n## License\n\nThis project is licensed under the GNU General Public License v3.0. See the [LICENSE](LICENSE) file for details.","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsimplecontainer%2Fsmr","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fsimplecontainer%2Fsmr","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsimplecontainer%2Fsmr/lists"}