{"id":13471496,"url":"https://github.com/coreroller/coreroller","last_synced_at":"2025-03-26T13:31:11.668Z","repository":{"id":1727022,"uuid":"43284667","full_name":"coreroller/coreroller","owner":"coreroller","description":"CoreRoller is a set of tools to control and monitor the rollout of your updates.","archived":false,"fork":false,"pushed_at":"2022-12-06T18:04:00.000Z","size":10537,"stargazers_count":287,"open_issues_count":22,"forks_count":38,"subscribers_count":17,"default_branch":"master","last_synced_at":"2024-10-30T02:59:42.704Z","etag":null,"topics":["coreos","coreos-cluster","omaha"],"latest_commit_sha":null,"homepage":"","language":"Go","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"other","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/coreroller.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}},"created_at":"2015-09-28T06:49:03.000Z","updated_at":"2024-08-28T03:22:08.000Z","dependencies_parsed_at":"2023-01-13T16:22:18.481Z","dependency_job_id":null,"html_url":"https://github.com/coreroller/coreroller","commit_stats":null,"previous_names":[],"tags_count":7,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/coreroller%2Fcoreroller","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/coreroller%2Fcoreroller/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/coreroller%2Fcoreroller/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/coreroller%2Fcoreroller/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/coreroller","download_url":"https://codeload.github.com/coreroller/coreroller/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":245662832,"owners_count":20652091,"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":["coreos","coreos-cluster","omaha"],"created_at":"2024-07-31T16:00:45.850Z","updated_at":"2025-03-26T13:31:09.318Z","avatar_url":"https://github.com/coreroller.png","language":"Go","funding_links":[],"categories":["Go"],"sub_categories":[],"readme":"![Coreroller](https://github.com/coreroller/coreroller/raw/master/docs/screenshots/coreroller.png)\n\n[![Travis Widget]][Travis] [![GoReportCard Widget]][GoReportCard]\n\n[Travis]: https://travis-ci.org/coreroller/coreroller\n[Travis Widget]: https://travis-ci.org/coreroller/coreroller.svg?branch=master\n[GoReportCard]: https://goreportcard.com/report/coreroller/coreroller\n[GoReportCard Widget]: https://goreportcard.com/badge/coreroller/coreroller\n\n## Overview\n\n**CoreRoller** is a set of tools to control and monitor the rollout of your updates. It's aimed to be an open source alternative to CoreOS CoreUpdate.\n\nScreenshots:\n\n\u003ctable\u003e\n    \u003ctr\u003e\n        \u003ctd width=\"33%\"\u003e\u003cimg src=\"https://github.com/coreroller/coreroller/raw/master/docs/screenshots/screenshot1.png\"\u003e\u003c/td\u003e\n        \u003ctd width=\"33%\"\u003e\u003cimg src=\"https://github.com/coreroller/coreroller/raw/master/docs/screenshots/screenshot2.png\"\u003e\u003c/td\u003e\n        \u003ctd width=\"33%\"\u003e\u003cimg src=\"https://github.com/coreroller/coreroller/raw/master/docs/screenshots/screenshot3.png\"\u003e\u003c/td\u003e\n    \u003c/tr\u003e\n    \u003ctr\u003e\n        \u003ctd\u003e\u003cimg src=\"https://github.com/coreroller/coreroller/raw/master/docs/screenshots/screenshot4.png\"\u003e\u003c/td\u003e\n        \u003ctd\u003e\u003cimg src=\"https://github.com/coreroller/coreroller/raw/master/docs/screenshots/screenshot5.png\"\u003e\u003c/td\u003e\n        \u003ctd\u003e\u003cimg src=\"https://github.com/coreroller/coreroller/raw/master/docs/screenshots/screenshot6.png\"\u003e\u003c/td\u003e\n    \u003c/tr\u003e\n\u003c/table\u003e\n\n## News\n\n*May 8, 2017*\n\nCoreRoller 1.0 released! The project will use semantic versioning from now on and docker images automatically built will be tagged accordingly as well. If you were already using CoreRoller before this release please check out the [release notes](https://github.com/coreroller/coreroller#release-notes) below.\n\n## Features\n\n- Dashboard to control and monitor your applications updates\n- Ready to serve updates for to CoreOS clusters out of the box\n- Manage updates for your own applications as well, not just CoreOS\n- Define your own groups and channels, even for the CoreOS application (pre-installed)\n- Define roll-out policies per group, controlling how updates should be applied to a set of instances\n- Pause/resume updates at any time at the group level\n- Statistics about versions installed in your instances, updates progress status, etc\n- Activity stream in UI to get notified about important events or errors\n- Post HipChat notifications about important events\n- Based on the [Omaha](https://code.google.com/p/omaha/wiki/ServerProtocol) protocol developed by Google\n\n## Status\n\nCoreRoller is *stable*. It has been used in production enviroments for over a year without any major issues. \n\nPlease report any bug you find as [issues](https://github.com/coreroller/coreroller/issues) on this repository.\n\n## Getting started\n\nThe best way to give it a try is to launch a Docker container using the public images hosted in Docker Hub: \n\n\tdocker run -d -p 8000:8000 coreroller/demo\n\nOnce the container is up, just point your browser to:\n\n\thttp://localhost:8000/\n\t\nand you should be ready to go. Default username/password is `admin/admin`.\n\nThis demo container runs `PostgreSQL` (the datastore used by CoreRoller) and the `CoreRoller server` (aka rollerd).\n\nIn addition to this [coreroller/demo](https://hub.docker.com/r/coreroller/demo) image, there are some other images available in the docker hub that may be helpful to you as a starting point when preparing your own custom images.\n\n- **[coreroller/rollerd](https://hub.docker.com/r/coreroller/rollerd)**: this image runs the backend server, a dependency free Golang binary that will power the dashboard and serve all Omaha updates and events requests.\n\n- **[coreroller/postgres](https://hub.docker.com/r/coreroller/postgres)**: this image runs PostgreSQL and creates the database used by CoreRoller. Do not forget to setup properly the volumes in the container to avoid any data loss.\n\nThese images are rebuilt and tagged automatically after every commit. Dockerfiles used to build them can be found in the `backend/docker` directory.\n\nAdditionally, in the `backend/systemd` directory there are some systemd unit files that might be handy in case you want to deploy CoreRoller in your CoreOS cluster using `fleet`. You can also use the sample kubernetes configuration files in the `backend/kubernetes` folder to deploy CoreRoller using `kubernetes` (`kubectl create -f backend/kubernetes`). These units and config files are just samples, feel free to adjust them to suit your specific needs.\n\n## Managing CoreOS updates\n\nOnce you have CoreRoller up, it's time to give it some work to do. You may be interested in managing the CoreOS updates in your cluster with it.\n\nThe process is slightly different if you want to do it in existing machines or in new ones. In both cases it's very simple as it only requires updating the server url the CoreOS updater uses to pull updates from. By default your CoreOS instances use the public CoreOS servers to get updates, so you'll have to point them to your CoreRoller deployment instead.\n\n### New machines\n\nIn new machines, you can set up the updates server in the cloud config. Here is a small example of how to do it:\n\n\tcoreos:\n\t\tupdate:\n\t\t\tgroup: stable\n\t\t\tserver: http://your.coreroller.host:port/v1/update/\n\nIn addition to the default `stable`, `beta` and `alpha` groups, you can also create and use **custom groups** for greater control over the updates. In that case, you **must** use the group id (not the name) you will find next to the group name in the dashboard.\n\n\tcoreos:\n\t\tupdate:\n\t\t\tgroup: ab51a000-02dc-4fc7-a6b0-c42881c89856\n\t\t\tserver: http://your.coreroller.host:port/v1/update/\n\n**Note**: The sample CoreRoller containers provided use the `port 8000` by default (**plain HTTP, no SSL**). Please adjust the update url setup in your servers to match your CoreRoller deployment.\n\n### Existing machines\n\nTo update the update server in existing instances please edit `/etc/coreos/update.conf` and update the `SERVER` value (and optionally `GROUP` if needed):\n\n\tSERVER=https://your.coreroller.host/v1/update/\n\nWhen using custom groups instead of the official ones (stable, beta, alpha) the group id **must** be used, not the group name:\n\n    GROUP=ab51a000-02dc-4fc7-a6b0-c42881c89856\n\t\nTo apply these changes run:\n\n\tsudo systemctl restart update-engine\n\t\nIn may take a few minutes to see an update request coming through. If you want to see it sooner, you can force it running this command:\n\n\tupdate_engine_client -update\n\n**Note:** the CoreUpdate docs do a great job explaining in detail how this process works and most of the information it contains applies to CoreRoller as well, so please have a look at them [here](https://coreos.com/products/coreupdate/docs/latest/configure-machines.html) for more information.\n\n### CoreOS packages in CoreRoller\n\nOut of the box CoreRoller polls periodically the public CoreOS update servers to create packages and update channels in your CoreRoller deployment as they become publicly available. So if rollerd has access to the Internet you'll see eventually new packages (pointing to the official image files) added to the CoreOS application in CoreRoller. This functionality can be disabled if needed (i.e. you want to deploy your custom built images, etc) using the rollerd flag `-enable-syncer=false`.\n\nBy default, CoreRoller only stores metadata about the official CoreOS packages available, not the packages payload. This means that the updates CoreRoller serves to your instances contain instructions to download the packages payload from the public CoreOS update servers directly, so your servers need access to the Internet to download them.\n\nIn some cases, you may prefer to host the CoreOS packages payload as well in CoreRoller. When CoreRoller is instructed to behave this way, in addition to get the packages metadata, it will also download the package payload itself so that it can serve it to your instances when serving updates.\n\nEnabling CoreOS packages payload hosting requires passing some parameters to rollerd:\n\n    rollerd -host-coreos-packages=true -coreos-packages-path=/PATH/TO/STORE/PACKAGES -coreroller-url=http://your.coreroller.host:port\n\n## Managing updates for your own applications\n\nIn addition to manage updates for CoreOS, you can use CoreRoller for your own applications as well. It's really easy to send updates and events requests to the Omaha server that CoreRoller provides.\n\nIn the `updaters/lib` directory there are some sample helpers that can be useful to create your own updaters that talk to CoreRoller or even embed them into your own applications. \n\nIn the `updaters/examples` you'll find a sample minimal application built using [grace](https://github.com/facebookgo/grace) that is able to update itself using CoreRoller in a graceful way.\n\n## Other features\n\n### HipChat notifications\n\nCoreRoller supports posting notifications to HipChat when certain events occur. This way you'll be notified when a channel points to a new package, a rollout starts, fails or succeeds, etc.\n\nEnabling HipChat notifications requires setting a couple of environment variables for `rollerd`:\n\n    CR_HIPCHAT_ROOM=ROOM_ID\n    CR_HIPCHAT_TOKEN=TOKEN\n\n## Contributing\n\nCoreRoller is an Open Source project and we welcome contributions. Before submitting any code for new features or major changes, please open an [issue](https://github.com/coreroller/coreroller/issues) and discuss first.\n\nBelow you will find some introductory notes that should point you in the right direction to start playing with the CoreRoller source code.\n\n### Backend\n\nThe CoreRoller backend (aka rollerd) is a Golang application. Builds and vendored dependencies are managed using [gb](http://getgb.io), so you just need a working Golang environment and gb installed to start working with it (there is **no** need to do a `go get` to fetch the dependencies as they are already contained in `backend/vendor`).\n\nThe backend source code is located inside `backend/src` and is structured as follows:\n\n- **Package `api`**: provides functionality to do CRUD operations on all elements found in CoreRoller (applications, groups, channels, packages, etc), abstracting the rest of the components from the underlying datastore (PostgreSQL). It also controls the groups' roll-out policy logic and the instances/events registration.\n\n- **Package `omaha`**: provides functionality to validate, handle, process and reply to Omaha updates and events requests received from the Omaha clients. It relies on the `api` package to get update packages, store events, or register instances when needed.\n\n- **Package `syncer`**: provides some functionality to synchronize packages available in the official CoreOS channels, storing the references to them in your CoreRoller datastore and even downloading packages payloads when configured to do so. It's basically in charge of keeping up to date your the CoreOS application in your CoreRoller installation.\n\n- **Cmd `rollerd`**: is the main backend process, exposing the functionality described above in the different packages through its http server. It provides several http endpoints used to drive most of the functionality of the dashboard as well as handling the Omaha updates and events requests received from your servers and applications.\n\n- **Cmd `initdb`**: is just a helper to reset your database, and causing the migrations to be re-run. `rollerd` will apply all database migrations automatically, so this process should only be used to wipe out all your data and start from a clean state (you should probably never need it).\n\nPlease make sure that your code is formatted using `gofmt` and makes [gometalinter](https://github.com/alecthomas/gometalinter) happy :) \n\n#### Backend datastore (PostgreSQL)\n\nCoreRoller uses `PostgreSQL` as datastore, so you will need it installed if you are planning to do some work on CoreRoller.\n\nYou can install it locally or use the docker image available in the docker hub (coreroller/postgres). If you don't use the docker image provided, you'll need to run the following commands to create the necessary databases:\n\n\tpsql -U postgres -c \"create database coreroller;\"\n\nTo run the tests you will also need to setup the coreroller\\_tests database:\n\t\n\tpsql -U postgres -c \"create database coreroller_tests;\"\n\n### Frontend\n\nThe frontend side of CoreRoller (dashboard) is a javascript web application built using `react/flux`.\n\nTo do some development in the frontend it's highly recommended to setup the backend service as well, as that will allow you to fully interact with the real API. Also, the backend server is ready to serve the static assets you'll build out of the box, so you can point your browser to `http://localhost:8000/` and interact with your development environment while you work on it.\n\nTo build the webapp and download its dependencies you'll need Node.js installed. Building the webapp is a simple and straightforward process:\n\nFetch the project dependencies\n\n\tnpm install (inside frontend)\n\t\nBuild it\n\n\tnpm run build\n\t\n*That's it!* The build process will generate a built **main.js** containing the web application and a built **styles.css** file containing the styles generated from the less templates. Both built files can be found inside `frontend/built` in the `js` and `css` directories respectively, along with some other files that will allow you to serve the webapp straight away from rollerd.\n\nWhile working on specific parts of the webapp, you may find handy running one of the watchers that will build the js or css files (or both) as soon as one relevant source file is modified.\n\n\tnpm run watch\n\tnpm run watch-js\n\tnpm run watch-css\n\t\nUnlike the build-* commands, the watchers do NOT minify the built files, so they'll be considerably bigger than the final ones.\n\nEnjoy!\n\n## Release notes\n\n### 1.0\n\nThe main change that this first release introduces is dropping the PostgreSQL `semver` extension completely. A few months ago CoreRoller stopped using it, but it was still part of the database migrations. This was a [problem](https://github.com/coreroller/coreroller/issues/42) as even though we were not using the extension anymore, it had to be present in your PostgreSQL server so that all migrations could be processed correctly. In scenarios where installing the extension wasn't possible (i.e. AWS RDS), this was a blocker. So we decided to drop it completely and merge all database migrations into a single one (applying some other minor database schema changes as well).\n\nIf you were using CoreRoller before this release we recommend you to follow the procedure below to upgrade to the stable 1.0 version:\n\n(please adjust database host and user as needed)\n\n    # Step 1: Backup existing CoreRoller data and move it to safe location\n    pg_dump -h COREROLLER_DB -U postgres -d coreroller --data-only --exclude-table=database_migrations \u003e coreroller_backup.sql\n\n    # Step 2: Start a new PostgreSQL server (free of any coreroller tables and data)\n    # (If you are setting up your PostgreSQL instance manually instead of using the provided docker image don't forget creating the database)\n\tpsql -h NEW_COREROLLER_DB -U postgres -c \"create database coreroller;\"\n\n    # Step 3: Start a new rollerd 1.0 instance connecting to the new PostgreSQL server. The new migration file will create the schema and add the sample data.\n\n    # Step 4: Delete the sample data from new PostgreSQL instance\n    psql -h NEW_COREROLLER_DB -U postgres -d coreroller -c \"delete from team; delete from event_type; delete from instance;\"\n\n    # Step 5: Restore data previously backed up into new PostgreSQL instance\n    psql -h NEW_COREROLLER_DB -U postgres coreroller \u003c coreroller_backup.sql\n\nFuture database schema changes will be applied automatically by `rollerd` using migrations as usual.\n\n## License\n\nCoreRoller is released under the terms of the [Apache 2.0 License](http://www.apache.org/licenses/LICENSE-2.0).\n\nCoreRoller was created by Cintia Sánchez García, Mathieu Lohier and Sergio Castaño Arteaga.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcoreroller%2Fcoreroller","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fcoreroller%2Fcoreroller","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcoreroller%2Fcoreroller/lists"}