Environment Variables

The Grouparoo application is configured primarily by setting environment variables. In the development and test environments, this can be done by modifying a .env file in the root of your application directory. For production environments, we recommend that you set these variables in other ways - usually directly in your OS, Docker Orchestrator or PaaS host.

Required Environment Variables

General Settings

• PORT is the port the application will run on. When developing, set this to something static like 3000. Many PaaS providers (like Heroku) will provide you a port dynamically at runtime via this environment variable.
• WEB_URL is the URL to access the Grouparoo web application, ie "http://localhost:3000" when developing. This is used to set access headers among other things.
• SERVER_TOKEN is a random string that will be used to identify Grouparoo servers to each-other in the same cluster. It will not be used to authenticate users, but rather authorize servers to make requests against each other. SERVER_TOKEN is not a replacement for setting unique, per-Application Database credentials and isolated runtime environments.

The following options configure if Grouparoo should enable the web server and workers for this instance. Learn more about WORKERS here.

• WEB_SERVER=true
• WORKERS=5

Logging

The Grouparoo logs can be modified with the following environment variables:

• GROUPAROO_LOG_LEVEL=info
• GROUPAROO_LOGS_STDOUT_DISABLE_COLOR=true
• GROUPAROO_LOGS_STDOUT_DISABLE_TIMESTAMP=true
• GROUPAROO_LOGS_PATH="/path/to/logs"

Telemetry

You can disable telemetry collection by setting GROUPAROO_TELEMETRY_ENABLED=false. Learn more about Grouparoo's telemetry collection here.

Redis

Grouparoo uses Redis as both a cache and as a background job queue via node-resque. You can customize how this are used via your environment variables.

• REDIS_URL="redis://localhost:6379/0"

The full set of options you can provide to REDIS_URL is: REDIS_URL="redis://{user}:{password}@{host}:{port}/{database}". Note that you cannot use an @ or : in your username or password when using REDIS_URL. Alternatively to REDIS_URL, you can set the following environment variables directly: REDIS_HOST, REDIS_PORT, REDIS_DB, and REDIS_USER, REDIS_PASS which do allow all special characters.

To use an in-memory redis, set REDIS_URL="redis://mock".

Database

Grouparoo stores all of your data in a database. You can use a Postgres or SQLITE database. You can customize your database connection string via environment variables.

• DATABASE_URL="postgresql://localhost:5432/grouparoo_development"

The full set of options you can provide to DATABASE_URL is: DATABASE_URL="postgresql://{user}:{password}@{host}:{port}/{database}?{ssl=true}". Note that you cannot use an @ or : in your username or password when using DATABASE_URL. Alternatively to DATABASE_URL, you can set the following environment variables directly: DB_DIALECT=postgres, DB_HOST, DB_PORT, DB_DATABASE, and DB_USER, DB_PASS which do allow all special characters.

You can also modify the SSL connection options to your postgres database with these environment variables:

• DATABASE_SSL=true
• DATABASE_SSL_SELF_SIGNED=true

To use SQLite, set DATABASE_URL="sqlite://grouparoo_development.sqlite" which will be stored in your application directory by default, or you can provide an absolute path, ie: DATABASE_URL="sqlite:///path/to/db.sqlite".

Batch Size Environment Variables

Once your Grouparoo server is deployed, you may want to tune some of the batch sizes Grouparoo uses. These batch sizes effect how many Records and Properties Grouparoo Imports and Exports at once. Increasing these values may speed up your Imports and Exports, but require more resources to run (e.g. more memory for the Grouparoo process and a larger postgres database). Also, increasing the batch sizes for Exports may lead to hitting rate limits, depending on the provider. Be careful when changing these values!

• GROUPAROO_IMPORTS_BATCH_SIZE - How many records to import from a Source at once? (default 1000)
• GROUPAROO_RECORDS_BATCH_SIZE - How many records to process from a Source at once? (default 500)
• GROUPAROO_EXPORTS_BATCH_SIZE - How many records to export to a Destination at once? (default 100)
• GROUPAROO_INTERNAL_BATCH_SIZE - How many rows does the Grouparoo internal database support updating at once? (default 5000)

.env example

#############
## GENERAL ##
#############

PORT=3000
WEB_URL=http://localhost:3000

WEB_SERVER=true
WORKERS=1
SERVER_TOKEN=my-serer-token

# By default, the config directory should be located in a folder named "config" within the root of your project.  You can change that with `GROUPAROO_CONFIG_DIR`
# GROUPAROO_CONFIG_DIR=/path/to/config

#############
## LOGGING ##
#############

GROUPAROO_LOG_LEVEL=info
# GROUPAROO_LOGS_STDOUT_DISABLE_COLOR=true
# GROUPAROO_LOGS_STDOUT_DISABLE_TIMESTAMP=true
# GROUPAROO_LOGS_PATH="/path/to/logs"

###########
## REDIS ##
###########

# To use an in-memory redis mock (no persistence)
REDIS_URL="redis://mock"

# To use a Redis Server
# REDIS_URL="redis://localhost:6379/0"

##############
## DATABASE ##
##############

# To use sqlite
DATABASE_URL="sqlite://grouparoo_development.sqlite"

# To use Postgres
# DATABASE_URL="postgresql://localhost:5432/grouparoo_development"

# With custom SSL options:
# DATABASE_SSL=true
# DATABASE_SSL_SELF_SIGNED=true

A note on SERVER_TOKEN: This should be a random string that will be used to identify Grouparoo servers to each-other in the same cluster. It will not be used to authenticate users, but rather authorize servers to make requests against each other. SERVER_TOKEN is not a replacement for setting unique, per-Application Database credentials and isolated runtime environments.

Exhaustive List

An exhaustive list of all the environment variables used to configure Grouparoo is stored in the repository.