Environment

Last Updated: 2021-01-12

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.

Environment Variables and API Keys

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 server and workers for this instance. When deploying, you will likely want some "api" servers and some "worker" servers, which can all be configured with these environment variables.

  • WEB_SERVER=true
  • WORKERS=1

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".

.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.