Installation process for On-Premise: Back-End with Docker

Requirements

The only requirement in this context is docker.

Important

Please note that only the Nginx HTTP port (80) is exposed and is not secured.

For a production use, you will need to use an HTTPS reverse proxy in front of the Toucan Toco container.

Quick Installation

Download the toucantoco/backend docker image

The Toucan Toco back-end docker image is a basic tar archive file which is downloadable by contacting the Toucan Toco team or via https://get-package.toucantoco.com/laputa/ if you have an account.

The latest version of the container is available via docker_backend-latest.tar.

Note

There is a sha1 file for each generated archive to let you check the integrity of the Toucan Toco container. Just add .sha1 to the package URL to download the associated sha1 fingerprint. The sha1 fingerprint of the latest version of the package is downloadable via docker_backend-latest.tar.sha1.

Import the toucantoco/backend docker image

To import the Docker image (on your node or your own registry), you only need to load it as following:

docker load < /path/to/docker_backend-latest.tar

You should be able to list the new image:

$ docker image list
REPOSITORY                 TAG                 IMAGE ID            CREATED             SIZE
toucantoco/backend         v39.2.4             02d4415908d8        2 days ago          3.2GB

It’s not mandatory, but we strongly recommand to recreate the latest tag to follow the best practices.

docker tag 02d4415908d8 toucantoco/backend:latest

Launch the toucantoco/backend docker image

Finally just launch

docker run -d -p 80:80 toucantoco/backend:latest

And test it by pinging the app’s status page:

curl -A "Plop 4rQD3KzCxWzTYaRyp0NSEfd6" http://127.0.0.1/status

That’s all!

The default admin credentials are:

  • user: toucantoco
  • password: hakunamatata

Important

Of course this approach is only for internal tests and PoCs.

You will see in the next section how to set your own admin password, persist data, check logs…

Please don’t run in a production mode with this configuration.

Advanced configuration for the toucantoco/backend docker image

Where are the app’s main logs files?

The main logs files are located in /data/tmp/toucan-log in the container.

How to persist the MongoDB data? and the Toucan Toco data?

It’s pretty simple to persist the MongoDB and the Toucan Toco data, you just need to mount volumes on the right places.

Here an example where MongoDB data are persisted in /app/toucan/mongo_db of the docker node and where the Toucan Toco data are persisted in /app/toucan/data_storage:

docker run      -d \
                -v /app/toucan/mongo_db:/var/lib/mongodb \
                -v /app/toucan/data_storage:/data/api-toucan/shared/storage \
                -p 80:80 \
                --name tctc-backend \
                toucantoco/backend:latest

More configurations?

Important

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

Thanks to a dedicated configuration file, you will be able to:

  • 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 an external MongoDB or Redis services

All you need is to create a file and mount it as /data/config.yml in the container.

The next parts of the doc is describe all the available settings.

Mandatory configuration

user_superadmin_password

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

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

jwt_secret_key

Set the value of the web token secret key.

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

MongoDB configuration

If you want to plug the Toucan Toco container to an external MongoDB service, you will need to add to the config.yml the following block:

mongo_supervisor: false                # explicit the container to use an external MongoDB
mongodb_host:     mongo.yourdomain.com # hostname or IP of the external MongoDB service
mongodb_port:     27017                # port of the external MongoDB service
mongodb_user:     app                  # MongoDB user for the Toucan Toco app
mongodb_pass:     adminpassword        # MongoDB password for the Toucan Toco app

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

db.createUser({user: 'app', pwd: 'adminpassword', roles: ['readWriteAnyDatabase'] })

Redis configuration

If you want to plug the Toucan Toco container to an external Redis service, you will need to add to the config.yml the following block:

redis_supervisor: false                # explicit the container to use an external Redis
redis_host:       redis.yourdomain.com # hostname or IP of the external Redis service
redis_port:       6379                 # port of the external Redis service

Gunicorn

gunicorn_workers

default value: 5

Set how many web workers will be launched.

Celery (background task manager)

celery_max_workers

default value: 1

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

celery_quick_max_workers

default value: 10

Set maximum number of parallel light tasks.

Mail configuration

There are 2 ways to send mails:

Sengrid

If you want to use the Sendgrid to send mails, you will need to add to the config.yml the following block:

send_mail_provider:   sendgrid              # explicit the container to use Sendgrid
sengrid_api_key:      YOUR_API_KEY          # your Sendgrid API key
send_mail_from_email: toucan@yourdomain.com # mails will be sent with this address
send_mail_from_name:  ToucanToco            # mails will be sent with the label ToucanToco

SMTP Server

If you want to use your own SMTP service to send mails, you will need to add to the config.yml the following block:

send_mail_provider: smtp                    # explicit the container to use an external SMTP server
smtp_host:          smtp.yourdomain.com     # hostname or IP of the external SMTP service
smtp_port:          25                      # port of the external SMTP service
smtp_login:         toucan@yourdomain.com   # SMTP user for the Toucan Toco app
smtp_password:      SMTP_PASSWORD           # SMTP password for the Toucan Toco app
smtp_tls:           false                   # disable the TLS option
smtp_smtps:         false                   # disable the SMTPS protocol
send_mail_from_email: toucan@yourdomain.com # mails will be sent with this address
send_mail_from_name:  ToucanToco            # mails will be sent with the label ToucanToco

config.yml example

In this example, the Toucan Toco container:

  • is plugged to an external MongoDB service
  • is plugged to an external Redis service
  • uses a dedicated SMTP service
Complet stack with access to external services

Complet stack with access to external services

user_superadmin_password: xPp9HOHeKwl3tbJvEOXatW1sUsMQFIqY
jwt_secret_key:           ql8xwyCayX0l5ckPD9ccaFZ3VzCbm7Ea

mongo_supervisor: false
mongodb_host:     mongo.yourdomain.com
mongodb_port:     27017
mongodb_user:     app
mongodb_pass:     adminpassword

redis_supervisor: false
redis_host:       redis.yourdomain.com
redis_port:       6379

send_mail_provider: smtp
smtp_host:          smtp.yourdomain.com
smtp_port:          25
smtp_login:         toucan@yourdomain.com
smtp_password:      SMTP_PASSWORD
smtp_tls:           false
smtp_smtps:         false
send_mail_from_email: toucan@yourdomain.com
send_mail_from_name:  ToucanToco

Finally the container could be launched as following

docker run      -d \
                -v /opt/toucantoco/config.yml:/data/config.yml \
                -p 80:80 \
                --name tctc-backend \
                toucantoco/backend:latest

Volumes Summary

Here’s a little summary of every interesting container’s files/directories.

Container’s Files/Direc tories Details
/data/confi g.yml file which described every settings you need for the advanced configurati ons
/var/lib/mo ngodb directory where all the MongoDB data are stored, only relevant if you use the container MongoDB service
/data/api-t oucan/share d/storage directory where all assets and data sources are stored
/data/tmp/t oucan-log directory where all logs are stored - be sure every users us able to write here