thebrianzeng / eventum

An event-driven CMS that syncs with Google Apps

ADI Website (adicu.com)

ADI is the tech club at Columbia. The ADI website is built on Eventum, a content management system for an event-driven blog that syncs with Google Calendar.

Stack

• Built in Flask
• Flask-Mongoengine and Mongoengine are used to interface with MongoDB
• Authentication is done with Google+ server-side flow
• Forms and validation are done through Flask-WTForms and WTForms
• CSS is generated from SCSS and managed with Flask-Assets
• Configurations are managed using Consul.
• Development is done using Vagrant.
• Deployment is done using Docker.

First-Time Setup

Eventum can be run locally on your machine, or in a virtual environment, using Vagrant. Default to use Vagrant, unless you have some reason to run Eventum locally.

Using Vagrant

1. Generate secrets files:

   • ADI: Download the ADI website secrets from GitHub. Unzip the folder, and copy its contents into the config directory.

     If the link gives a 404 error, ask someone within the ADI GitHub organization for access

   • non-ADI: Copy config/setup_consul_no_secrets.sh to config/setup_consul_dev.sh, and fill in the four parameters that are set to empty strings. Then, either setup Google Auth yourself, or disable it.

2. Install Virtual box.

3. Once Vagrant is installed, install Vagrant.

Without Vagrant

Eventum runs natively on Linux and OSX. To get it up an running, follow these steps:

1. Generate secrets files:

   • ADI: Download the ADI website secrets from GitHub. Unzip the folder, and copy its contents into the config directory.

     If the link gives a 404 error, ask someone within the ADI GitHub organization for access

   • non-ADI: Copy config/setup_consul_no_secrets.sh to config/setup_consul_dev.sh, and fill in the four parameters that are set to empty strings. Then, either setup Google Auth yourself, or disable it.

2. Install MongoDB (Ubuntu Linux, OSX).

   On OSX, you may have to run mkdir /data /data/db before you can run mongod without errors.

3. Install VirtualEnv:

   sudo pip install virtualenv

4. Install Consul.

5. Install SASS gem gem install sass

   Otherwise, you will see an intermittent OSError

Developing

Using Vagrant

vagrant up                      # Wait for installation
vagrant ssh                     # Enter your virtual machine
cd /vagrant                     # Enter your project directory
./config/setup_consul_dev.sh    # Populate Consul with values
python run.py                   # Run the application

Finally, go to localhost:5000 in your web browser.

Without Vagrant

./develop.sh                    # MongoDB, Consul, and Pip
source bin/activate             # Enter the virtual environment
./config/setup_consul_dev.sh    # Populate Consul with values
python run.py                   # Run the application

Finally, go to localhost:5000 in your web browser.

Disabling Google Auth

It is possible to run Eventum without logging in using Google+ or authenticating with Google Calendar. To do so, edit config/setup_consul_dev.sh and change the line:

consul_set GOOGLE_AUTH_ENABLED 'FALSE'

to:

consul_set GOOGLE_AUTH_ENABLED 'TRUE'

Then, re-run the consul configurations:

./config/setup_consul_dev.sh    # Populate Consul with values

Documentation

Eventum uses Sphinx to compile documentation to an HTML website. This documentation is generated from the source code.

First, enter your development environment. See "Developing" for more. Then, generate the docs:

cd docs
make html                       # Generate docs in /docs/_build/html
cd _build/html
python -m SimpleHTTPServer .    # Host the docs on localhost:8000

Testing

Tests live in the test directory, and can be run via nosetests. We also use flake8 for linting .py files.

First, enter your development environment. See "Developing" for more. Then, run the tests:

flake8 app config test script   # Run the flake8 linter on our python files
nosetests --with-progressive    # Run test scripts

Organization / Structure

.
├── .travis.yml      # Configurations for Travis-CI continuous integration
├── app              # All code related to the running of the app
│   ├── forms        # Flask-WTForms models, used for generating forms in 
│   │                #     HTML and validating input
│   ├── lib          # Misc helpers, tasks, and modular libraries
│   ├── models       # Mongoengine Models
│   ├── routes       # All Flask routes, using Blueprints
│   ├── static       # Static files.  Note: All files in here are public
│   │   ├── css      # CSS
│   │   │   ├── lib  # CSS libraries
│   │   │   └── gen  # CSS generated from SCSS
│   │   ├── img      # Images
│   │   ├── js       # JavaScript files
│   │   └── scss     # Stylesheets
│   ├── templates    # HTML templates
│   └── __init__.py  # All app-wide setup.  Called by `run.py`
├── authorize.py     # Used for authorizing the app with Google Calendar
├── config           # Configuration files
├── data             # Backup data
├── deploy.sh        # Run on our deployment server to deploy a new version
├── develop.sh       # Used for non-Vagrant local Development
├── Dockerfile       # Holds Docker configurations
├── docs             # Eventum documentation, generated using Sphinx
├── log              # Log Files
├── manage.py        # Various scripts. Run `python manage.py` to view usage
├── run.py           # Runs the app!
├── script           # Scripts run by `manage.py` outside of the app
├── test             # Unit tests
└── Vagrantfile      # Configurations for Vagrant