Installation and Configuration

quay.io/toucantoco/backend Container: Custom Configuration with Environment Variables

Warning

Toucan v112 introduces a new architecture, composed of multiple services. We’re working hard to provide you with a deployment plan for on-premise installations. While it’s not yet available, we provide Long Term Support for v111, including important fixes and security patches. Please continue using v111 (or latest-lts) for the time being!

Thanks to environment variables, you will be able to - for example:

  • change the default admin password and token (mandatory for production)
  • configure the Sendgrid service or your SMTP server (mandatory to be able to send mails to the users)
  • configure access to MongoDB or Redis services

All you need is to launch the quay.io/toucantoco/backend image with the following environment variables to set and apply configuration to the container.

You can use the –env or –env-file options of the docker run to set these environment variables.

If you use docker-compose, you can use the environment or env_file keys to set these environment variables.

Mandatory Configuration

Important

This part describes all the mandatory configurations you need to set for the Toucan Toco backend container in a production environment.

TOUCAN_USER_SUPERADMIN_PASSWORD

Sets the password of the super admin user (which is toucantoco).

We strongly recommend you to use a password of at least 20 characters.

TOUCAN_USER_SUPERADMIN_LOGIN

Overrides super admin username (by default: toucantoco).

TOUCAN_JWT_SECRET_KEY

Sets the value of the web token secret key.

We strongly recommend you to use a string of at least 20 characters.

TOUCAN_DB_ENCRYPTION_SECRET

Sets the secret used to encrypt an decrypt sensitive fields saved in the database.

We strongly recommend you to use a string of at least 20 characters.

MongoDB Configuration

Configure access to the MongoDB service.

TOUCAN_MONGODB_HOST=mongo.yourdomain.com           # hostname or IP of the external MongoDB service
TOUCAN_MONGODB_PORT=27017                          # port of the external MongoDB service
TOUCAN_MONGODB_USER=app                            # MongoDB user for the Toucan Toco app
TOUCAN_MONGODB_PASS=app_password                   # MongoDB password for the Toucan Toco app
TOUCAN_MONGODB_READONLY_USER=app_readonly          # (optional) MongoDB user with read-only access for the Toucan Toco app
TOUCAN_MONGODB_READONLY_PASS=app_readonly_password # (optional) MongoDB password for the read-only userfor the Toucan Toco app
TOUCAN_MONGODB_SSL=false                           # set it as true if your connection will be over SSL, possible values: true/false

Where the user app has been previously created on mongo.yourdomain.com:27017 with the following command:

db.createRole({role: "readWriteDropAnyDatabase", privileges: [],roles: [{role:"readWriteAnyDatabase",db:"admin"},{role:"dbAdminAnyDatabase",db:"admin"}]});
db.createUser({user: 'app', pwd: 'app_password', roles: ['readWriteDropAnyDatabase'] })

Optionally, for additional security, you can add a read-only user that will be used to perform the data queries done by the frontend.

db.createUser({user: 'app_readonly', pwd: 'app_readonly_password', roles: ['readAnyDatabase'] })

Warning

If you don’t add this read only user, the backend will use the “app” user as a fallback to perform data queries of the front end. This user has write access to the database. So with this configuration, it will be possible for end users so do write operations on the database by calling the backend API and tweaking the queries.

If you want to connect the container to a MongoDB managed service like Atlas, the only required environment variable is TOUCAN_MONGODB_HOST, like this:

TOUCAN_MONGODB_HOST='mongodb+srv://${USER_RW}:${PASSWORD_RW}@mongo.yourdomain.com/api-toucan?retryWrites=true&w=majority'
TOUCAN_MONGODB_READONLY_HOST='mongodb+srv://${USER_RO}:${PASSWORD_RO}@mongo.yourdomain.com/api-toucan?w=majority'

Here’s another connection string example for a MongoDB configuration with replica set:

TOUCAN_MONGODB_HOST='mongodb://${USER_RW}:${PASSWORD_RW}@mongo-01.yourdomain.com:27017,mongo-02.yourdomain.com:27017,mongo-03.yourdomain.com:27017/api-toucan?retryWrites=true&authSource=admin'
TOUCAN_MONGODB_READONLY_HOST='mongodb://${USER_RO}:${PASSWORD_RO}@mongo-01.yourdomain.com:27017,mongo-02.yourdomain.com:27017,mongo-03.yourdomain.com:27017/api-toucan?retryWrites=true&authSource=admin'

Please find all the available options for the Mongo Connection String on the official MongoDB online documentation

Redis Configuration

Configure access to the Redis service.

TOUCAN_REDIS_HOST=redis.yourdomain.com # hostname or IP of the external Redis service
TOUCAN_REDIS_PORT=6379                 # port of the external Redis service
TOUCAN_REDIS_SSL=false                 # set it as true if your connection will be over SSL, possible values: true/false
TOUCAN_REDIS_PASSWORD=your_password    # optional - if needed specify the password to access the Redis

Mail Configuration

There are 2 ways to send emails:

Sengrid

If you want to use the Sendgrid to send emails, you will need to set the following environment variables:

TOUCAN_SEND_MAIL_PROVIDER=sendgrid                  # explicitly sets the container to use Sendgrid
TOUCAN_SENGRID_API_KEY=YOUR_API_KEY                 # your Sendgrid API key
TOUCAN_SEND_MAIL_FROM_EMAIL=toucan@yourdomain.com   # emails will be sent with this address
TOUCAN_SEND_MAIL_FROM_NAME=ToucanToco               # emails will be sent with the label ToucanToco
TOUCAN_SEND_MAIL_WITH_INSTANCE_EMAIL_ADDRESS=enable # all emails will be sent with the above values, regardless of user input

SMTP Server

If you want to use your own SMTP service to send emails, you will need to set the following environment variables:

TOUCAN_SEND_MAIL_PROVIDER=smtp                      # explicitly sets the container to use an external SMTP server
TOUCAN_SMTP_HOST=smtp.yourdomain.com                # hostname or IP of the external SMTP service
TOUCAN_SMTP_PORT=25                                 # port of the external SMTP service
TOUCAN_SMTP_LOGIN=toucan@yourdomain.com             # SMTP user for the Toucan Toco app
TOUCAN_SMTP_PASSWORD=SMTP_PASSWORD                  # SMTP password for the Toucan Toco app
TOUCAN_SMTP_TLS=false                               # disables the TLS option, possible values: true/false
TOUCAN_SMTP_SMTPS=false                             # disables the SMTPS protocol, possible values: true/false
TOUCAN_SEND_MAIL_FROM_EMAIL=toucan@yourdomain.com   # emails will be sent with this address
TOUCAN_SEND_MAIL_FROM_NAME=ToucanToco               # emails will be sent with the label ToucanToco
TOUCAN_SEND_MAIL_WITH_INSTANCE_EMAIL_ADDRESS=enable # all emails will be sent with the above values, discarding user input

Warning

Just don’t set and remove TOUCAN_SMTP_LOGIN and TOUCAN_SMTP_PASSWORD if your SMTP server doesn’t need a login/password to send mail.

Workers Configuration

According to your server settings and usage, you can adapt the number of workers for the Toucan Toco API and process workers.

These default settings are good enough for most installations.

TOUCAN_GUNICORN_WORKERS

default value: 5

Set how many web workers will be launched.

TOUCAN_CELERY_MAX_WORKERS

default value: 2

Set maximum number of parallel heavy background tasks (e.g. data preprocessing).

TOUCAN_CELERY_QUICK_MAX_WORKERS

default value: 10

Set maximum number of parallel light background tasks (e.g. committing a config file in a git repository).

Misc Configuration

TOUCAN_FRONTEND_URLS

default value: [] (no frontend url)

Set the list of frontend URLs connected to the backend as a JSON string, containing an array of URLS.

Please note:

  • The Toucan Toco backend URL minus an api- prefix will be considered as the fallback URL.
  • If there is multiple frontend URLs, the backend will use the fallback URL above if it is in the list, otherwise the first one of the list.
  • If no frontend URL is specified, the backend will use the fallback URL.

E.g:

TOUCAN_FRONTEND_URLS="['https://yourcompany.toucantoco.com','https://cockpit.yourcompany.com']"

TOUCAN_PUPPETEER_URL

default value: http://screenshot:3000/

If you enable the screenshot feature by deploying the Docker image quay.io/toucantoco/screenshot, you will need to specify the URL to reach the container.

E.g:

TOUCAN_PUPPETEER_URL='http://screenshot.yourdomain.com/' # The URL of the Toucan Toco screenshot container

TOUCAN_TOKEN_VALIDITY

default value: 30 days

Set the validity period of the user’s access tokens. Quantifiers can be any of: “hours”, “days”, “weeks”.

TOUCAN_CROSS_ORIGIN_WHITELIST

default value: ['*'] (no restriction)

Set the list of allowed origins for CORS (Cross Origin Resource Sharing). Please note that, by default, the Toucan Toco backend will allow requests from all origins.

E.g:

TOUCAN_CROSS_ORIGIN_WHITELIST="['https://yourcompany.toucantoco.com','https://cockpit.yourcompany.com']"

TOUCAN_PDF_REPORT

default value: disable (feature not accessible)

To activate the pdf report (paid feature) on your instance:

TOUCAN_PDF_REPORT=enable

TOUCAN_DATAWALL

default value: disable (feature not accessible)

To activate the datawall (paid feature) on your instance:

TOUCAN_DATAWALL=enable

TOUCAN_ALERTS

default value: disable (feature not accessible)

To activate the alerts (paid feature) on your instance:

TOUCAN_ALERTS=enable

TOUCAN_WHITE_LABEL

default value: disable (feature not accessible)

To activate the white label (paid feature) on your instance:

TOUCAN_WHITE_LABEL=enable

TOUCAN_EMBED

default value: disable (feature not accessible)

To enable the creation of embed dashboards on your instance:

TOUCAN_EMBED=enable

TOUCAN_GUEST_CREATION

default value: disable (feature not accessible)

To activate the guest creation (paid feature) on your instance:

TOUCAN_GUEST_CREATION=enable

TOUCAN_SHORT_PASSWORD_TOKEN_VALIDITY

default value: 24 hours

Set the validity period of a user’s reset password link, sent by email. Quantifiers can be any of: “hours”, “days”, “weeks”.

TOUCAN_LONG_PASSWORD_TOKEN_VALIDITY

default value: 4 weeks

Set the validity period of a user’s account activation link, sent by email). Quantifiers can be any of: “hours”, “days”, “weeks”.

TOUCAN_MAX_ROWS_FOR_LIVE_DATA

default value: 10000

Allows to control how many rows will be fetched at most by live data.

TOUCAN_MAX_ROWS_FOR_PREPARED_DATASETS_PREVIEW (deprecated)

default value: 10000

Allows to control how many rows will be used as input to preview the result of prepared datasets.

TOUCAN_DEFAULT_SOURCE_ROWS_SUBSET_FOR_PREPARED_DATASET_PREVIEW

default value: 10000

Allows to control how many rows will be used by default as input to preview the result of prepared datasets.

TOUCAN_EXECSUM_PAGINATED_RENDERING_NUMBER_OF_PAGES_PER_FILE

default value: 4

Sets the number of pages of the PDF report (aka. execsum) that gets rendered at the same time in the screenshot container.

TOUCAN_EXECSUM_PAGINATED_RENDERING_GENERATED_FILES_LIMIT

default value: 10

Sets the maximum number of times we iterate on the number of pages above for a single pdf report. So if this paramater value is 10 and the TOUCAN_EXECSUM_PAGINATED_RENDERING_NUMBER_OF_PAGES_PER_FILE is 4; then the maximum number of pages for a rendering of the PDF report is 10x4 = 40.

TOUCAN_QUERY_CACHE

default value: disable

Controls the activation of the cache of queries (stored in redis database #1).

TOUCAN_QUERY_CACHE_MIN_TIME

default value: 150ms

Duration of the query past which this query will be stored in cache (only if TOUCAN_QUERY_CACHE is enabled).

TOUCAN_THROTTLE_RATE_STATUS

default value: disable

Controls the activation of the throttle rate (the number of requests allowed in a period of time).

TOUCAN_THROTTLE_RATE_LIMIT

default value: 5/minute

Amount of requests (default is 5) for a period of time (default is minute, it can be hour, day or month…) allowed on some endpoints like login, forgot-password and access-request (only if TOUCAN_THROTTLE_RATE_STATUS is enable).

TOUCAN_IS_BEHIND_PROXY

default value: enable

If your instance is running behind a proxy, this value should be True, so that our backend can receive the user IP for incoming requests (inside the header ‘X-Forwarded-For’). This is used by the application to throttle API traffic, cf. TOUCAN_THROTTLE_RATE_STATUS.

TOUCAN_CUSTOM_USER_ID

default value: 1000

Sets the UID of the toucan system user of the backend container (this user manages the /app folder).

TOUCAN_CUSTOM_GROUP_ID

default value: 1000

Sets the GID of the toucan system user of the backend container.

Secrets Configuration

You can set secrets in the TOUCAN_SECRETS env var so that they do not appear in the ETL config. This var is a JSON where you need to add your secrets under the extra key.

TOUCAN_SECRETS='{"extra": {"my_db": {"user": "my_user", "password": "mypwd"}}}'

Secrets can then be used in the connector or data source configuration with the following syntax {{ secrets.extra.my_db.user }} and {{ secrets.extra.my_db.password }}

MS Teams bot configuration

TOUCAN_MS_TEAMS_APP_ID=YOUR_BOT_ID                  # Your MS Teams bot ID
TOUCAN_MS_TEAMS_APP_PASSWORD=YOUR_BOT_PASSWORD                 # your MS TeamsBot password
TOUCAN_MS_TEAMS_SERVICE_URL=YOUR_SERVICE_URL   # Your MS Teams service URL
TOUCAN_MS_TEAMS_REGISTER_TEAM_PASSWORD=YOUR_TEAM_ID               # The ID of your team

quay.io/toucantoco/frontend Container: Custom Configuration with Environment Variables

Warning

Toucan v112 introduces a new architecture, composed of multiple services. We’re working hard to provide you with a deployment plan for on-premise installations. While it’s not yet available, we provide Long Term Support for v111, including important fixes and security patches. Please continue using v111 (or latest-lts) for the time being!

Thanks to environment variables, you will be able to - for example:

  • specify the URL to reach the quay.io/toucantoco/backend container (mandatory)
  • define a MixPanel Analytics ID to track the usage of the application

All you need is to launch the quay.io/toucantoco/frontend image with the following environment variables to set and apply configuration to the container.

You can use the –env or –env-file options of the docker run to set these environment variables.

If you use docker-compose, you can use the environment or env_file keys to set these environment variables.

Mandatory Configuration

Important

This part describes all the mandatory configurations you need to set for the Toucan Toco frontend container in a production environment.

API_BASEROUTE

The URL of your Toucan Toco backend instance. It’s the only mandatory setting you need to specify for the quay.io/toucantoco/frontend container

E.g:

API_BASEROUTE=http://api-toucan.domain.com

Misc Configuration

MIXPANEL_ANALYTICS_ID

Use this environment variable to specify your Mixpanel analytics.

You can retrieve this token by following this FAQ tuto.

USERNAME and PASSWORD

Sets bundled credentials for the app.

You should use these settings only when you need to make a public application.

The credentials should have been created before with the user management interface.

Of course, be sure to always embed viewers’ credentials and not those of admins or contributors!

E.g:

USERNAME=public-user@yourdomain.com
PASSWORD=mypublicPASSWORD

AUGMENT FLAG

The AUGMENT_PY_USE flag allows to hide the augment.py field when it was not modified.

The default value is disabled, change it to enable to allow modification of the augment.py file.