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.
The latest version is 1.4.1 (see release notes) which we recommend for production use, while our main branch is where features still in development and testing will be available.
This is generated from react-apollo-starter-kit. Look at that project's README for info on some of the libraries used.
Follow up instructions located here
Please let us know if you deployed by filling out this form here
- Install either sqlite (or another knex-supported database)
- Install the Node version listed under
enginesinpackage.json. NVM is one way to do this. yarn installcp .env.example .env- If you want to use Postgres:
- In
.envsetDB_TYPE=pg. (Otherwise, you will use sqlite.) - Set
DB_PORT=5432, which is the default port for Postgres. - Create the spokedev database:
psql -c "create database spokedev;"
- In
- Create an Auth0 account. In your Auth0 account, go to Applications, click on
Default Appand then grab your Client ID, Client Secret, and your Auth0 domain (should look like xxx.auth0.com). Add those inside your.envfile (AUTH0_CLIENT_ID, AUTH0_CLIENT_SECRET, AUTH0_DOMAIN respectively). - Run
yarn devto create and populate the tables. - In your Auth0 app settings, add
http://localhost:3000/login-callback,http://localhost:3000andhttp://localhost:3000/logout-callbackto "Allowed Callback URLs", "Allowed Web Origins" and "Allowed Logout URLs" respectively. (If you get an error when logging in later about "OIDC", go to Advanced Settings section, and then OAuth, and turn off 'OIDC Conformant') - Add a new rule in Auth0:
function (user, context, callback) {
context.idToken["https://spoke/user_metadata"] = user.user_metadata;
callback(null, user, context);
}-
Update the Auth0 Universal Landing page, click on the
Customize Login Pagetoggle, and copy and paste following code in the drop down into theDefault Templatesspace:Code to paste into Auth0
<!DOCTYPE html> <html> <head> <meta charset="utf-8"> <meta http-equiv="X-UA-Compatible" content="IE=edge,chrome=1"> <title>Sign In with Auth0</title> <meta name="viewport" content="width=device-width, initial-scale=1.0" /> </head> <body> <!--[if IE 8]> <script src="//cdnjs.cloudflare.com/ajax/libs/ie8/0.2.5/ie8.js"></script> <![endif]--> <!--[if lte IE 9]> <script src="https://cdn.auth0.com/js/base64.js"></script> <script src="https://cdn.auth0.com/js/es5-shim.min.js"></script> <![endif]--> <script src="https://cdn.auth0.com/js/lock/11.11/lock.min.js"></script> <script> // Decode utf8 characters properly var config = JSON.parse(decodeURIComponent(escape(window.atob('@@config@@')))); config.extraParams = config.extraParams || {}; var connection = config.connection; var prompt = config.prompt; var languageDictionary; var language; if (config.dict && config.dict.signin && config.dict.signin.title) { languageDictionary = { title: config.dict.signin.title }; } else if (typeof config.dict === 'string') { language = config.dict; } var loginHint = config.extraParams.login_hint; // Available Lock configuration options: https://auth0.com/docs/libraries/lock/v11/configuration var lock = new Auth0Lock(config.clientID, config.auth0Domain, { auth: { redirectUrl: config.callbackURL, responseType: (config.internalOptions || {}).response_type || (config.callbackOnLocationHash ? 'token' : 'code'), params: config.internalOptions }, // Additional configuration needed for custom domains: https://auth0.com/docs/custom-domains/additional-configuration // configurationBaseUrl: config.clientConfigurationBaseUrl, // overrides: { // __tenant: config.auth0Tenant, // __token_issuer: 'YOUR_CUSTOM_DOMAIN' // }, assetsUrl: config.assetsUrl, allowedConnections: ['Username-Password-Authentication'], rememberLastLogin: !prompt, language: language, languageDictionary: { title: 'Spoke', signUpTerms: 'I agree to the <a href="YOUR_LINK HERE" target="_new">terms of service and privacy policy</a>.' }, mustAcceptTerms: true, theme: { logo: '', primaryColor: 'rgb(83, 180, 119)' }, additionalSignUpFields: [{ name: 'given_name', icon: 'https://upload.wikimedia.org/wikipedia/commons/c/ca/1x1.png', placeholder: 'First Name' }, { name: 'family_name', placeholder: 'Last Name', icon: 'https://upload.wikimedia.org/wikipedia/commons/c/ca/1x1.png' }, { name: 'cell', placeholder: 'Cell Phone', icon: 'https://upload.wikimedia.org/wikipedia/commons/c/ca/1x1.png', validator: (cell) => ({ valid: cell.length >= 10, hint: 'Must be a valid phone number' }) }], prefill: loginHint ? { email: loginHint, username: loginHint } : null, closable: false, defaultADUsernameFromEmailPrefix: false, // Uncomment if you want small buttons for social providers // socialButtonStyle: 'small' }); lock.show(); </script> </body> </html>
-
If the application is still running from step 8, kill the process and re-run
yarn devto restart the app. Wait until you see both "Node app is running ..." and "webpack: Compiled successfully." before attempting to connect. (make sure environment variableJOBS_SAME_PROCESS=1) -
Go to
http://localhost:3000to load the app. -
As long as you leave
SUPPRESS_SELF_INVITE=blank and unset in your.envyou 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.
- If you DO set that variable, then spoke will be invite-only and you'll need to generate an invite. Run:
-
You should then be prompted to create an organization. Create it.
If you want to create an invite via the home page "Login and get started" link, make sure your SUPPRESS_SELF_INVITE variable is not set.
cp .env.example .env- Follow Steps 7, 9, & 10 above to set up your Auth0 account.
- 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 rundocker-compose up.
- You can stop docker compose at any time with
- Go to localhost:3000 to load the app.
- Follow Step 13 above.
- 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.
- But if you need to generate an invite, run:
- You should then be prompted to create an organization. Create it.
- When done testing, clean up resources with
docker-compose down, ordocker-compose down -vto completely destroy your Postgres database & Redis datastore volumes.
See https://github.com/MoveOnOrg/Spoke/blob/main/docs/HOWTO-run_tests.md
Cross-browser Testing Platform and Open Source <3 Provided by Sauce Labs.
- Run
sqlite3 mydb.sqliteto connect to a SQL shell for the dev database - Set up an ESLint plugin in your code editor so that you catch coding errors and follow code style guidelines more easily!
- Install the redux-devtools-extension in Chrome to get advanced Redux debugging features.
- Right now there is a bug in Apollo (apollographql/react-apollo#57) that means in one particular case, errors get swallowed. If you end up with an app that is silently breaking, console.log(this.props.data) and check the errors property.
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.
Twilio
Twilio provides test credentials that will not charge your account as described in their documentation. You may use either your test credentials or your live keys by following the instructions here.
- Run
OUTPUT_DIR=./build yarn run prod-build-serverThis will generate something you can deploy to production in ./build and run nodejs server/server/index.js - Run
yarn run prod-build-client - 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 - Install PostgreSQL
- 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 toDB_variables in spoke-pm2.config.js
Spoke is licensed under the MIT license.