Server for online menstrual tracker
Branch: master
Clone or download
jessamynsmith Upgrading to heroku-18
Latest commit 9bb024c Nov 28, 2018


Build Status Coverage Status

The egg timer is an open-source tracker for menstrual periods. It provides a calendar, email notifications, statistical analysis, and an API allowing you to download all your data. Check out the live app:

Like my work? Tip me!


Fork the project on github and git clone your fork, e.g.:

git clone<username>/eggtimer-server.git

Create a virtualenv using Python 3 and install dependencies. I recommend getting python3 using a package manager (homebrew on OSX), then installing virtualenv and virtualenvwrapper to that python. NOTE! You must change 'path/to/python3' to be the actual path to python3 on your system.

mkvirtualenv eggtimer --python=/path/to/python3
pip install -r requirements/development.txt

Ensure you have node installed (I recommend using homebrew on OSX), then use npm to install Javacript dependencies:

npm install

Set environment variables as desired. Recommended dev settings:


Optional environment variables, generally only required in production:


You can add the exporting of environment variables to the virtualenv activate script so they are always available.

Set up db:

python migrate

Run tests and view coverage:

coverage run test
coverage report -m

Check code style:


(Optional) Generate graph of data models. In order to do this, you will need to install some extra requirements:

brew install graphviz pkg-config
pip install -r requirements/extensions.txt

You can then generate graphs, e.g.:

python graph_models --pygraphviz -a -g -o all_models.png  # all models
python graph_models periods --pygraphviz -g -o period_models.png  # period models

Run server:

python runserver

Or run using gunicorn:

gunicorn eggtimer.wsgi

Lint JavaScript:

./node_modules/jshint/bin/jshint */static/*/js

Run JavaScript tests:

mocha --require-blanket -R html-cov */tests/static/*/js/* > ~/eggtimer_javascript_coverage.html

To run Selenium tests, you must have chromedriver installed:

 brew install chromedriver

Next you need to create a Django admin user and then export the email and password for that user as environment variables:


Finally, ensure the server is running, and run the selenium tests:

nosetests selenium/

Retrieve data from the API with curl. <AUTH_TOKEN> can be found in your account info.

curl -vk -X GET -H "Content-Type: application/json" -H 'Authorization: Token <AUTH_TOKEN>' "" | python -m json.tool

curl -vk -X GET -H "Content-Type: application/json" -H 'Authorization: Token <AUTH_TOKEN>' "" | python -m json.tool

You can filter based on minimum and maximum timestamp of the events:

curl -vk -X GET -H "Content-Type: application/json" -H 'Authorization: Token <AUTH_TOKEN>' "" | python -m json.tool

Create a period:

curl -vk -X POST -H "Content-Type: application/json" -H 'Authorization: Token <AUTH_TOKEN>' --data '{"timestamp": "THH:MM:SS"}' ""

Continuous Integration and Deployment

This project is already set up for continuous integration and deployment using circleci, coveralls, and Heroku.

Make a new Heroku app, and add the following addons:

Heroku Postgres
New Relic APM
Heroku Scheduler
Dead Man's Snitch

Add Heroku buildpacks:

heroku buildpacks:set heroku/nodejs -i 1
heroku buildpacks:set heroku/python -i 2

Enable the project on, and copy the repo token

Enable the project on, and under Project Settings -> Environment variables, add:

COVERALLS_REPO_TOKEN <value_copied_from_coveralls>
HEROKU_API_KEY <value_copied_from_heroku>

On, under Project Settings -> Heroku Deployment, follow the steps to enable Heroku builds. At this point, you may need to cancel any currently running builds, then run a new build.

Once your app is deployed successfully, you can add the Scheduler task on Heroku:

python notify_upcoming_period --settings=eggtimer.settings

You can also set up Dead Man's Snitch so you will know if the scheduled task fails.

Thank you to: Emily Strickland ( for the name