startup tweaks and README additions

.gitignore

@@ -9,8 +9,10 @@ media/
 static/CACHE/
 node_modules/
 staticfiles/
+.DS_Store
 
 # Elastic Beanstalk Files
 .elasticbeanstalk/*
 !.elasticbeanstalk/*.cfg.yml
 !.elasticbeanstalk/*.global.yml
+

README.md

@@ -10,6 +10,8 @@ It has been published in the [Washington Post](https://www.washingtonpost.com/dc
 
 While you may fork and run this code to run it locally, almost all users find it sufficient to upload data directly to RCVis.com.
 
+<br>
+
 # Ranked Choice Voting Visualization
 Visualize the results of ranked-choice voting elections.
 
@@ -21,65 +23,35 @@ Visualize the results of ranked-choice voting elections.
 
 Learn more on our Medium post: [An Illustrated Guide to Ranked-Choice Voting](https://medium.com/@armin.samii/an-illustrated-guide-to-ranked-choice-voting-4ce3c5fe73f9).
 
-## Installation
-Install `python3`, `virtualenv`, and `npm` with your favorite package manager, then run `./scripts/install.sh`.
-
-Create a .env file with your secrets and configuration options:
-
-```bash
-export RCVIS_SECRET_KEY=''
-export RCVIS_DEBUG=True
-export RCVIS_HOST=localhost
-
-# Either have OFFLINE_MODE=True
-export OFFLINE_MODE=True
-
-# The following fields are optional, though you will
-# have limited functionality without them.
+## Examples
+Check out [rcvis.com](https://www.rcvis.com) for live examples, including:
 
-# Or set up an AWS bucket and enter your credentials
-# export OFFLINE_MODE=False
-# export AWS_STORAGE_BUCKET_NAME=''
-# export AWS_S3_REGION_NAME=''
-# export AWS_ACCESS_KEY_ID=''
-# export AWS_SECRET_ACCESS_KEY=''
+| Barchart | Round-by-Round |
+| --- | --- |
+| ![Barchart](static/visualizer/icon_interactivebar.gif "Interactive Barchart") | ![Round-by-Round](static/visualizer/icon_interactiveroundbyround.gif "Round-by-Round") |
 
-# To send registration emails when OFFLINE_MODE is False:
-# export SENDGRID_USERNAME=''
-# export SENDGRID_PASSWORD=''
+| Sankey | Tabular Summary |
+| --- | --- |
+| ![Sankey](static/visualizer/icon_sankey.jpg "Sankey") | ![Tabular Summaries](static/visualizer/icon_singletable.png "Tabular Summaries") |
 
-# To clear cloudflare cache when models update:
-# export CLOUDFLARE_ZONE_ID=''
-# export CLOUDFLARE_AUTH_TOKEN=''
+## Embedding
+RCVis implements the [oembed protocol](http://www.oembed.com) with discoverability, allowing you to embed files into your website with an iframe.
 
-# To run the SauceLabs integration tests, you will need
-export SAUCE_USERNAME=''
-export SAUCE_ACCESS_KEY=''
+<br>
 
-# To generate videos (and to run movie tests), you will need:
-export IMAGEIO_FFMPEG_EXE='/usr/bin/ffmpeg'
-export SQS_QUEUE_NAME='default-queue'
-# export MOVIE_FONT_NAME="Roboto"
-# export AWS_POLLY_STORAGE_BUCKET_NAME="bucket-name-on-s3"
+# Running RCVis Locally
 
-# To subscribe users to mailchimp upon registration, you need:
-# export MAILCHIMP_API_KEY=''
-# export MAILCHIMP_LIST_ID=''
-# export MAILCHIMP_DC=''
+## Installation
+Install `python3`, `virtualenv`, `npm`, and `postgresql` with your favorite package manager, then run `./scripts/install.sh`. This script will initalize a `.env` file in the root directory for your secrets and configuration. You will need to supply a secret key and local host IP address before proceeding.
 
-# If you are updating a template, you'll need to clear the cache every time or set:
-# export DISABLE_CACHE=True
 
-```
+## Running
 
-To get moviepy working for Ubuntu 16.04 LTS users, comment out the following statement in `/etc/ImageMagick-6/policy.xml`:
-```xml
-<policy domain="path" rights="none" pattern="@*"/>
+To upload data and generate visuals, you will need to create a local user with credentials from your `.env` file using:
+```bash
+./scripts/create-user.sh
 ```
-or, simply run `sudo ./scripts/fix-moviepy-on-ubuntu-1604.sh`
-
-## Running
-To begin serving the website at localhost:8000:
+You can then begin serving the website at localhost:8000:
 ```bash
 ./scripts/serve.sh
 ```
@@ -93,24 +65,8 @@ npm install  # this works for me
 python3 manage.py npminstall  # this is purported to work but doesn't
 ```
 
-To run workers to generate movies (optional - only needed to use the movie generation flow):
-```bash
-source .env
-source venv/bin/activate
-export DISPLAY=":0" # if not already set
-celery -A rcvis worker --loglevel info
-```
-
-## Examples
-Check out [rcvis.com](https://www.rcvis.com) for live examples, including:
-
-| Barchart | Round-by-Round |
-| --- | --- |
-| ![Barchart](static/visualizer/icon_interactivebar.gif "Interactive Barchart") | ![Round-by-Round](static/visualizer/icon_interactiveroundbyround.gif "Round-by-Round") |
-
-| Sankey | Tabular Summary |
-| --- | --- |
-| ![Sankey](static/visualizer/icon_sankey.jpg "Sankey") | ![Tabular Summaries](static/visualizer/icon_singletable.png "Tabular Summaries") |
+## Test Data
+Test data with election  can be found in the `testData` directory.
 
 ## REST API
 The primary API documentation is in the form of [example code](visualizer/tests/testRestApiExampleCode.py), which is documented line-by-line.
@@ -120,7 +76,7 @@ Addition documentation is available at [rcvis.com/api/](https://www.rcvis.com/ap
 To get started with programmatic access to rcvis:
 
 1. Create an account on RCVis
-2. Email [email protected] to enable API access
+2. Email [email protected] to request API access
 3. Submit a POST request to [https://www.rcvis.com/api/auth/get-token](https://www.rcvis.com/api/auth/get-token) to obtain an API Key, e.g. `curl -X POST https://www.rcvis.com/api/auth/get-token -d username=yourUserName -d password=yourAmazingPassword`
 
 With your API key, you may access two endpoints:
@@ -129,5 +85,20 @@ With your API key, you may access two endpoints:
 
 For both endpoints, upload with POST and modify with PUT or PATCH. Authenticated users are limited to 1000 requests per hour.
 
-## oembed
-RCVis implements the [oembed protocol](http://www.oembed.com) with discoverability, allowing you to embed files into your website with an iframe.
+<br>
+
+## Movies
+
+To get moviepy working for Ubuntu 16.04 LTS users, comment out the following statement in `/etc/ImageMagick-6/policy.xml`:
+```xml
+<policy domain="path" rights="none" pattern="@*"/>
+```
+or, simply run `sudo ./scripts/fix-moviepy-on-ubuntu-1604.sh`
+
+To run workers to generate movies (optional - only needed to use the movie generation flow):
+```bash
+source .env
+source venv/bin/activate
+export DISPLAY=":0" # if not already set
+celery -A rcvis worker --loglevel info
+```

infra/.env.template

@@ -0,0 +1,60 @@
+### The following fields must be provided to run RCVis locally and visualize results.
+
+# a user-generated string
+export RCVIS_SECRET_KEY=''
+
+# set to True to enable debug mode
+export RCVIS_DEBUG=True
+
+# host IP address
+export RCVIS_HOST=localhost
+
+# toggle offline mode
+export OFFLINE_MODE=True
+
+# credentials for local user in offline mode
+export OFFLINE_USERNAME=''       
+export OFFLINE_PASSWORD='' 
+
+### The following fields are optional, though you will have limited functionality without them.
+### We should add some explanation here about what "limited functionality" means.
+
+# authentication credentials for obtaining API key
+export USERNAME='your_username'        
+export PASSWORD='your_password' 
+
+# API key
+export API_KEY=''
+
+# set up an AWS bucket when OFFLINE_MODE is False:
+# export OFFLINE_MODE=False
+# export AWS_STORAGE_BUCKET_NAME=''
+# export AWS_S3_REGION_NAME=''
+# export AWS_ACCESS_KEY_ID=''
+# export AWS_SECRET_ACCESS_KEY=''
+
+# To send registration emails when OFFLINE_MODE is False:
+# export SENDGRID_USERNAME=''
+# export SENDGRID_PASSWORD=''
+
+# To clear cloudflare cache when models update:
+# export CLOUDFLARE_ZONE_ID=''
+# export CLOUDFLARE_AUTH_TOKEN=''
+
+# To run the SauceLabs integration tests:
+export SAUCE_USERNAME=''
+export SAUCE_ACCESS_KEY=''
+
+# To generate videos (and to run movie tests):
+export IMAGEIO_FFMPEG_EXE='/usr/bin/ffmpeg'
+export SQS_QUEUE_NAME='default-queue'
+# export MOVIE_FONT_NAME="Roboto"
+# export AWS_POLLY_STORAGE_BUCKET_NAME="bucket-name-on-s3"
+
+# To subscribe users to mailchimp upon registration:
+# export MAILCHIMP_API_KEY=''
+# export MAILCHIMP_LIST_ID=''
+# export MAILCHIMP_DC=''
+
+# If you are updating a template, you'll need to clear the cache every time or set:
+# export DISABLE_CACHE=True

infra/requirements-core.txt

@@ -1,4 +1,5 @@
-boto3==1.17.100
+boto3==1.26.0
+botocore==1.29.0
 csscompressor==0.9.5
 django-admin-cursor-paginator==0.1.3
 django-compressor==4.3.1

scripts/create-user.sh

@@ -0,0 +1,29 @@
+#!/bin/bash
+# Create or update a local server user using credentials from .env file
+
+# Source the .env file to get the environment variables
+source .env
+
+# Activate the virtual environment
+source venv/bin/activate
+
+# Run the Django shell to create or update the user
+python manage.py shell <<EOF
+from django.contrib.auth.models import User
+
+# Get the username and password from environment variables
+username = '$OFFLINE_USERNAME'
+password = '$OFFLINE_PASSWORD'
+
+# Check if the user already exists
+user, created = User.objects.get_or_create(username=username)
+if created:
+    user.set_password(password)
+    user.email = username
+    user.save()
+    print(f"User {username} created successfully.")
+else:
+    user.set_password(password)
+    user.save()
+    print(f"User {username} password updated successfully.")
+EOF

scripts/install.sh

@@ -8,6 +8,20 @@ pip3 install -r requirements.txt
 # Install npm deps
 npm i
 
+# initialize .env
+if [ -f .env ]; then
+    echo ""
+    echo ".env file already exists."
+    echo ""
+else
+    # Copy the template to .env
+    cp infra/.env.template .env
+    echo ""
+    echo ".env file has been initialized from the template."
+    echo "Please modify the .env file to include the necessary values."
+    echo ""
+fi
+
 # Run migrations to set up db
 source .env
 python3 manage.py migrate