{"id":13577126,"url":"https://github.com/ehazlett/stellar","last_synced_at":"2025-05-16T18:06:17.555Z","repository":{"id":96541267,"uuid":"136054307","full_name":"ehazlett/stellar","owner":"ehazlett","description":"Simplified Container System","archived":false,"fork":false,"pushed_at":"2022-09-02T12:25:52.000Z","size":11001,"stargazers_count":1141,"open_issues_count":16,"forks_count":33,"subscribers_count":22,"default_branch":"main","last_synced_at":"2025-04-12T16:54:18.692Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":"","language":"Go","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/ehazlett.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":null,"support":null,"governance":null,"roadmap":null,"authors":null}},"created_at":"2018-06-04T16:38:18.000Z","updated_at":"2025-03-20T08:54:21.000Z","dependencies_parsed_at":null,"dependency_job_id":"6dc5683d-97d4-4df7-9c92-78f0f71e0fda","html_url":"https://github.com/ehazlett/stellar","commit_stats":null,"previous_names":[],"tags_count":2,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ehazlett%2Fstellar","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ehazlett%2Fstellar/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ehazlett%2Fstellar/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ehazlett%2Fstellar/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/ehazlett","download_url":"https://codeload.github.com/ehazlett/stellar/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":254582904,"owners_count":22095518,"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","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":[],"created_at":"2024-08-01T15:01:18.284Z","updated_at":"2025-05-16T18:06:17.534Z","avatar_url":"https://github.com/ehazlett.png","language":"Go","funding_links":[],"categories":["Go","others"],"sub_categories":[],"readme":"```\n   _____ __       ____\n  / ___// /____  / / /___ ______\n  \\__ \\/ __/ _ \\/ / / __ `/ ___/\n ___/ / /_/  __/ / / /_/ / /\n/____/\\__/\\___/_/_/\\__,_/_/\n\n```\n\nSimplified Container Runtime Cluster\n\nStellar is designed to provide simple container runtime clustering.  One\nor more nodes are joined together to create a cluster.  The cluster\nis eventually consistent making it ideal for transient workloads or edge\ncomputing where nodes are not always guaranteed to have high bandwidth, low\nlatency connectivity.\n\n# Why\nThere are several container platforms and container orchestrators out there.\nHowever, they are too complex for my use.  I like simple infrastructure that\nis easy to deploy and manage, tolerates failure cases and is easy to debug\nwhen needed.  With the increased tolerance in failure modes, this comes at\na consistency cost.  It may not be for you.  Use the best tool for your use\ncase.  Enjoy :)\n\n# Features\n\n- Container execution via [containerd](https://github.com/containerd/containerd)\n- Multihost Networking via [CNI](https://github.com/containernetworking/cni)\n- Service Discovery via DNS\n- Cluster event system via [NATS](https://github.com/nats-io/gnatsd)\n- Builtin Proxy using [Radiant](https://github.com/stellarproject/radiant) (zero downtime reloads, canary deploys, health checks, automatic HTTPS)\n- Masterless design\n- Efficient use of system resources\n- Simple daemon deployment\n\n# Downloads\nFor official releases, see the [Releases](https://github.com/ehazlett/stellar/releases)\n\nYou can also grab the latest [Master Build](https://s3.us-east-2.amazonaws.com/stellar-release/latest/stellar-linux-amd64.tar.gz)\n\n# Building\nIn order to build Stellar you will need the following:\n\n- A [working Go environment](https://golang.org/doc/code.html) (1.11+)\n- Protoc 3.x compiler and headers (download at the [Google releases page](https://github.com/google/protobuf/releases))\n\nOnce you have the requirements you can build.\n\nIf you change / update the protobuf definitions you will need to generate:\n\n`make generate`\n\nTo build the binaries (client and server) run:\n\n`make`\n\n## Docker\nAlternatively you can use [Docker](https://www.docker.com) to build:\n\nTo generate protobuf:\n\n`make docker-generate`\n\nTo build binaries:\n\n`make docker-build`\n\n# Running\nTo run Stellar, once you have a working containerd installation follow these steps:\n\n- Install [Containerd](https://github.com/containerd/containerd#getting-started) version \u003e=1.1\n- Build binaries or get a release\n- Copy `/bin/sctl` to `/usr/local/bin/`\n- Copy `/bin/stellar` to `/usr/local/bin/`\n- Copy `/bin/stellar-cni-ipam` to `/opt/containerd/bin/` or `/opt/cni/bin`\n\nFirst, we will generate a config:\n\n```\n$\u003e stellar config \u003e stellar.conf\n```\n\nThis will produce a default configuration.  Edit the addresses to match your environment.  For\nthis example we will use the IP `10.0.1.70`.\n\n```\n{\n    \"ConnectionType\": \"local\",\n    \"ClusterAddress\": \"10.0.1.70:7946\",\n    \"AdvertiseAddress\": \"10.0.1.70:7946\",\n    \"Debug\": false,\n    \"NodeID\": \"dev\",\n    \"GRPCAddress\": \"10.0.1.70:9000\",\n    \"TLSServerCertificate\": \"\",\n    \"TLSServerKey\": \"\",\n    \"TLSClientCertificate\": \"\",\n    \"TLSClientKey\": \"\",\n    \"TLSInsecureSkipVerify\": false,\n    \"ContainerdAddr\": \"/run/containerd/containerd.sock\",\n    \"Namespace\": \"default\",\n    \"DataDir\": \"/var/lib/stellar\",\n    \"StateDir\": \"/run/stellar\",\n    \"Bridge\": \"stellar0\",\n    \"UpstreamDNSAddr\": \"8.8.8.8:53\",\n    \"ProxyHTTPPort\": 80,\n    \"ProxyHTTPSPort\": 443,\n    \"ProxyTLSEmail\": \"\",\n    \"GatewayAddress\": \"127.0.0.1:9001\",\n    \"EventsAddress\": \"10.0.1.70:4222\",\n    \"EventsClusterAddress\": \"10.0.1.70:5222\",\n    \"EventsHTTPAddress\": \"10.0.1.70:4322\",\n    \"CNIBinPaths\": [\n        \"/opt/containerd/bin\",\n        \"/opt/cni/bin\"\n    ],\n    \"Peers\": [],\n    \"Subnet\": \"172.16.0.0/12\"\n}\n```\n\nTo start the initial node run:\n\n```\n$\u003e stellar -D server --config stellar.conf\n```\n\nTo join additional nodes simply add the `AdvertiseAddress` of the first node to the `Peers`\nconfig option of the second node:\n\nFor example:\n\n```\n{\n    \"ConnectionType\": \"local\",\n    \"ClusterAddress\": \"10.0.1.71:7946\",\n    \"AdvertiseAddress\": \"10.0.1.71:7946\",\n    \"Debug\": false,\n    \"NodeID\": \"dev\",\n    \"GRPCAddress\": \"10.0.1.71:9000\",\n    \"TLSServerCertificate\": \"\",\n    \"TLSServerKey\": \"\",\n    \"TLSClientCertificate\": \"\",\n    \"TLSClientKey\": \"\",\n    \"TLSInsecureSkipVerify\": false,\n    \"ContainerdAddr\": \"/run/containerd/containerd.sock\",\n    \"Namespace\": \"default\",\n    \"DataDir\": \"/var/lib/stellar\",\n    \"StateDir\": \"/run/stellar\",\n    \"Bridge\": \"stellar0\",\n    \"UpstreamDNSAddr\": \"8.8.8.8:53\",\n    \"ProxyHTTPPort\": 80,\n    \"ProxyHTTPSPort\": 443,\n    \"ProxyTLSEmail\": \"\",\n    \"GatewayAddress\": \"127.0.0.1:9001\",\n    \"EventsAddress\": \"10.0.1.71:4222\",\n    \"EventsClusterAddress\": \"10.0.1.71:5222\",\n    \"EventsHTTPAddress\": \"10.0.1.71:4322\",\n    \"CNIBinPaths\": [\n        \"/opt/containerd/bin\",\n        \"/opt/cni/bin\"\n    ],\n    \"Peers\": [\"10.0.1.70:7946\"],\n    \"Subnet\": \"172.16.0.0/12\"\n}\n```\n\nYou will now have a two node cluster.  To see node information, use `sctl`.\n\n```\n$\u003e sctl --addr 10.0.1.70:9000 cluster nodes\nNAME                ADDR                OS                       UPTIME              CPUS                MEMORY (USED)\nstellar-00          10.0.1.70:9000      Linux (4.17.0-3-amd64)   7 seconds           2                   242 MB / 2.1 GB\nstellar-01          10.0.1.71:9000      Linux (4.17.0-3-amd64)   6 seconds           2                   246 MB / 2.1 GB\n```\n\n# Deploying an Application\nTo deploy an application, create an application config.  For example, create the following as `example.conf`:\n\n```json\n{\n    \"name\": \"example\",\n    \"labels\": [\n        \"env=prod\",\n        \"region=us-east\"\n    ],\n    \"services\": [\n        {\n            \"name\": \"redis\",\n            \"image\": \"docker.io/library/redis:alpine\",\n            \"runtime\": \"io.containerd.runtime.v1.linux\",\n            \"process\": {\n                \"uid\": 0,\n                \"gid\": 0,\n                \"args\": [\"redis-server\"]\n            },\n            \"labels\": [\n                \"env=prod\"\n            ],\n            \"network\": true\n        }\n    ]\n}\n\n```\n\nThen run the following to deploy:\n\n```\n$\u003e sctl --addr 10.0.1.70:9000 apps create -f ./example.conf\n```\n\nYou should now see the application deployed:\n\n```\n$\u003e sctl --addr 10.0.1.70:9000 apps list\nNAME                SERVICES\nexample             1\n\n$\u003e sctl --addr 10.0.1.70:9000 apps inspect example\nName: example\nServices:\n  - Name: example.redis\n    Image: docker.io/library/redis:alpine\n    Runtime: io.containerd.runtime.v1.linux\n    Snapshotter: overlayfs\n    Labels:\n      containerd.io/restart.status=running\n      stellar.io/application=example\n      stellar.io/network=true\n\n```\n\nBy default all applications that have networking enabled will have a corresponding nameserver record\ncreated.  To view the records use the following:\n\n```\n$\u003e sctl --addr 10.0.1.70:9000 nameserver list\nNAME                    TYPE                VALUE                                            OPTIONS\nexample.redis.stellar   A                   172.16.0.4\nexample.redis.stellar   TXT                 node=stellar-00; updated=2018-09-08T10:71:02-04:00\n```\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fehazlett%2Fstellar","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fehazlett%2Fstellar","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fehazlett%2Fstellar/lists"}