REFERENCE-environment_variables.md

Variable	Purpose
ACTION_HANDLERS	Optional Action Handlers, listed in extensions/action-handlers. ngpvan-action required for VAN integration
ALLOW_SEND_ALL	Allow usage of the "Bulk Send" feature.
APOLLO_OPTICS_KEY	A key for Apollo tracer.
ASSETS_DIR	Directory path where front-end packaged JavaScript is saved and loaded. Required.
ASSETS_MAP_FILE	File name of map file, within ASSETS_DIR, containing map of general file names to unique build-specific file names.
ASSIGNMENT_CONTACTS_SIDEBAR	Show a sidebar with a list of contacts to the texter. Allows texter to freely navigate between conversations, regardless of status.
ASSIGNMENT_LOAD_LIMIT	Limit of contacts to load at one time for an assignment. Used when Spoke is deployed on a service with time and bandwidth limitations, such as AWS Lambda. Type: integer
AUTH0_DOMAIN	Domain name on Auth0 account, should end in .auth0.com, e.g. example.auth0.com. Required.
AUTH0_CLIENT_ID	Client ID from Auth0 app. Required.
AUTH0_CLIENT_SECRET	Client secret from Auth0 app. Required.
AWS_ACCESS_AVAILABLE	1 or 0 to enable or disable S3 campaign exports within Amazon Lambda.
AWS_ACCESS_KEY_ID	AWS access key ID with access to S3 bucket, required for campaign exports outside Amazon Lambda.
AWS_SECRET_ACCESS_KEY	AWS access key secret with access to S3 bucket, required for campaign exports outside Amazon Lambda.
AWS_S3_BUCKET_NAME	Name of S3 bucket for saving campaign exports.
AWS_REGION	Region of S3 bucket for saving campaign exports.
BASE_URL	The base URL of the website, without trailing slash, e.g. https://example.org, used to construct various URLs.
BULK_SEND_BATCH_SIZE	The number of texts to send out in 1 API call when using bulk send. Necessary to mitigate performance and timeout issues when BULK_SEND_CHUNK_SIZE is large.
BULK_SEND_CHUNK_SIZE	The number of texts to send out with 1 click of the "Bulk Send" button.
CACHE_PREFIX	If REDIS_URL is set, then this will prefix keys CACHE_PREFIX, which might be useful if multiple applications use the same redis server. Default: "".
CAMPAIGN_ID	Campaign ID used by dev-tools/export-query.js to identify which campaign should be exported.
CAMPAIGN_INVITES_CURRENT_USERS_ONLY	Campaign invites will only work for already-joined organization users (instead of auto-joining them to the organization)
CONTACTS_PER_PHONE_NUMBER	If EXPERIMENTAL_CAMPAIGN_NUMBERS is turned on, this is the ratio of contacts to phone numbers used to calculate the number of phone numbers required for a campaign, defaults to 200 per Twilio recommendations for P2P.
CONVERSATION_LIST_ROW_SIZES	The list of options for the number of conversations to show on each page in Message Review. If set this must be an array of integers. The numbers in the array do not need to be sorted. The first number in the array will be the default page size. Default: [10, 30, 50, 100]
DB_DEBUG	Boolean value to enable debugging of database queries (queries will be logged to the console). Default: false.
DB_HOST	Domain or IP address of database host.
DB_MAX_POOL	Database connection pool maximum size. Default: 10.
DB_MIN_POOL	Database connection pool minimum size. Default: 2.
DB_NAME	Database connection name. Required.
DB_PORT	Database connection port. Required.
DB_SCHEMA	Optional postgres database schema to use instead of public. Useful for running multiple instances on a shared DB server. Default: ""
DB_TYPE	Database connection type for Knex. Options: mysql, pg, sqlite3. Default: sqlite3.
DB_USE_SSL	Boolean value to determine whether database connections should use SSL. Default: true.
DEBUG_SCALING	Emit console.log on events related to scaling issues. Default: false.
DEFAULT_ORG	Set only with FIX_ORGLESS. Set to integer organization.id corresponding to the organization you want orgless users to be assigned to.
DEFAULT_SERVICE	Default SMS service. Options: twilio, bandwidth, nexmo, fakeservice.
DEFAULT_TZ	Default timezone region for determining timezone when a contact timezone is unavailable. If this is not set, then texting hours will fallback to 12pm Eastern to 9pm Eastern which is the most conservative value for texting hours in the continental US and probably the right default. Only set this if your entire audience is in a single timezone.
DEFAULT_RESPONSEWINDOW	Default number of hours after when a campaign's contacts that need a response (after they reply) -- this is changeable per-campaign, but this sets the default.
DEV_APP_PORT	Port for development Webpack server. Required for development.
DOWNTIME	When enabled it will redirect users to a /downtime page. If set to a string, it will show the string as a message to users on the downtime page. Use this to take the system down for maintenance. It will NOT stop graphql requests and will NOT stop users that are already in the app.
DOWNTIME_NO_DB	On AWS Lambda this blocks the site from loading the app at all and swaps out a system that redirects users to /downtime. This is useful for DB maintenance. For non-Lambda environments, just run the src/server/downtime app instead of src/server/index default app
DOWNTIME_NO_INITIAL	When enabled, texters will see a message telling them that sending of initial messages is paused, but they will still be able to reply to any incoming responses.
DOWNTIME_TEXTER	Setting DOWNTIME_TEXTER to a text message (without quotes, please) will give the message as a text to texters when they arrive on the site, but the admin pages will still be accessible. This could be useful if you want to stop new texters from landing on the site and texting, while you debug things.
DST_REFERENCE_TIMEZONE	Timezone to use to determine whether DST is in effect. If it's DST in this timezone, we assume it's DST everywhere. Default: "US/Eastern". (The default will work for any campaign in the US. For example, if the campaign is in Australia, use "Australia/Sydney" or some other timezone in Australia. Note that DST is opposite in the northern and souther hemispheres.)
DYNAMICASSIGNMENT_BATCHES	Enables texter strategies for campaigns. Enabled by default are "finished-replies-tz", "vetted-texters", and "finished-replies". Learn more at HOWTO-use-dynamicassignment-batches.md. NOTE: "vetted-takeconversations" is experimental and does not work on its own, needing other three default strategies enabled.
CONTACT_LOADERS	Optional contact loaders in extensions/contact-loaders ngpvan Required for VAN integration
EMAIL_FROM	Email from address. Required to send email from either Mailgun or a custom SMTP server.
EMAIL_HOST	Email server host. Required for custom SMTP server usage.
EMAIL_HOST_PASSWORD	Email server password. Required for custom SMTP server usage.
EMAIL_HOST_PORT	Email server port. Required for custom SMTP server usage.
EMAIL_HOST_USER	Email server user. Required for custom SMTP server usage.
EMAIL_HOST_SECURE	Email server security -- set to 1 if connection is made with smtps, otherwise set to 0 to connect without tls. For emails providers such as Postmark that use STARTTLS, set to 0 to connect with STARTTLS
EXPERIMENTAL_TWILIO_PER_CAMPAIGN_MESSAGING_SERVICE	Allow campaigns to have their own messaging service. This allows Spoke to send more than default Twilio limits of 400 numbers or 80,000 texts per day
EXPERIMENTAL_CAMPAIGN_PHONE_NUMBERS	Allows campaigns to select numbers from the inventory by area code. Currently only implemented for Twilio and fakeservice. When using Twilio, this creates a messaging service for each campaign on the fly. Requires PHONE_INVENTORY to be turned on.
EXPERIMENTAL_STICKY_SENDER	Creates permanent mappings between contact numbers and user numbers per organization when a recipient is texted. Once the mapping exists, that contact number will always be texted by that user number. This also means that messaging services will be skipped in favor of the direct user number.
PHONE_INVENTORY	Enable the Twilio phone number inventory feature while it's under active development
FIX_ORGLESS	Set to any truthy value only if you want to run the job that automatically assigns the default org (see DEFAULT_ORG) to new users who have no assigned org.
GRAPHQL_URL	Optional URL for pointing GraphQL API requests. Should end with /graphql, e.g. https://example.org/graphql. Default: "/graphql"
HIDE_BRANCHED_SCRIPTS	Convert UI to only used canned responses and hide all the interactions/questions. In the interactions section, specify an "Initial Outbound" message, then include canned responses. This also filters shortcut canned responses by the typed message text and shortens canned response titles rather than hiding their shortcut buttons when they are too long.
JOBS_SAME_PROCESS	Boolean value indicating whether jobs should be executed in the same process in which they are created (vs. processing asynchronously via worker processes). Default: false.
MAILGUN_DOMAIN	The domain you set up in Mailgun, e.g. email.bartletforamerica.com. Required for Mailgun usage.
MAILGUN_PUBLIC_KEY	Should be automatically set during Heroku auto-deploy. Do not modify. Required for Mailgun usage.
MAILGUN_SMTP_LOGIN	'Default SMTP Login' in Mailgun. Required for Mailgun usage.
MAILGUN_SMTP_PASSWORD	'Default Password' in Mailgun. Required for Mailgun usage.
MAILGUN_SMTP_PORT	Default: 587. Do not modify. Required for Mailgun usage.
MAILGUN_SMTP_SERVER	Default: smtp.mailgun.org. Do not modify. Required for Mailgun usage.
MAX_CONTACTS	If set each campaign can only have a maximum of the value (an integer). This is good for staging/QA/evaluation instances. Default: false (i.e. there is no maximum)
MAX_CONTACTS_PER_TEXTER	Maximum contacts that a texter can send to, per campaign. This is particularly useful for dynamic assignment. This must not be blank/empty and must be a number greater than 0.
MAX_MESSAGE_LENGTH	The maximum size for a message that a texter can send. When you send a SMS message over 160 characters the message will be split, so you might want to set this as 160 or less if you have a high SMS-only target demographic. Default: 99999
MAX_TEXTERS_PER_CAMPAIGN	Maximum texters that can join a campaign before joining with a dynamic assignment campaign link will block the texter from joining with a message that the campaign is full.
MOBILIZE_EVENT_SHIFTER_URL	For the texter sidebox, mobilize-event-shifter. This should be the base mobilize link for the organization, i.e. https://www.mobilize.us/{org_name}. Can be overridden in the campaign/organization admin settings.
MESSAGE_HANDLERS	Optional message handlers, listed in extensions/message-handlers. ngpvan required for VAN integration
MULTI_TENANT	Set to true if instance can host more than one organization.
NEXMO_API_KEY	Nexmo API key. Required if using Nexmo.
NEXMO_API_SECRET	Nexmo API secret. Required if using Nexmo.
NGP_VAN_API_KEY	API key. Generate an API key on the API Integrations section of VAN. Select Spoke or Spoke Basic API key type. Depending on a user's permission level the key may be generated automatically or need to be approved by their admin (users should contact their organization's VAN admin to request additional permissions as needed). Spoke Basic only supports writing data back into VAN, it does not have access to Export Jobs, while Spoke can export. Most users will only see Spoke but VAN clients who do not allow exports via API can request to have Spoke Basic added. Required for VAN integration.
NGP_VAN_API_BASE_URL	Base URL for VAN API. Optional. Default: https://api.securevan.com
NGP_VAN_APP_NAME	App name for your API key. Request an API key on the API Integrations section of VAN. Required for VAN integration.
NGP_VAN_CACHE_TTL	Time to live for VAN import metadata (i.e., saved lists) in a local cache in seconds. Optional. Default: 300.
NGP_VAN_EXPORT_JOB_TYPE_ID	Export job type ID. Optional. Default: 8.
NGP_VAN_MAXIMUM_LIST_SIZE	The maximum number of contacts to import. Spoke will ignore lists larger than this and you will not be able to select them in Spoke. Optional. Default: 75000.
NGP_VAN_WEBHOOK_BASE_URL	The base URL to pass to VAN for callbacks when contact exports from VAN are complete. This must be an https URL. It is probably the same URL you use to reach Spoke from a browser. Required for VAN integration.
NO_EXTERNAL_LINKS	Removes google fonts and auth0 login script -- good for development offline when you already have an auth0 session
NODE_ENV	Node environment type. Options: development, production.
NOT_IN_USA	A flag to affirmatively indicate the ability to use features that are discouraged or not legally usable in the United States. Consult with an attorney about the implications for doing so. Default: false (i.e. default assumes a USA legal context)
OPT_OUT_MESSAGE	Spoke instance-wide default for opt out message.
OPT_OUT_PER_STATE	Have different opt-out messages per state and org. Defaults to the organization's default opt-out message for non-specified states or when the Smarty Zip Code API is down. Requires the SMARTY_AUTH_ID and SMARTY_AUTH_TOKEN environment variables.
OPTOUTS_SHARE_ALL_ORGS	Can be set to true if opt outs should be respected per instance and across organizations
OUTPUT_DIR	Directory path for packaged files should be saved to. Required.
OWNER_CONFIGURABLE	If set to ALL then organization owners will be able to configure all available options from their Settings section (otherwise only superadmins will). You can also put a comma-separated list of environment variables to white-list specific settable variables here. This gives organization owners a lot of control of internal settings, so enable at your own risk.
PASSPORT_STRATEGY	A flag to set passport strategy to use for user authentication. The Auth0 strategy will be used if the value is an empty string or auth0. The local strategy will be used if the value is local.
PEOPLE_PAGE_CAMPAIGN_FILTER_SORT	The order in which to display the campaigns in the campaigns filter in People. Optional. If set, it must be one of DUE_DATE_ASC, DUE_DATE_DESC, ID_ASC, ID_DESC, TITLE. Default: ID_ASC.
PEOPLE_PAGE_ROW_SIZES	The list of options for the number of people to show on each page in People. If set this must be an array of integers. The numbers in the array do not need to be sorted. The first number in the array will be the default page size. Default: [100, 200, 500, 1000].
PGSSLMODE	Postgres SSL mode. Due to a Knex bug, this environment variable must be used in order to specify the SSL mode directly in the driver. This must be set to PGSSLMODE=require to work with Heroku databases above the free tier (see Heroku Postgres & SSL).
PHONE_NUMBER_COUNTRY	Country code for phone number formatting. Does not default to US. If left blank, phone numbers you upload must have a country code.
PORT	Port for Heroku servers.
REDIS_URL	This enables caching using the url option in redis library. This is an area of active development. More can be seen at server/models/cacheable_queries/README and the project board
REVERE_SQS_URL	SQS URL to process outgoing Revere SMS Messages.
REVERE_LIST_ID	Revere List to add user to.
REVERE_NEW_SUBSCRIBER_MOBILE_FLOW	Revere mobile flow to trigger upon recording action.
REVERE_MOBILE_API_KEY	Revere authentication api key to use to access Revere API.
REVERE_API_URL	Revere api endpoint to use for triggering a mobile flow.
ROLLBAR_CLIENT_TOKEN	Client token for Rollbar error tracking.
ROLLBAR_ACCESS_TOKEN	Access token for Rollbar error tracking.
ROLLBAR_ENDPOINT	Endpoint URL for Rollbar error tracking.
SEND_AUTO_OPT_OUT_RESPONSE	Send the organization's default opt-out message if a user is auto-opted out. Alternatively, set a shouldAutoRespond property in an item for the auto opt-out regex to true, for it to only apply on those regex matches.
SESSION_SECRET	Unique key used to encrypt sessions. Required.
SHOW_SERVER_ERROR	Best practice is to hide errors in production for security purposes which can reveal internal database/system state (even in an open-source project where the code paths are known)
SLACK_NOTIFY_URL	If set, then on post-install (often from deploying) a message will be posted to a slack channel's #spoke channel
SMARTY_AUTH_ID	Smarty API authentication ID. Required when the OPT_OUT_PER_STATE environment variable is enabled.
SMARTY_AUTH_TOKEN	Smarty API authentication token. Required when the OPT_OUT_PER_STATE environment variable is enabled.
SUPPRESS_SELF_INVITE	Boolean value to prevent self-invitations. Recommend setting before making sites available to public. Default: false.
SUPPRESS_DATABASE_AUTOCREATE	Suppress database auto-creation on first start. Mostly just used for test context
TERMS_REQUIRE	Require texters to accept the Terms page before they can start texting. Default: false
TEXTER_SIDEBOX_FIELDS	By default the texter UI only loads contact data used by tokens in the text messages. This variable takes a comma-separated list of contact data fields to make available for texter sideboxes irrespective of the tokens used in the messages.
TWILIO_ACCOUNT_SID	Global Twilio account SID. Required if using Twilio and TWILIO_MULTI_ORG is not set.
TWILIO_API_KEY	(Deprecated) Replaced by TWILIO_ACCOUNT_SID
TWILIO_AUTH_TOKEN	Global Twilio auth token. Required if using Twilio and TWILIO_MULTI_ORG is not set.
TWILIO_BASE_CALLBACK_URL	Base URL of the server handling twilio callbacks. Required if using EXPERIMENTAL_TWILIO_PER_CAMPAIGN_MESSAGING_SERVICE
TWILIO_MESSAGE_SERVICE_SID	Global Twilio message service ID. Required if using Twilio and TWILIO_MULTI_ORG is not set.
TWILIO_MULTI_ORG	Boolean value to indicate if organizations can override Twilio credentials in the organization settings. Default: false.
TWILIO_SQS_QUEUE_URL	AWS SQS URL to handle incoming messages when app isn't connected to twilio
TWILIO_VALIDATION	Validate message report links as well -- you should enable this. It's only non-default for backwards compatibility reasons.
TWILIO_VOICE_URL	Global Twilio voice url for phone numbers provisioned through Spoke. If not set, the default Twilio voicemail will be used.
WAREHOUSE_DB_X {TYPE,HOST,PORT,NAME,USER,PASSWORD,SCHEMA,USE_SSL}	Enables ability to load contacts directly from a SQL query from a separate data-warehouse db -- only is_superadmin-marked users will see the interface
WAREHOUSE_DB_LAMBDA_ITERATION	If the WAREHOUSEDB connection/feature is enabled, then on AWS Lambda, queries that take longer than 5min can expire. This will enable incrementing through queries on new lambda invocations to avoid timeouts.
WEBPACK_HOST	Host domain or IP for Webpack development server. Default: 127.0.0.1.
WEBPACK_PORT	Port for Webpack development server. Defaut: 3000.
ZAPIER_WEBHOOK_URL	URL where a payload of tag data will be POSTed to upon updating tags (not limited to Zapier; can be any URL)
ZAPIER_ACTION_URL	URL where a payload of action data will be POSTed to upon an action being taken (not limited to Zapier; can be any URL)
ZAPIER_CONFIG_OBJECT	Optional. A configuration object for zapier-action that specifies where to push payloads for specific responses/answers to questions. See HOWTO_INTEGRATE_WITH_ZAPIER for details on this object's schema and additional guidance on Zapier (and generic HTTP endpoint) integration.
ZAPIER_TIMEOUT_MS	Optional. The timeout, in milliseconds, for POSTs made by the zapier-action to configured URLs.