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 MoveOn.org at https://github.com/MoveOnOrg/Spoke.
This repository is a branch of MoveOn/Spoke created by Politics Rewired, a small campaign tech consultancy created in 2019.
Due to a desire to develop more quickly, we did not maintain compatibility with MoveOn/Spoke, which means although this repository will be
a useful source of ideas, it may more work than is worth it to merge it back into MoveOn/Spoke, although we welcome any efforts towards
that goal. See HOWTO_migrate-from-moveon-main.md
.
Runtimes and package managers:
- Node (^16.14)
- Yarn (>= 1.19.1)
External services:
- Postgres (>= 11)
Recommended:
- Docker, for running Postgres as a container
We recommend using the asdf version manager.
# Example using `asdf` (https://github.com/asdf-vm/asdf)
asdf plugin add nodejs https://github.com/asdf-vm/asdf-nodejs.git
asdf plugin add yarn https://github.com/twuni/asdf-yarn
asdf install
You can also install the prereqs manually:
If you have Docker installed, we recommend using Postgres as a container.
Spoke Rewired comes with a postgres
container in docker-compose.yml
, which you can start with the following command:
# Run in the foreground, so you can watch logs and stop with Ctrl-C
docker compose up postgres
# Run in the background so you can use the terminal for other things
docker compose up postgres -d
# (if you have an older version of Docker installed, you may have to run
# "docker-compose" with a hyphen instead of "docker compose" with a space)
The postgres
container will automatically start up a server with the following configuration:
- connection string (for
DATABASE_URL
):postgres://spoke:spoke@localhost:15432/spokedev
- port: 15432
- default database:
spokedev
- user:
spoke
- password:
spoke
To stop all containers, including Postgres, run:
docker compose down
To delete all container data, including the Postgres database, and stop all containers, run:
docker compose down -v
After the database container is taken down, you can run the up
commands above to restart it. For more information, see the Docker Compose reference documentation.
You can also install and run a Postgres server manually without Docker:
git clone git@github.com:politics-rewired/Spoke.git
cd Spoke
git config --local blame.ignoreRevsFile .git-blame-ignore-revs
yarn install
You will need to update the database connection string: it should contain the correct host, port, and username/password credentials to your development Postgres server.
cp .env.example .env
vi .env
# in this case, the server is running at port 5432 (the default Postgres port)
# DATABASE_URL=postgres://spoke:spoke@localhost:5432/spokedev
psql -c "create database spokedev;"
yarn migrate:worker
yarn knex migrate:latest
yarn codegen
yarn dev
For development, you can set DEFAULT_SERVICE=fakeservice
to skip using an SMS provider (Assemble Switchboard or Twilio) and insert the message directly into the database. This is set by default in .env
.
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.
Spoke uses knex
to manage application schema. Spoke also uses graphile-worker
as it's database-backed job queue.
graphile-worker
The graphile-worker
migrations only need to be run once:
yarn migrate:worker
knex
The knex migrations need to be run any time a new release has made changes to the application schema, as indicated by a new migration file in ./migrations
. Some migrations require application downtime, some do not. It is up to YOU to review migration notes before rolling out a new release.
yarn knex migrate:latest
To create a new knex migration, run
yarn knex migrate:make my-migration
All configuration environment variables are documented in config.js.
You can also find developer documentation and guides in the docs directory.
This project adheres to the Conventional Commits specification. You can use yarn commit
instead of git commit
.
Pull Request merges should use the "Squash and merge" strategy. The final commit message should include relevant information from the component commits and its heading should reflect the purpose of the PR itself; if the PR adds a feature, it should be a feat: add feature x
even if it includes a necessary bug fix (ideally unrelated bug fixes are submitted as separate PRs in the first place).
Each release gets its own commit on main
that includes the version bump and changelog updates. The version bump, changelog updates, commit, and tag are generated by standard-version
:
yarn release
Other helpful options are:
# Preview the changes
yarn release --dry-run
# Specify the version manually
yarn release --release-as 1.5.0
# or the semver version type to bump
yarn release --release-as minor
# Specify an alpha release
yarn release --prerelease
# or the pre-release type
yarn release --prerelease alpha
If you plan to build container images locally for use in production you may want to set the default architecture by adding the following to your shell config (e.g. ~/.bash_profile
):
export DOCKER_DEFAULT_PLATFORM=linux/amd64
or pass --platform=linux/amd64
to all docker buildx
commands.
Spoke can be deployed in a variety of different ways. We use Kubernetes internally and are only currently maintaining the Docker image. See the developer documentation for more information about other deployment methods.
See LICENSE.