Cog

Cog is a hardware checkout system for hackathons, originally written for use at HackMIT and MakeMIT.

Features

Inventory Management

Add inventory items individually or in bulk from a spreadsheet, providing links and descriptions to give hackers resources for getting started. Items can even be individually named and tracked to make sure nothing goes missing.

Flexible Request System

Tweak Cog to fit the logistical needs of your event, with options to manage lotteried items, items that require checkout, or simply a grab-and-go style inventory.

Keep Track of Users

Easily determine which hackers have which items, and get in touch with hackers via phone or email. You can additionally track whether or not you've collected collateral (such as an ID) from each hacker.

Real-time Admin Panel

View, approve, and fulfill item requests in real-time as they come in. As soon as an organizer approves a request, hackers can see that their item is ready to be picked up.

Quill-Integrated Login

Users login using credentials from an associated Quill instance, forgoing the need to create an additional account.

Deployment & Configuration

The easiest way to deploy Cog is to smash this Deploy to Heroku button right here:

If you're interested in deploying on other infrastructure, that should be doable as well. Cog is written in Python 2, and all dependencies can easily be installed using Pip via requirements.txt. Cog uses PostgreSQL as a database. Deployments of Cog generally use Gunicorn as a web server (alongside gevent or eventlet for handling websockets). The exception to this is Cog's default Heroku configuration which uses the built in Flask-SocketIO web server due to performance issues using Gunicorn on Heroku.

A myriad of configuration options are available to be tweaked in config.py. Alternatively, all values set in this file can be set as environment variables of the same name - environment variable values will take precedence over the value specified in config.py. Sensible defaults are in place for all of the event logistical settings, but we recommend playing around with them a bit. At the bare minimum you should change the HACKATHON_NAME and set your QUILL and SECRET env variables to match the associated Quill instance.

We strongly recommend deploying Cog and experimenting with/testing your desired configuration options in advance of your event to ensure it behaves in a manner consistent with the logistical organization of your event.

Adding Hardware via Google Sheets

While you can add individual items one-by-one, we recommend creating a spreadsheet with all your items and importing this into Cog in one go. Currently, the only supported way to do this is via Google Sheets. An example Cog inventory sheet can be found here.

To import from a Google Sheet, simply turn on view-only sharing and paste the main URL (not the sharing URL) into Cog after clicking 'Import Google Sheet' on the main inventory page.

Customizing Branding

Cog uses the Semantic UI framework for styling. Branding can easily be customized using Semantic UI themes.

While Cog mostly uses default Semantic UI styling, a minimal amount of custom CSS lives in hardwarecheckout/static/sass/app.scss. In order to rebuild the CSS when the Sass is changed, install Sass and run sass --watch sass:css in the /static directory.

If you end up using Cog for your event, please take a moment to add yourself to our users list!

Development

Interested in hacking on Cog? Check out the development guide for some steps to get you started.

Contributing

Hacking on Cog go well? Contribute back to upstream! We love outside contributions - have a look at our contributing guide for information on how you can get involved.

Acknowledgements

Thanks to the following folks for their contributions to Cog pre-open sourcing:

• Ethan Weber and Albert Yue of MakeMIT
• Shreyas Kapur of HackMIT
• Andrew Zhang of SwampHacks

License

Copyright 2017-2018 Noah Moroze. Released under AGPLv3. See LICENSE.md for a copy of the full license text.