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_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']"