The ksvotes.org site makes Kansas online voting registration easy.
You run PostgreSQL and Redis via Docker.
See the docker-compose.yml
file in the repo. You can use with:
$ make services-start
$ make services-stop
Redis is used for caching stats and external API calls.
Once you have PostgreSQL available, you must create database instances for local use. DB setup reference
Create databases for development and testing. In the Environmental Variables
section below we assume the names you picked were ksvotes_dev
and ksvotes_test
.
Recommendations for running after cloning:
Install Python 3.10+
Install pip
Install virtualenv
In app root directory setup your virtualenv and install dependencies to your virtualenv python.
$ python3 -m venv venv
$ . venv/bin/activate
$(venv) make deps
$(venv) make locales
You'll want to add some entries to your local /etc/hosts
file to make using Docker easier.
127.0.0.1 ksvotes-postgres
127.0.0.1 redis
127.0.0.1 test.ksvotes.org
$(venv) PGPASSWORD=postgres psql -c 'create database "ksvotes.org_test";' -U postgres -h ksvotes-postgres
$(venv) PGPASSWORD=postgres psql -c 'create database "ksvotes.org_dev";' -U postgres -h ksvotes-postgres
$(venv) psql -c "create user foo with password 'bar';" -U postgres -h ksvotes-postgres
Create a .env file in the root directory and add the following variables.
Note that the commented-out (#
-prefixed) variables are optional.
DATABASE_URL=postgresql://foo:bar@ksvotes-postgres/ksvotes_dev
TESTING_DATABASE_URL=postgresql://foo:bar@ksvotes-postgres/ksvotes_test
SECRET_KEY={{generate a secret key}}
APP_CONFIG=development
CRYPT_KEY={{generate a secret key | base64}}
# Set this to enable the /demo endpoint
DEMO_UUID={{generate a UUID and run "make load-demo"}}
# You can grab one from the URL below or take the one from the staging configuration
USPS_USER_ID={{key from https://registration.shippingapis.com/}}
#########################
# OPTIONAL ENV VARS
#########################
# LOG_LEVEL=INFO
# GA_KEY={{google analytics key}}
# RECAPTCHA_KEY={{public key}}
# RECAPTCHA_SECRET={{private key}}
# AWS_ACCESS_KEY_ID={{from role with at least rds access}}
# AWS_SECRET_ACCESS_KEY={{from role with at least rds access}}
# AWS_DEFAULT_REGION={{us-east-1 || or your region where RDS is hosted}}
# SES_ACCESS_KEY_ID={{from role with ses access}}
# SES_SECRET_ACCESS_KEY={{from role with ses access}}
# TEST_CLERK_EMAIL={{override the Clerk.email value for the TEST County}}
# EMAIL_FROM={{override the From email header in all email}}
# EMAIL_PREFIX={{prefix all Subject lines with a string}}
# Default is not to send actual email unless SEND_EMAIL is set
# SEND_EMAIL=true
# Number of minutes before idle session expires. Default is 10.
# SESSION_TTL=10
# You want the default VV URL unless you are testing error checking.
# VOTER_VIEW_URL=https://myvoteinfo.voteks.org/VoterView/RegistrantSearch.do
# The date and time prior to the Primary election when the Advance Ballot
# option for the Primary disappears. Format is 'YYYY-MM-DD HH:MM:SS' and assumes
# a Central US time zone
# AB_PRIMARY_DEADLINE="2020-05-01 17:00:00"
# Turn the AB flow on. Default is off.
# ENABLE_AB=true
# Turn VIT voting location JS widget on. Default is off.
# ENABLE_VOTING_LOCATION=true
# Turn off HTTPS requirement. Probably set this to true in your local dev.
# SSL_DISABLE=true
# Turn on lots of SQL debugging.
# SQL_DEBUG=true
# Include the top banner on every page that this is not the live production site.
# STAGE_BANNER=true
# Airtable is managed by ksvoterguide.org folks for early voting and ballot dropbox locations.
# AIRTABLE_EV_KEY=sekrit
# AIRTABLE_EV_BASE_ID=sekrit
# to temporarily disable, leave the table names commented out
# AIRTABLE_EV_TABLE='SoS 10-19-2020'
# AIRTABLE_DROPBOX_TABLE='dropbox 2020'
The encryption key is kind of particular, it needs to be 32 bytes long and URl-safe base64 encoded. Use this command to generate one for you using the cryptography library:
$(venv) make crypt-key
We need DEMO_UUID
set to a UUID, use this to generate one for you quickly:
$(venv) make demo-uuid
You can check that your local env has all of the requried environment variables set by running:
($venv) make check
Once setup is complete let's get our models imported into our development database.
$(venv) make dbupgrade
When you modify the model classes and want to apply to the schema:
$(venv) make update
Let's get up and running.
First, build the container image:
$(venv) make container-build
Second, login to the container:
$(venv) make login
If you get an error like docker: Error response from daemon: network ksvotesorg_app-tier not found.
make sure you have the redis/postgresql services running
with make services-stop
.
Third, start the app:
ksvotesapp@randomstr:/app$ make run
Navigate to test.ksvotes.org:5000
To run all unit tests (inside the Docker container):
ksvotesapp@randomstr:/app$ make test
To run all unit tests with coverage:
ksvotesapp@randomstr:/app$ make testcov
Run browser-based tests outside the container, on your native host:
$(venv) make playwright
Code is currently setup to SCSS with node scripts to compile.
Edit scss/source.scss
and compile with % make css
.
Alternatively you can create your own .css style sheet in app/static/css and replace
<link href="{{url_for('static', filename='css/compiled.css')}}" rel="stylesheet">
in app/templates/base.html with
<link href="{{url_for('static', filename='css/[[[name of your style sheet]]]')}}" rel="stylesheet">
To setup scss watcher in root directory run:
$ npm install
$ npm run watch
This application is using Flask-Babel
To add a new string, reference the string in the .py code with gettext()
or lazy_gettext()
and then run % make locales
to update the corresponding babel files. For example:
# in foo.py
lazy_gettext('some_key_string')
# add 'some_key_string' to translations.json
% vi translations.json
# Then in your terminal
# update the translation files
% make locales