Frequently Asked Questions

Answers for industrious sysadmins

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

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

curl https://${backend_domain}/

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

These information are 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 currently produce two types of releases:

  • weekly releases: they contain the last improvements and fixes in the product, and are out every thursday
  • monthly releases: they accumulate the changes of 4 development weeks, and are battle-tested against complex apps during their last week of production

We indicate which version corresponds to which release type in our releases notes.

In case of critical fixes or security updates that can’t wait a month or even a week to be published, we patch both the latest weekly and monthly release. You will also receive a security note by mail about it.

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

A complete post is available on our blog for more details: Releases that adapt to your desired speed.

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

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 front-end and also the back-end 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) to use the Toucan Toco app. Please check with your IT team for more details.

This question has been asked in the following discourse thread: My client can’t login to a small app using her/his id/password.

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:

    image: toucantoco/backend-light:latest-monthly
      - mongo
      - redis
      - 80
    image: toucantoco/frontend:latest-monthly
      - 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 devoluted 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 to configure 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/* {
  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 to install some extra packages/dependencies, which 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 toucantoco/backend 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 toucantoco/backend:latest-monthly  RUN toucan-ctl install_connectors azure_mssql oracle

eval_rst  .. warning::     While overriding the image is very flexible to add 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 the 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 toucantoco/backend container.

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