Frequently Asked Questions

Answers for industrious sysadmins

How to know the current version of my Toucan Toco app?

It’s pretty simple to find out your frontend and backend version with a basic curl command:

curl https://${backend_domain}/

curl https://${frontend_domain}/tucana-version.txt

This information is also accessible in a browser, on the bottom-right corner of the login page:

instance version tooltip

What’s your release frequency? When do I need to upgrade the app?

We release a new version of our frontend and backend every month.

The release is available the last week of each month and contains the last improvements and fixes of the product.

All the details (features, fixes, breaking changes) about a given release is available on our release notes page.

In case of critical fixes or security updates that can’t wait a month to be published, we directly patch the latest release and create a new version. You will also receive a security note by email about it.

The latest release is always available behind the latest-monthly tag.

It means a bit more maintenance work for us but it ensures the Toucan Toco platform stays perfectly secure anytime.

We strongly recommend to update your stack at least every quarter.

I can’t login to the Toucan Toco app, why?

In some cases, you can reach the Toucan Toco app with your browser, you know your IDs are good but you are not able to login.

First you need to be sure that your browser is able to reach the frontend and also the backend servers.

Moreover please be sure there is no proxy between the servers and your browser, which could remove some HTTP headers.

Some of them are mandatory (like the authorization one) for using the Toucan Toco app. Please check with your IT team for more details.

Can I host frontend and backend servers on the same machine?

Yes you can, you just need to configure your machine’s webserver to serve the two domains associated respectively with the frontend and backend.

How can I serve my Toucan Toco app over SSL/TLS ?

As explained in the requirements section, implementing the SSL/TLS termination is up to you, but here is an example of how you could add this feature to a docker-compose stack using Caddy:

      - mongo
      - redis
      - 80
      - 80
    image: caddy/caddy:alpine
      - ./Caddyfile:/etc/caddy/Caddyfile:ro  # see Caddyfile content below
      - ./
      - ./
      FRONTEND_SERVICE: frontend
      BACKEND_SERVICE: backend
      SSL_CRT: /certs/
      SSL_KEY: /certs/
      - "80:7000"
      - "443:8000"
      - backend
      - frontend

(note that in this docker-compose file, frontend and backend services ports are not exposed outside of the Docker network anymore, since this is now delegated to caddy)


# Port 8000 is for incoming https trafic
# Port 7000 is for incoming http trafic -> redirect it to https
:7000 {
  redir https://{host}{uri}

# Frontend TLS termination proxy
http://{$FRONTEND_DNS}:8000, https://{$FRONTEND_DNS}:8000 {
  tls {$SSL_CRT} {$SSL_KEY}
  reverse_proxy {$FRONTEND_SERVICE}:80

# Backend TLS termination proxy
http://{$BACKEND_DNS}:8000, https://{$BACKEND_DNS}:8000 {
  tls {$SSL_CRT} {$SSL_KEY}
  reverse_proxy {$BACKEND_SERVICE}:80

Can I serve both Toucan Toco’s frontend and backend under the same domain ?

Frontend and backend services are decoupled but nothing prevents you from configuring your proxy configuration to make them accessible under the same domain name, for example by serving the backend under some http path prefix, e.g /_api/.

From the example above (using Caddy), one can achieve this by updating the API_BASEROUTE environment variable to, and by updating the Caddyfile:

# Backend TLS termination proxy (using the same DNS as the frontend)
http://{$FRONTEND_DNS}:8000/_api/*, https://{$FRONTEND_DNS}:8000/_api/* {
  uri strip_prefix _api
  tls {$SSL_CRT} {$SSL_KEY}
  reverse_proxy {$BACKEND_SERVICE}:80

My connector does not work, how can I add its dependencies to my on-premises stack?

The Toucan Toco Docker image is as light as possible. This is why we avoid installing some extra packages/dependencies that are only needed in specific cases or contexts.

Some Toucan Toco connectors need these extra packages.

You can find the list of these connectors on the Toucan Toco connectors public repository.

If you need to use one of these connectors, you will have to declare it explicitly with the TOUCAN_EXTRA_CONNECTORS environment variable:


TOUCAN_EXTRA_CONNECTORS='["azure_mssql", "oracle"]'

This will trigger the download and the installation of theses dependencies when the container starts.

Override the image with these connectors built-in

If downloading and installing these dependencies at start time is not an option, you can still create your own image from the one we provide with these dependencies built in.

Example Dockerfile:

``` FROM

RUN toucan-ctl install_connectors azure_mssql oracle ```

While overriding the image is very flexible for adding arbitrary dependencies, it is also an easy way to break the Toucan stack and get errors that we won’t be able to reproduce. Also, please note that this will require that you manage (build, store, update) the resulting image by yourself.

I have an old application and I’m not able to update it on my new stack, what’s going on?

Since version v28.5, the augment should now use the pipeline syntax.

If you need to keep using the old syntax, you will have to declare the environment variable TOUCAN_OLD_AUGMENT_WHITELIST when you launch your container.

The TOUCAN_OLD_AUGMENT_WHITELIST is a list of small apps, which will keep using the old augment system.


TOUCAN_OLD_AUGMENT_WHITELIST='["small_app_1", "small_app_2"]'

I do not use Nginx in production, I won’t be using your docker image to serve Toucan Toco frontend, what can I do ?

The frontend static files package is available as a tarfile on (just ask your credential to our support team).

Thus you can deploy the static files on a S3 bucket, on a docroot of your favorite web server or you can even create your own docker image with the static files.

Deploy the content of the www folder on your site root path. You will need to edit the file www/scripts/tc-params.js with the relevant parameters.

The image is just an example to start quickly.

How do I install analytics applications on-premises ?

The tool we chose to monitor our analytics and base our analytics app on is mixpanel. To be able to have the analytics on-premises, your will have to create a new mixpanel account and a dedicated project on mixpanel with its own token.

Once you have created your account you will need :

  • API Secret: copy this value in the Analytics app etl_config.cson file (it should replace the string '{{ analytics.mixpanel_api_secret }}' in this file).
  • Token : copy this value in the frontend www/scripts/tc-params.js file, under the key named MIXPANEL_ANALYTICS_ID.

Can I export embeds on-premise ?

Yes, check our dedicated doc right here

I have timeout issues with the screenshot features

Typical message you can have:

Error while rendering the screenshot: TimeoutError: waiting for selector ".tc-slide__content, .tc-story" failed: timeout 30000ms exceeded

It’s important to understand, the screenshot features work like your own usual browser: The screenshot container needs to be able to reach the backend and the frontend through their DNS.

Here’s a procedure to help you debug if your screenshot container is ready:

# Go inside the screenshot container as root
$ docker exec -u root -it <screenshot-container-name> bash

# Install usual debug tools
root@<screenshot-container-id>:app/# apt-get update
root@<screenshot-container-id>:app/# apt-get install telnet curl ca-certificates bind9-host

# Confirm the DNS resolution
root@<screenshot-container-id>:app/# host $FRONTEND_DNS
root@<screenshot-container-id>:app/# host $BACKEND_DNS
# should return something like: $FRONTEND_DNS has address WW.XX.YY.ZZ

# Confirm you can "connect" to the frontend and the backend on HTTPS port
root@<screenshot-container-id>:app/# telnet $FRONTEND_DNS 443
root@<screenshot-container-id>:app/# telnet $BACKEND_DNS 443
# should return something like: Connected to $FRONTEND_DNS.
# you will need to force quit with Ctrl+C

# Confirm you can access to the home page
root@<screenshot-container-id>:app/# curl -sL -w "%{http_code}" -k "https://$FRONTEND_DNS" -o /dev/null
root@<screenshot-container-id>:app/# curl -sL -w "%{http_code}" -k "https://$BACKEND_DNS" -o /dev/null
# should return: 200

Don’t hesitate to contact us with the result of this debug process.

What about the redundancy of the stack?

For some technical reasons, it’s currently not possible to provide redundancy on the backend part: you can’t run several backend containers at the same time.

There is no problem for the frontend container.