Setting Up a Developer Environment

Connect is an application with extensive compiled less/hogan/javascript front-end and interpreted Python/Django back-end components. While it’s not necessary for a back-end developer to know how to build front-end tests, nor does a front-end developer need to know how to write Python code, it is vital that anyone working on Connect have the packages for both available locally.

Some parts of this documentation are based off the DjangoCMS Documentation

Note

You will need sudo access to install some of these packages.

Note

These instructions apply for development using OS X, although there shouldn’t be much change needed to develop on Linux.

System Package Requirements

As a 12 Factor App, developers of Connect should strive for Dev/prod parity, where the environment run locally is as close as possible to production.

Before starting, make sure you have Homebrew installed so you can install the required libraries. The following instructions imply that you have brew installed.

  • Node - Command-line javascript system. brew install node
  • PostgreSQL - Database. brew install postgresql or via Postgres.app with the command line tools configured. Postgres.app is more user-friendly, but both work.
  • Grunt - Front-end task runner. sudo npm install -g grunt-cli
  • Bower - Front-end dependency management. sudo npm install -g bower
  • libjpeg - JPEG image support. brew install libjpeg
  • pip - Python dependency management. sudo easy_install pip
  • virtualenv or virtualenvwrapper - Python package isolation. It’s recommended you install the more user-friendly virtualenvwrapper, which also installs virtualenv, but these instructions imply you’re using the vanilla virtualenv. sudo pip install virtualenv
  • Git - Code management. This may be installed already on your system, but for the latest version of Git: brew install git

Optional (but recommended) packages

  • libmemcached Library for compiling memcached client. brew install libmemcached
  • Memcached - Caching framework. Note: Django offers alternative caches brew install memcached
  • Gifsicle - Animated GIF support. Gifsicle is required for GIFs to maintain animation after resize. It also allows some tests that are otherwise skipped to run. brew install gifscicle
  • RabbitMQ - Task Queue. Note: For convenience it’s recommended you run Connect in development with CELERY_ALWAYS_EAGAR enabled (it is enabled by default when in DEBUG mode), disabling local task queues. It’s also possible to use alternative task queues locally. brew install rabbitmq

Forking Connect

Connect requires users to fork their own version of the Connect Github project then use the official project as a remote that changes can be merged in from.

How to fork Connect and move the upstream changes into that fork is outside the scope of this documentation, but for simplicity’s sake we can clone Connect from the official repository locally.

To clone the Connect project locally, set the official project as a remote called “open” and enter that folder, run the following:

git clone -o open https://github.com/ofa/connect.git
cd connect

Note

Be careful merging in upstream changes from the official Connect project into your local project, and always review code changes and commit messages manually before merging. While we strive for stability, Connect is under active development and some changes to the core project can break your local modifications.

Back-end Configuration & Setup

Installing in a virtualenv using pip

Installing inside a virtualenv is the preferred way to install any Django installation. These instructions imply you’re using the vanilla version of virtualenv and not virtualenvwrapper, which has more user-friendly shortcuts when dealing with virtualenv, but is slightly more difficult to setup.

To create a new virtualenv

virtualenv connectenv

Note

If you are not using a system-wide install of Python (such as with Homebrew), omit the usage of sudo when installing via pip.

Switch to the virtualenv at the command line by typing:

source connectenv/bin/activate

Note

Any time you want to load Connect you’ll need to enter source connectenv/bin/activate to enter the virtual environment containing your Connect dependencies.

Connect relies on pip for python dependency management.

The python dependencies necessary for development of Connect are located in the dev-requirements.txt file [1]. To install all the packages necessary to run Connect, run:

pip install -r dev-requirements.txt

Warning

There are a few packages that are compiled during this step that require packages defined in System Package Requirements, specifically libjpeg for JPEG image handling and PostgreSQL (with the PostgreSQL command line tools) for database handling. Make sure you have installed both before attempting to install Connect.

[1]There are multiple requirements.txt files in Connect, including an actual requirements.txt, which has packages aimed specifically at Heroku and may not compile on OS X. Each of these files include common-requirements.txt, which contains the core cross-platform packages necessary to run Connect on any platform. For development, use dev-requirements.txt

Setting up a .env file

Basic configuration of Connect is based around the 12 Factor Environment-Based Configuration philosophy. Instead of having to directly edit your environment, Connect’s backend uses Django-environ and frontend uses dotenv to allow users to store the configuration in an .env file locally that is not tracked by version control. The .env file is a key/value file containing variables that will be loaded into the environment at startup.

The first step in setting up your developer environment is to clone the .env-dev-example file (which is tracked in version control) to be your local .env file (which will not be tracked by version control)

cp .env-dev-example .env

You can then edit the .env file to reflect the settings you need locally. Available settings are available in the Connect Settings documentation.

Setting up a database

This assumes that you have Postgres.app installed and running and have correctly installed the command line tools.

The .env file that ships with Connect assumes that you have a database called connect in your localhost database. To both create this database and have Connect insert all the preliminary code, run:

createdb connect
python manage.py migrate

Front-end Configuration & Setup

Loading front-end dependencies

Some files necessary for managing Connect are not contained in the repository itself, and instead must be brought in via the Node Package Manager and Bower.

To load all front-end dependencies run:

npm install
bower install

Compiling front-end files

Connect uses Grunt to compile static assets. A simple default task is already created to compile all the necessary static assets.

grunt

Note

Grunt is used elsewhere in Connect for front-end related tests. As long as you do not have a CONNECT_APP loaded in your .env file, you can run tasks like grunt jasmine and have the app-wide tests run. If you do have a CONNECT_APP defined in your .env you can run those same tasks by settings a --target "open_connect/connect_core" flag to your grunt tasks. For jasmine tests that would be grunt --target "open_connect/connect_core" jasmine

Setting up your version of Connect

Running Connect locally

Once you have your static files built, you’ll be able to launch your version of Connect using Django’s built-in development server.

While inside your local virtualenv (i.e. after running source connectenv/bin/activate) run

python manage.py runserver

You should now be able to visit http://127.0.0.1:8000/ and see a fully functioning version of Connect using the open source theming.

Promote a user to be a superuser

Connect uses NGP VAN_‘s ActionID single-sign-on system for authentication via Python Social Auth.

When you first go to your development server you’ll be given 2 buttons, one to Login and one to Create a New Account. Click on either and follow the login or registration flow presented by ActionID. Remember the email address you use. After you’re done with that you’ll be redirected back to Connect with a new account.

In order to upgrade your account to be a super-user, you’ll need to use the promote_superuser Django management command and include the email address you used to sign-up for ActionID with.

python manage.py promote_superuser [email protected]

Your account should now be properly promoted to a superuser. From here on out you can manage your local version of Connect by following the Administrator Guide.