Skip to content
mass-contact text/SMS distribution tool
JavaScript Other
Branch: main
Clone or download

Latest commit

Latest commit 638f30f Mar 25, 2020


Type Name Latest commit message Commit time
Failed to load latest commit information.
.github/ISSUE_TEMPLATE merging main into add-aliasName - fixing conflicts Feb 10, 2020
__mocks__ run prettier on all files Aug 5, 2019
__test__ remove a couple of console.logs Mar 25, 2020
deploy Removes references to unused PUBLIC_DIR Apr 16, 2019
dev-tools ability to load config files from a deployed file instead of just env… Jan 6, 2020
docs Merge pull request #1460 from MoveOnOrg/release-notes-53 Mar 25, 2020
migrations Merge branch 'pr/1365' into stage-main Feb 24, 2020
src remove some console.logs associated with debugging createoptout permi… Mar 25, 2020
webpack run prettier on all files Aug 5, 2019
.babelrc got rid of some changes we didn't need Jul 4, 2018
.dockerignore feat(docker): build from local source Mar 14, 2019
.env.example Document local login as the dev default and add docs list to README May 18, 2019
.eslintignore chore(eslint): ignore build output Mar 14, 2019
.eslintrc eslintrc fix Feb 19, 2020
.gitattributes insert better warnings about linefeeds into the code Jun 21, 2019
.gitignore ability to load config files from a deployed file instead of just env… Jan 6, 2020
.nvmrc bumped node version to 10.3 May 28, 2019
.prettierignore Add config files for prettier: package install of prettier + husky + … Aug 5, 2019
.prettierrc fix smart quotes Feb 12, 2020
.travis.yml enable sqlite tests on travis Jan 25, 2020 Integrate Citizen Code of Conduct with more explicit expected/unaccep… Nov 11, 2019 Merge new changes in from main Sep 19, 2019
Dockerfile update node in dockerfile May 28, 2019
LICENSE Add Sheena to license May 17, 2017
Procfile chore(heroku): extract BASE_URL parsing logic Mar 21, 2019 Version 5.3 release notes Mar 25, 2020
app.json Switch default passport_strategy on Heroku deploys to local for revie… Nov 26, 2019
docker-compose.yml adds directory file path as var to docker and heroku vars config Sep 9, 2019
heroku.yml chore(heroku): use container runtime Mar 14, 2019
jest.config.e2e.js run prettier on all files Aug 5, 2019
jest.config.js ability to load config files from a deployed file instead of just env… Jan 6, 2020
jest.config.sqlite.js fix most tests for test-sqlite Jan 25, 2020
knexfile.env.js run prettier on all files Aug 5, 2019
lambda.js fix comment to be accurate Dec 7, 2019
nodemon.json Ignore client-side code as it is already being monitored by webpack. Apr 5, 2019
package.json CONTACT_CACHE_ENABLED setting and allow admins to access getAssignmen… Mar 17, 2020 Merge new changes in from main Sep 19, 2019
readmestaging20180902 Create readmestaging20180902 Sep 3, 2018
travis-run-e2e-tests Removes travis-run-e2e-test script from travis config May 1, 2019
yarn.lock merge main into scaling-feb20-1-campaigncontact Feb 24, 2020

Build Status Contributor Covenant


Spoke is an open source text-distribution tool for organizations to mobilize supporters and members into action. Spoke allows you to upload phone numbers, customize scripts and assign volunteers to communicate with supporters while allowing organizations to manage the process.

Spoke was created by Saikat Chakrabarti and Sheena Pakanati, and is now maintained by

The latest version is 5.3 (see release notes) which we recommend for production use, while our main branch is where features still in development and testing will be available.

Deploy to Heroku


Follow up instructions located here.

Please let us know if you deployed by filling out this form here

Getting started


  1. Install either sqlite, postgres, or another knex-supported database.
  2. Install the Node version listed in .nvmrc. NVM is one way to do this (from the spoke directory):
    nvm install
    nvm use
  3. Install yarn.
  1. Install the packages.
    yarn install
  2. Create a real environment file:
    cp .env.example .env
  • This creates a copy of .env.example, but renames it .env so the system will use it. Make sure you use this new file.

Filling out your .env file

You now have a .env file to fill out. For more details on environment variables you can change, see the environment variable reference.

There are some common environment variables you will want to adjust:

  1. To skip using the SMS provider (useful for development), set DEFAULT_SERVICE=fakeservice.
  2. Determine which database to use and set the necessary variables, listed in the reference.
  1. Determine which authentication system you want to use. For development, there are a few ways authenticate.

Getting the app running

At this point, you should be ready to start your app in development mode.

  1. Run yarn dev to create and populate the tables.
    • Wait until you see both "Node app is running ..." and "webpack: Compiled successfully." before attempting to connect. (make sure environment variable JOBS_SAME_PROCESS=1)
  2. Go to http://localhost:3000 to load the app. (Note: the terminal will say it's running on port 8090 -- don't believe it :-)
  3. As long as you leave SUPPRESS_SELF_INVITE= blank in your .env you should be able to invite yourself from the homepage.
    • If you DO set that variable, then spoke will be invite-only and you'll need to generate an invite. Run:
      echo "INSERT INTO invite (hash,is_valid) VALUES ('abc', 1);" |sqlite3 mydb.sqlite
      # Note: When doing this with PostgreSQL, you would replace the `1` with `true`
    • Then use the generated key to visit an invite link, e.g.: http://localhost:3000/invite/abc. This should redirect you to the login screen. Use the "Sign Up" option to create your account.
  4. You should then be prompted to create an organization. Create it.
  5. See the Admin and Texter demos to learn about how Spoke works.
  6. See Getting Started with Development below.
  7. See How to Run Tests


For development, you can set DEFAULT_SERVICE=fakeservice to skip using an SMS provider (Twilio or Nexmo) and insert the message directly into the database.

To simulate receiving a reply from a contact you can use the Send Replies utility: http://localhost:3000/admin/1/campaigns/1/send-replies, updating the app and campaign IDs as necessary. You can also include "autorespond" in the script message text, and an automatic reply will be generated (just for fakeservice!)


Twilio provides test credentials that will not charge your account as described in their documentation. To setup Twilio follow our Twilio setup guide.

Getting started with Docker

Docker is optional, but can help with a consistent development environment using postgres.

  1. cp .env.example .env and see the "Filling out your .env file" section above for some possible tweaks
  2. Build and run Spoke with docker-compose up --build
    • You can stop docker compose at any time with CTRL+C, and data will persist next time you run docker-compose up.
  3. Go to localhost:3000 to load the app.
    • But if you need to generate an invite, run:
      docker-compose exec postgres psql -U spoke -d spokedev -c "INSERT INTO invite (hash,is_valid) VALUES ('<your-hash>', true);"
    • Then use the generated key to visit an invite link, e.g.: http://localhost:3000/invite/<your-hash>. This should redirect you to the login screen. Use the "Sign Up" option to create your account.
  4. You should then be prompted to create an organization. Create it.
  5. When done testing, clean up resources with docker-compose down, or docker-compose down -v to completely destroy your Postgres database & Redis datastore volumes.

More Documentation

Deploying Minimally

There are several ways to deploy documented below. This is the 'most minimal' approach:

  1. Run OUTPUT_DIR=./build yarn run prod-build-server This will generate something you can deploy to production in ./build and run nodejs server/server/index.js
  2. Run yarn run prod-build-client
  3. Make a copy of deploy/spoke-pm2.config.js.template, e.g. spoke-pm2.config.js, add missing environment variables, and run it with pm2, e.g. pm2 start spoke-pm2.config.js --env production
  4. Install PostgreSQL
  5. Start PostgreSQL (e.g. sudo /etc/init.d/postgresql start), connect (e.g. sudo -u postgres psql), create a user and database (e.g. create user spoke password 'spoke'; create database spoke owner spoke;), disconnect (e.g. \q) and add credentials to DB_ variables in spoke-pm2.config.js

Big Thanks

Cross-browser Testing Platform and Open Source <3 Provided by Sauce Labs.


Spoke is licensed under the MIT license.

You can’t perform that action at this time.