{"id":13837295,"url":"https://github.com/coderanger/commis","last_synced_at":"2025-07-10T18:32:45.856Z","repository":{"id":1387755,"uuid":"1361048","full_name":"coderanger/commis","owner":"coderanger","description":"A Django implementation of a Chef server","archived":true,"fork":false,"pushed_at":"2012-05-30T18:37:41.000Z","size":815,"stargazers_count":64,"open_issues_count":8,"forks_count":3,"subscribers_count":7,"default_branch":"master","last_synced_at":"2024-11-21T00:32:43.383Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":"","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":"spring/pr-downloader","license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/coderanger.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2011-02-13T06:15:55.000Z","updated_at":"2024-05-03T08:36:30.000Z","dependencies_parsed_at":"2022-08-16T13:15:14.470Z","dependency_job_id":null,"html_url":"https://github.com/coderanger/commis","commit_stats":null,"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/coderanger/commis","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/coderanger%2Fcommis","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/coderanger%2Fcommis/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/coderanger%2Fcommis/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/coderanger%2Fcommis/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/coderanger","download_url":"https://codeload.github.com/coderanger/commis/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/coderanger%2Fcommis/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":264631213,"owners_count":23640941,"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-04T15:01:05.611Z","updated_at":"2025-07-10T18:32:45.497Z","avatar_url":"https://github.com/coderanger.png","language":"Python","funding_links":[],"categories":["Python"],"sub_categories":[],"readme":"## WHAT\n\nCommis is a [Django](http://djangoproject.com) implementation of [Chef\nServer](http://wiki.opscode.com/display/chef/Chef+Server). It's currently\ncompatible with Django 1.2 through 1.4, and thus has the same dependencies as\nthose releases:\n\n* Python 2.5 or newer\n* A relational database engine (this includes the ships-with-Python SQLite)\n\nOn top of that, Commis requires a handful of other pure-Python libraries, such\nas PyChef, Celery and PyParsing.\n\n\n## WHY\n\nThere are a number of reasons you may want to deploy Commis instead of the\nstandard Chef Server implementation or using Opscode's hosted service:\n\n### Simpler deployment\n\n**Chef Server requires many components \u0026 runtimes in addition to Ruby**:\nRabbitMQ (and thus Erlang), CouchDB (also Erlang), Solr (Java), and `gecode`.\nInstallation quickly gets complicated on non-Ubuntu platforms such as CentOS or\nFedora (have fun finding up to date `gecode` RPMs or waiting an hour for it to\ncompile!).  Managing and supporting the different components is also a large\nhurdle for users who just want to get started, regardless of platform.\n\nConversely, in its most basic form, **Commis relies purely upon Python\nlibraries** -- the embedded SQLite for databasing, Whoosh for text indexing,\nand Celery for queuing (which can function without an actual queue when not\nneeded.)\n\nFurthermore, **you can easily replace these components when necessary, and with\nwhatever backends you want**.  SQLite crumbles with more than a few concurrent\nusers? Use Postgres or MySQL (or Oracle or ...). Need non-eager background\njobs? Use any [Celery](http://celeryproject.org/)-supported backend (like\nRedis), you're not limited to RabbitMQ. Ditto for text indexing -- anything\n[Haystack](http://haystacksearch.org/) supports is fair game.\n\n### Improved hackability\n\nAs a third party solution, Commis is free to innovate and add experimental\nfeatures that aren't suitable for the official Chef Server project. This\nincludes things like major UI changes for the web interface and flexible policy\nbackends that are designed be be altered to suit your needs.\n\nFor example, not everybody is able or willing to treat their Chef Server as the\nsingle source of truth -- imagine being able to plug-in or sync your\npre-existing LDAP server or Clusto database such that your Chef recipes see the\ndata as regular attributes, or even as dynamically managed node or client\nentries. And this is just one example.\n\n### Python interoperability\n\nMostly a sub-case of the above -- Commis, being Python, is a great fit for\nshops with pre-existing Python systems or Python deployment experience.\nLearning Ruby to write Chef manifests is one thing; becoming comfortable\ndeploying a complex Ruby web-app is another entirely. With Commis, you might\nnot have to.\n\n\n## HOW\n\nHere's how to get started hacking on or evaluating Commis. It assumes you want\nto run off the abovementioned pure-Python default stack; to move away from\nthose defaults, you'll just need to install the additional components you want\nand modify `commis/settings.py` appropriately.\n\n### Installation\n\nOn the system acting as Chef Server, get Commis installed and running:\n\n* Get Commis: `git clone`, download tarball, etc.\n* (Optional but strongly recommended) Create a\n  [virtualenv](http://www.virtualenv.org) and activate it.\n* Get dependencies: `pip install -r requirements.txt`\n* Put Commis on your PYTHONPATH (some settings files need to import\n  `commis.\u003cx\u003e`): `pip install -e .`\n* Install DB schema: `python commis/manage.py syncdb`\n    * By default, this creates a SQLite DB in `commis/commis.db`. You can\n    select a different SQL DB in `commis/settings.py`.\n    * It will prompt you for a new admin user which you'll use to admin the Web\n    UI.\n* Start it up to make sure things work: `python commis/manage.py runserver\n  0.0.0.0:8000`\n    * You may alter the port number to taste.\n    * Chef Server runs the Web UI and the API on separate ports; Commis runs\n    both on a single port, exposing the API at `/api/*`.\n* Hit up `http://\u003chostname\u003e:8000/`and make sure you can log\n  in as your admin user and click around.\n\n### Client/key management\n\nYou now have a working Commis install, but you need to do some Chef client/key\nmanagement in order for Chef-managed systems, or CLI management tools\n(`knife`), to connect. Here's a conceptual overview:\n\n* Chef \"clients\" are entities that connect to the Chef server API and\n  manipulate/query its DB. They are distinct from the Django website user\n  accounts (such as your admin user.)\n* Clients are really just an association between a name and an RSA key pair\n  (think SSH keys -- two chunks of text, one public and one private) \n  stored in the DB along with authorization metadata (admin ability, etc.)\n* There are three kinds of clients:\n    * **Admin** clients have full privileges, analogous to SQL database root\n    users. They grant actual humans access to the Chef server, typically via\n    the `knife` CLI tool.\n    * **Node** clients represent a Chef-managed system or \"node\", and are\n    analogous to non-root SQL users. They only manipulate their related Node\n    object and its data.\n    * **Validator** clients are used solely to create new node clients on the\n    fly.\n* Thus, the workflow you need is:\n    * Ensure an admin client exists, so you can manage the server via\n    `knife` (currently the primary way to manage Chef Server / Commis, barring\n    a richer Web UI.)\n    * Ensure a validator client exists and that its private key file is in a\n    known location.\n    * New Chef-managed systems obtain a copy of the validator key (e.g. via\n    `scp` or authenticated download) and use it with `chef-client` to create\n    new node clients/keys for themselves.\n    * They then use those per-node client accounts to run Chef cookbooks.\n\n#### Actual client/key HOWTO\n\nHere's the specifics on getting your new Commis serve ready to work with client\nnodes:\n\n* Make an admin client: `python commis/manage.py commis_client --admin\n\u003cname\u003e`.\n    * Replace `\u003cname\u003e` with your desired client name or username. It could,\n    match your Django-level admin account name or local username, but doesn't\n    have to.\n    * This creates a file in your working directory named `\u003cname\u003e.pem`.\n* Make the validator client: `python commis/manage.py commis_client\n  --validator`. This generates `validation.pem` in your working directory.\n* Copy both `.pem` files somewhere persistent that you will remember, such as\n  `~/.chef/` or `/etc/chef/`.\n* Select a system to use for managing your Commis server via `knife` -- could\n  be the Commis server itself, or your local workstation.\n* On that system, install Chef (e.g. `gem install chef`) and copy down the\n  `.pem` files you created above. A good location may be `~/.chef/` as that's\n  where Knife defaults to storing its config files and so forth.\n* Run `knife configure` (note: no `-i` as other tutorials sometimes use.) It'll\n  prompt you for the following:\n  * The location of the conf file to generate.\n  * The Chef Server URL. This is the hostname or IP of your Commis server, plus\n  the port and -- **this is a departure from regular Chef Server** -- a\n  trailing `/api`.\n      * For example, if you are using the Commis system itself as your\n      management host, enter `http://localhost:8000/api`.\n  * The client name. This is the admin user you made above, i.e. `\u003cname\u003e`.\n  * The validator name. This is `chef-validator` by default.\n  * The validator key path. Depending on where you moved that to, give the path\n  here, e.g. `~/.chef/validation.pem`.\n  * A Chef repository path. Leave this blank.\n* Phew! That should have created e.g. `~/.chef/knife.rb`.\n* Test out `knife`: make sure your runserver is active, and execute `knife\n  client list`. It should spit back the two clients you just made, `\u003cname\u003e` and\n  `validator`.\n\n### Running cookbooks on your servers\n\nAt this point, you've got Commis running and can manage/query it via `knife`.\nThe next step is to run some cookbooks on a target server/node!\n\n#### Uploading cookbooks\n\nTo run cookbooks, they must be in Commis' database: `chef-client`\nexpects to get all cookbooks/recipes/etc from the server. We'll\nuse a trivial test cookbook here:\n\n    .\n    └── testcookbook\n        └── recipes\n            └── default.rb\n\nwhere `default.rb` is simply:\n\n    log \"Hello world!\"\n\nGet that `testcookbook` directory onto your `knife` system, enter its parent directory, and execute:\n\n    knife cookbook upload -o . testcookbook\n\nYou can verify the upload by visiting the Web UI and viewing the Cookbooks tab,\nor running `knife cookbook list`.\n\n#### Executing on a new node\n\nWe're almost done. Locate or create a system you're comfortable experimenting\non. There's two ways to update it to run against our Commis server, the\nautomatic way and the hard way.\n\n#### `knife bootstrap`\n\nThe easy way is to simply enter your management workstation's home directory,\nand run:\n\n    knife bootstrap \u003chostname\u003e -x \u003cusername\u003e --sudo\n    \nUse the target's hostname, and your SSH login username used to connect to that\nsystem. It should connect, ensure Chef is installed, and handle the certificate\nmanagement for you (including copying the validator cert from your\nworkstation.)\n\nCaveats:\n\n* Due to a bug in Knife, you have to run this command while inside your home\n  directory, or wherever you created a `.chef` directory containing `knife.rb`.\n  If you run it from your Commis checkout, it will fail.\n  * This is **not** true for other Knife commands like `knife node list` --\n  only `bootstrap` appears to be affected.\n* Depending on your target server's auth settings, you could leave off the `-x\n  \u003cusername\u003e` if you have root login enabled. However, we strongly recommend\n  not doing this, as it's bad security practice.\n* Even if your local workstation username is `\u003cusername\u003e`, you still have to\n  explicitly specify it with `-x`, as `knife` will try to use `root` otherwise.\n* If you're giving a non-human-readable hostname, like an IP address, you can\n  also give `-N \u003cnodename\u003e` to override the Chef-facing name this client will\n  use.\n\n##### Manual\n\nThis is basically what `knife bootstrap` is doing for you:\n\n* Copy `validation.pem` to the target system.\n* Obtain the necessary parameters to run `chef-client` against your Commis\n  server, which can either be used as CLI flags (see `chef-client --help`), or\n  go into a `client.rb` config file:\n  * Path to `validation.pem`.\n  * Path to desired new client key, e.g. `/etc/chef/\u003chostname\u003e.pem`.\n  * Server URI: same as above for Knife,\n  `http://\u003ccommis-server-hostname\u003e:8000/api`.\n* Execute `chef-client` -- it should create a new node client for itself, named\n  after your system's hostname, then run an empty run list.\n\n##### Sanity test and run_list update\n\n* Verify that node creation with `knife node list` on your workstation or on\n  the Web UI.\n* Update this node's run list to include `\"testcookbook\"`, again either via\n  knife (`knife node run_list add \u003chostname\u003e testcookbook`) or the Web UI's\n  edit form.\n    * If using the Web UI, drag the \"testcookbook\" box from the lower left,\n    into the right hand side. Then click \"Edit Node\" to save, and you're done.\n* Run `chef-client` on the target node -- it should print out your \"Hello\n  world!\" log entry in the middle of its run.\n* If so, you're done! Add more cookbooks, tweak run lists, and go to town.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcoderanger%2Fcommis","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fcoderanger%2Fcommis","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcoderanger%2Fcommis/lists"}