Requirements

  • Programming lanuage: Python 2.7.10
  • Web framework: Flask
  • HTTP server: Gunicorn
  • See requirements.txt for additional Python package requirements
  • Background jobs: Redis

Optional requirements

Install for local development

  1. Clone repo
    • git clone <repo> <location_to_clone>
  2. Install virtualenv
  3. Create virtual environment for project
    • virtualenv <env> where <env> is location to where you want to store project environment. <env> is typically the directory of your git repo or something like ~/.virtualenvs/env_name.
  4. Activate virtualenv
    • source <path_to_env>/bin/activate
  5. Install requirements
    • pip install -r requirements.txt
  6. Setup Github application

Setup environment variables

  1. Copy example_config.py to config.py and populate config.DevelopmentConfig with your own data.
    • This is where you’ll copy and paste your Github OAuth application’s credentials.
    • The defaults are all set in the config.Config so override only values you need. The following are required:
      • SECRET_KEY
      • GITHUB_CLIENT_ID
      • GITHUB_SECRET
      • REPO_OWNER - Name of your github user
      • REPO_NAME - Name of repository you’ll store the guide content
      • REPO_OWNER_ACCESS_TOKEN - OAuth token of your github user or owner of the repository where the guide content is stored. You cannot set this until after you run the application locally and authorize it with your github account as described below.
      • CELERY_BROKER_URL - URL of Redis (or another broker) for handling background jobs (see instructions for Celery on heroku for help).
      • DOMAIN - Base URL where your site will be running. This can be the URL of your Heroku deployment or localhost like 127.0.0.1:5000 or 0.0.0.0:5000.

First-time Setup

  1. Run python run.py or make run_flask if you have Make installed
  2. Browse to http://127.0.0.1:5000/login/
  3. Login with your github account and authorize your newly created application
    • Login with the account you set as the REPO_OWNER
  4. Check your logs for the new token printed. This will be a CRTICAL level log message.
  5. You’ll need to place that token in the REPO_OWNER_ACCESS_TOKEN environment variable.
  6. Shutdown the local flask webserver with Ctrl-C and run python run.py again

Now you can test things from the CLI if that’s more your speed. However, there’s one more step to setting up the ability to publish articles. This requires running a celery process for background jobs.

You can try creating a guide once you have celery running locally or your CELERY_BROKER_URL configured to a running Redis server.

Note now you can use this local server and expose it to the Internet through a secure tunnel if you want!

Run locally with Flask webserver

  1. Follow the first-time setup instructions
  2. Run python run.py or make run_flask and use Ctrl-C to stop the server.

Run locally with Gunicorn webserver

  1. Follow the first-time setup instructions
  2. Run make run_gunicorn

Setting up Celery for background processing

You already have Celery installed if you used the requirements.txt file. However, now you need Redis running to process background jobs from Celery and fully enable publishing articles.

Setting up Redis locally is outside the scope of this document. You can refer to the Redis documentation for that. However, you can easily setup Redis on Heroku by following the these instructions.