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 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 email about it.

It means a bit more maintenance work for us but it ensures the 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 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.

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:

[...]
  backend:
    image: toucantoco/backend-light:latest-monthly
    depends_on:
      - mongo
      - redis
    expose:
      - 80
  frontend:
    image: toucantoco/frontend:latest-monthly
    environment:
      API_BASEROUTE: https://api-toucan.mydomain.com
    expose:
      - 80
  caddy:
    image: caddy/caddy:alpine
    volumes:
      - ./Caddyfile:/etc/caddy/Caddyfile:ro  # see Caddyfile content below
      - ./mydomain.com.crt:/certs/mydomain.com.crt:ro
      - ./mydomain.com.key:/certs/mydomain.com.key:ro
    environment:
      FRONTEND_DNS: toucan.domain.com
      FRONTEND_SERVICE: frontend
      BACKEND_DNS: api-toucan.domain.com
      BACKEND_SERVICE: backend
      SSL_CRT: /certs/mydomain.com.crt
      SSL_KEY: /certs/mydomain.com.key
    ports:
      - "80:7000"
      - "443:8000"
    depends_on:
      - 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)

Caddyfile:

# 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 https://toucan.mydomain.com/_api/, 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 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:

E.g:

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 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 toucantoco/backend container.

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

E.g:

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 (get-package.toucantoco.com)[https://get-package.toucantoco.com/] (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 toucantoco/frontend 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.

How do I enable embed export on my applications ?

To do so, you’ll have to set specific HTTP headers in you preferred web server (as Nginx) in order that your embeds work.

Please note you can not change the header at the level of the Toucan Toco containers, you will need to configure it at the SSL reverse proxy level.