Find file Copy path
Fetching contributors…
Cannot retrieve contributors at this time
304 lines (188 sloc) 10.5 KB

README for API Installation

Back to root README Read about working with WeVoteServer

NOTE: We are running Django version 1.8

NOTE: WeVoteServer is built for Python 3.4. It currently still works with Python version 2.7.6. (tests still have issues with Python 3.4, but everything else works)

Clone WeVoteServer from github

Create a place to put all of the code from Github:

$ mkdir /Users/<YOUR NAME HERE>/PythonProjects/

Retrieve “WeVoteServer” into that folder.

Installing Python 3

Mac instructions (Based on this)

Install Python 3.4 from package: This allows you to run python3 and pip3. (Software gets installed into /Library/Frameworks/Python.framework/Versions/3.4/bin/.)

$ pip3 install --user virtualenv
$ vim ~/.bash_profile

Add the following to .bash_profile, save and quit:

alias virtualenv3='~/Library/Python/3.4/bin/virtualenv'

Update the current Terminal window to use the alias you just saved:

$ source ~/.bash_profile

Create a place for the virtual environment to live on your hard drive. We recommend installing it outside of "PythonProjects" folder:

$ mkdir /Users/<YOUR NAME HERE>/PythonEnvironments/
$ cd /Users/<YOUR NAME HERE>/PythonEnvironments/
$ virtualenv3 WeVoteServer3.4

Now activate this new virtual environment for WeVoteServer:

$ cd /Users/<YOUR NAME HERE>/PythonProjects/WeVoteServer/
$ source /Users/<YOUR NAME HERE>/PythonEnvironments/WeVoteServer3.4/bin/activate
$ pip install -r requirements.txt
$ python runserver

Running Linux?

If you are installing on a Linux environment, we recommend the following steps within your virtual environment. If you are installing on a Mac or Windows machine, you can skip these steps.


sudo apt-get install python-psycopg2 
sudo apt-get install python-dev
pip install psycopg2 


pip install django-toolbelt
pip install --upgrade pip
pip install -r requirements.txt

Setup - Install the Postgres database

METHOD 1 (Mac)

For Mac, download and install the DMG from

Run this on your command line:

export PATH=$PATH:/Applications/

Start up the command line for postgres (there is an 'open psql' button/navigation item if you installed postgresapp. Run these commands:

create role postgres;
alter role postgres with login;

METHOD 2 (Windows)

Install Postgres:

$ sudo port install postgresql94
$ sudo port install postgresql94-server

METHOD 3 (linux Ubuntu)

Follow these instructions

Setup - Install PG Admin III

We recommend installing pgAdmin3 as a WYSIWYG database administration tool. NOTE: You may need to turn off the restriction in "Security & Privacy" on "unidentified developers" to allow this tool to be installed. See:

In pgadmin add a server. You can use your sign in name as the server name.

Setup - Environment Variables Configuration - config/environment_variables.json

Copy "config/environment_variables-template.json" to "config/environment_variables.json". You will configure many variables for your local environment in this file.

New variables needed by WeVoteServer will be added to "environment_variables-template.json" from time to time, so please check for updates by comparing your local version with the template file.


Create a file on your computer to match the one expected in the environment_variables.json file:

sudo mkdir /var/log/wevote/
sudo touch /var/log/wevote/wevoteserver.log
sudo chmod -R 0777 /var/log/wevote/

As configured in github, only errors get written to the log. Logging has five levels: CRITICAL, ERROR, INFO, WARN, DEBUG. It works as a hierarchy (i.e. INFO picks up all messages logged as INFO, ERROR and CRITICAL), and when logging we specify the level assigned to each message. You can change this to info items by changing this:


Set up GeoIP

Install the C library

Start by changing directories into your WeVoteServer folder:

$ cd /Users/<YOUR NAME HERE>/PythonProjects/WeVoteServer/
$ git clone
$ cd geoip-api-c
$ ./bootstrap
$ ./configure
$ make

In the "make check" step, you may see some errors like "make[2]: * [install-libLTLIBRARIES] Error 1". These errors won't prevent geoip from working.

$ make check
$ make install
$ cd ..

On OS X 10.10.5 I got an error (autoreconf: command not found), and had to do this first:

$ brew install automake
$ brew install libtool

“ cannot open..."

On Amazon Linux (Fedora), if you get a “ cannot open shared object No such file or directory” error when you run WeVoteServer:

$ sudo vi /etc/

Add on a new line:


Then run:

$ sudo ldconfig

Run the command that downloads the GeoLite database from the WeVoteServer root folder (Where this README lives)

$ ./ update_geoip_data

On Amazon Web Services - NOT for local install

Buy the latest database ("GEO-133 GeoIP Legacy City with DMA/Area Codes") at

Find and copy the GZIP download link from this page which will look like:

Transfer it to the live API server:

$ cd /home/wevote/WeVoteServer/geoip/import_data/
$ mv geoip_download\?edition_id\=133\&date\=20160202 GeoIP-133_DATE_HERE.tar.gz
$ chmod 0777 GeoIP-133_DATE_HERE.tar.gz
$ tar zxvf GeoIP-133_DATE_HERE.tar.gz
$ cp GeoIP-133_20160202/GeoIPCity.dat .
$ chmod 0777 *.*

Setup - Database Creation

If you would like to match the local database settings from the "config/environment_variables.json" file, (Search for "DATABASES"):

createdb WeVoteServerDB

Populate your database with the latest database tables:

python makemigrations
python migrate

Create the initial database:

$ python syncdb

When prompted for a super user, enter your email address and a simple password. This admin account is only used in development.

If you are not prompted to create a superuser, run the following command:

python createsuperuser

Test that WeVoteServer is running

Start up the webserver:

$ cd /Users/<YOUR NAME HERE>/PythonProjects/WeVoteServer/
$ source /Users/<YOUR NAME HERE>/PythonEnvironments/WeVoteServer3.4/bin/activate
$ pip install -r requirements.txt
$ python runserver

Grant yourself Admin rights

Find admin tools here:


Now you will need to authenticate as an admin. For now, this will require that you log in with your Twitter account. Please contact for configuration settings you can add to your local config/environment_variables.json file.

Click "Sign in with Twitter" and use your Twitter credentials to Sign-In. 

After you have signed in, you will see an error message in red that states "You must sign in with account that has Verified Volunteer rights to see that page." Just below the error message, there will be a field "we_vote_id" with a text string like "wv01voter1234" next to it, note the we_vote_id number.

Give yourself Admin rights via PGAdmin

Open PG Admin III and navigate to:

Server Groups > Servers > WeVoteServerDB 

Double click on WeVoteServerDB (there may be a red x thru it). It will prompt you for a password; leave it blank and click OK. You may see an additional warning screen about saving passwords, if so, click ok. Once you are connected, navigate to:

WeVoteServerDB > Schemas > public > Tables > voter_voter

Then, right click, and in the menu that appears, select:

View Data > View Top 100 rows

In the new window that opens, scroll down and find the we_vote_id number, noted above. Scroll to the right to locate the box "is_admin" click on it once, and a box will appear, click it and change it to TRUE. Then, go back to your browser, and click on:

Back to Admin Home

Give yourself Admin rights via command line

Run this command from your Postgres command line. Replace WE_VOTE_ID_HERE with the actual we_vote_id found above:

UPDATE voter_voter SET is_admin=true WHERE we_vote_id='WE_VOTE_ID_HERE';

Test your access

Now, you should be able to access the admin tools.

Find documentation for all of the APIs here:


Sample data

Sample data is provided. Go here:


Find the "Sync Data with Master We Vote Servers" link, and click it: http://localhost:8000/admin/sync_dashboard/

Choose 1) an upcoming election from the drop down, and 2) your local state, and then run all scripts from top to bottom.

Google Civic

In order to retrieve fresh ballot data, you will need to sign up for a Google Civic API key:

Vote Smart

We also have a paid subscription with Vote Smart. You can sign up for a Vote Smart developer key, or reach out to to discuss using our organizational account.

  • Copy your Vote Smart key and paste it into config/environment_variables.json as the value for VOTE_SMART_API_KEY


Instructions coming soon.

Working with WeVoteServer day-to-day

Back to root README