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¶
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:
- via Sendgrid
- via a SMTP server
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¶
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.