Installation and Configuration

toucantoco/backend Container: Custom Configuration with Environment Variables

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

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=adminpassword        # MongoDB password for 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.createUser({user: 'app', pwd: 'adminpassword', roles: ['readWriteAnyDatabase'] })

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://your_user:your_password@mongo.yourdomain.com/test?retryWrites=true&w=majority'

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

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_PUPPETEER_URL

default value: http://puppeteer/

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

E.g:

TOUCAN_PUPPETEER_URL='http://puppeteer.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']"

toucantoco/frontend Container: Custom Configuration with Environment Variables

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

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

All you need is to launch the 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 toucantoco/frontend container

E.g:

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

Misc Configuration

GOOGLE_ANALYTICS_ID

Use this environment variable to specify your Google Analytics ID.

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
PASSWORD=mypublicPASSWORD