Installation process for On-Premise: Back-End by Package

Installation workflow

Ansible Workflow

Ansible Workflow

If you don’t want to install the Toucan Toco stack over SSH, you can do it locally.

Requirements

Hardware requirements

The installation machine - where you will install and setup the Toucan Toco stack - should first meet the On-Premise requirements.

Technical requirements

The installation process is fully managed with Ansible. So to complete the process, you need a machine:

  • able to contact by SSH the targeted server where the Toucan Toco app will be installed. The SSH user should be able to launch sudo commands.
  • with Ansible v2.7.x (the latest version of the v2.7.x is currently v2.7.8)

Moreover, you will need SSL certificates and associated keys to configure the reverse proxy.

Note

If you don’t have Ansible on your machine, it’s very easy to install it locally, with just python3 virtualenv tool:

# Creates a virtualenv in <INSTALL_DIR> dedicated to our ansible installation
python3 -m venv <INSTALL_DIR>/ansible-2.7.8

# Activates this virtualenv
source <INSTALL_DIR>/ansible-2.7.8/bin/activate

# Install ansible 2.7.8
pip install ansible==2.7.8

# Install useful python modules
pip install requests httplib2

# Check ansible's version
ansible --version
# Should echo: ansible 2.7.8

Download package

The Toucan Toco back-end package is a basic tar.gz 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 package is available via onpremise_backend-latest.tar.gz.

Copy and extract the Toucan Toco installation package, on the machine - described earlier - from where you will launch the Ansible playbooks.

Note

There is a sha1 file for each generated archive to let you check the integrity of the Toucan Toco package. 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 onpremise_backend-latest.tar.gz.sha1.

Host Configuration

In laputa/shipping/hosts/production you should specify:

  • the host where you need to install the Toucan Toco app
  • the user (with sudo privileges) able to connect to the machine via SSH

eg:

[production]
toucantoco-machine.yourdomain.net ansible_ssh_user=your_user

App Configuration

Important

When you configure your Toucan Toco application, you only need to edit laputa/shipping/group_vars/production. Every configuration listed below should be set in this file.

Non On-Premise configuration

Because some configurations are only available in the SaaS context, you should disable the following configuration when you are in an On-Premise environment.

Please be sure to have in your laputa/shipping/group_vars/production, the following lines:

saas_flag:              disable
sentry_process:         disable
webpush:                disable
remote_process:         disable

Mandatory configuration

instance_name

expected value: api-toucan

This variable is mandatory.

It’s the id of the app used to identify everything about the Toucan Toco app (like configuration files, mongo database prefix, etc…).

setup_dir

default value: /data/api-toucan

This variable is mandatory.

It allows you to specify the path where the Toucan Toco app will be installed.

Please specify a path without variables (only Ansible are available).

app_log

default value: /data/tmp/toucan-log

This variable is mandatory.

It lets you configure where the Toucan Toco app’s logs will be stored.

Please specify a path without variables (only Ansible are available).

app_socket_dir

default value: /tmp

Specify the directory where the app’s socket will be created.

Important

Please note for RedHat OS family, you have to change the default value because it’s not allowed to write socket in /tmp directory.

vhost_server_name

expected value: api-toucan.mydomain.com

This variable is mandatory.

It lets you specify the vhost name used to reach the Toucan Toco app, choose the domain you want.

Important

Please note you should have the SSL certificates and keys for this domain and the DNS should be configured to reach the vhost.

user_superadmin_login and user_superadmin_password

These variables are mandatory.

Set the name and password of the super admin username.

By default super admin login is toucantoco, any other username you set has to be an email.

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

jwt_secret_key

default value: YOUR_TOKEN

Set the value of the web token secret key. We strongly recommend you to use a string of at least 20 characters.

python_install_root_dir

default value: /opt/pythonroot

Specify the directory where the python binary will be compiled and installed.

node_install_root_dir

default value: /opt/nodejsroot

Specify the directory where the node binary will be installed.

api_protocol

default value: https

This variable lets you specify if you want to expose the app in HTTPS or HTTPS.

If you choose HTTPS, you will need to also set vhost_ssl_key_file and vhost_ssl_crt_file.

You can choose between the following values:

  • https if you want to generate a virtual host configuration in HTTPS
  • http if you want to generate a virtual host configuration in HTTP

app_user and app_user_id

These variables are mandatory

Set the name and the UID of the system user who will run the Toucan Toco app.

By default the username is toucan and the UID 2000.

This user doesn’t need to be sudoer.

If the user does not exist, it will be created during the deploy of the Toucan Toco app.

UFW Firewall

firewall_flag

default value: enable

By default, the installation process will enable the UFW firewall to only allows HTTP/HTTPS and SSH “in” traffic.

If you don’t need it (or want to manually control your firewall), just disable it in the laputa/shipping/group_vars/production.

Mongo

If you do not have a MongoDB instance already installed on your infrastructure, the installation process is able to install it locally for you.

mongo_flag

expected value: enable

Should always be enable if you don’t already have a MongoDB service running elsewhere in your infrastructure.

This variable lets you install Mongo tools and service on the Toucan Toco machine.

Important

Please note if you manage your own Mongo server, be sure to disable server-side execution of JavaScript. The Toucan Toco backend already blocks this kind of NoSQL injection but it’s a good practice to also disable it at the Mongo sever level.

mongo_type

default value: docker

If don’t already have a MongoDB instance installed on your infrastructure, the installation process is able to install it locally for you.

You can install the local MongoDB instance as:

  • a docker container (when mongo_type: docker - default behavior) - in this case, please note the Toucan Toco server needs to be able to run this container
  • a service via the official distribution package installation process (when mongo_type: service)

If you already have a Mongo instance, just put in your laputa/shipping/group_vars/production:

mongo_type: none

mongodb_host

This variable is mandatory.

Specify the IP/hostname of your MongoDB host.

mongodb_port

This variable is mandatory.

Specify the port of your MongoDB host.

mongodb_admin_user and mongodb_admin_pass

These variables are mandatory.

Specify the name and password of your MongoDB privileged user (usually admin).

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

mongodb_user and mongodb_pass

These variables are mandatory.

Specify the name and password of the dedicated MongoDB user. The installation script will automatically create or update it.

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

NodeJS

Redis

If you have no Redis instance installed on your infrastructure, the installation process is able to install it locally for you.

redis_flag

expected value: enable

Should always be enable if you don’t have an available Redis service for the Toucan Toco app in your infrastructure.

This variable lets you install your Redis server.

redis_type

default value: docker

If you have no Redis instance installed on your infrastructure, the installation process is able to install it locally for you.

You can install the local Redis instance as:

  • a docker container (when redis_type: docker - default behavior) - in this case, please note the Toucan Toco server needs to be able to run this container
  • a service via the official distribution package installation process (when redis_type: service)

If you already have a Redis instance, just put in your laputa/shipping/group_vars/production:

redis_type: none

redis_host

This variable is mandatory.

Specify the IP/hostname of your Redis host.

redis_port

This variable is mandatory.

Specify the port of your Redis host.

cache_flag

Default value: disable

Specify if you want to cache MongoDB queries in Redis. Enabling the cache is an effictive way to improve the performance of the Toucan Toco app.

Nginx

Nginx is basically used as a reverse proxy in front of the Toucan Toco app: to manage SSL, potential security policies, etc…

The Toucan Toco app only listens on a local unix socket, so it’s mandatory to have a local reverse proxy to expose the app.

nginx_flag

default value: enable

Choose if you need to install nginx or not.

By default the process will install nginx on the Toucan Toco app machine.

nginx_log_dir

default value: /var/log/nginx

This variable lets you specify a different log directory for the nginx Toucan Toco app vhost.

SSL

vhost_ssl_key_file

default value: /etc/nginx/ssl/$vhost_server_name.key

This variable lets you specify the path of the SSL key associated to the vhost name you previously choose.

Only relevant when api_protocol is equal to https.

vhost_ssl_crt_file

default value: /etc/nginx/ssl/$vhost_server_name.crt

This variable lets you specify the path of the SSL crt associated to the vhost name you previously choose.

Only relevant when api_protocol is equal to https.

Supervisor

Supervisor is used to managed and launch the Toucan Toco app python processes.

supervisor_flag

default value: enable

Choose if you need to install supervisor or not.

supervisor_socket_dir

default value: /tmp/

Specify the directory path where the supervisor socket will be created.

Important

Please note for RedHat OS family, you should change the default value because it’s not allowed to write socket in /tmp directory.

supervisor_main_dir

default value: /etc/supervisor

The supervisor Toucan Toco app configuration file will be stored in this directory.

supervisor_conf_extension

default value: .ini

To match the pattern of your main supervisor configuration file, you can change and adapt the extension of the supervisor Toucan Toco app configuration file.

Gunicorn

gunicorn_workers

default value: 10

Set how many python workers will be launched by supervisor.

You should not need to change this value.

Mail Settings

It’s mandatory to configure a mail service to be able to send mails (like exports, reset password process…).

You can choose between 2 options:

  • use SendGrid
  • use a SMTP server

send_mail_from_email

default value: fromemail@example.com

Let you configure the email field of the choosen Mail Settings (e.g. SendGrid).

send_mail_from_name

default value: From Name

Let you configure the from field of the choosen Mail Settings (e.g. SendGrid).

send_mail_provider

default value: sendgrid

You can choose between the following values:

  • sendgrid if you want to use and configure SendGrid as your mail service
  • smtp if you want to use a given SMTP server

sengrid_api_key

default value: YOUR_KEY

Let you specify your Sendgrid API key.

This variable is necessary only when send_mail_provider: sendgrid otherwise it’s ignored.

smtp_host

This variable is mandatory if send_mail_provider: smtp otherwise it’s ignored.

Specify the IP/hostname of your SMTP host.

smtp_port

This variable is mandatory if send_mail_provider: smtp otherwise it’s ignored.

Specify the port of your SMTP host.

smtp_login and smtp_password

These variables are mandatory if send_mail_provider: smtp otherwise it’s ignored.

Specify the name and password of your SMTP user.

smtp_tls

Emit a STARTTLS command at the begining of the exchange to upgrade the connection using SSL/TLS.

This variable is used only when send_mail_provider: smtp otherwise it’s ignored.

Possible values:

  • true if the SMTP server supports STARTTLS
  • false if the SMTP server doesn’t support STARTTLS

smtp_smtps

If the SMTP server supports connection over SSL/TLS at the transport layer, you can enable it via this option.

This variable is used only when send_mail_provider: smtp otherwise it’s ignored.

Possible values:

  • true if the SMTP server supports SMTPS
  • false if the SMTP server only supports SMTP

Security

security_token_validity

default value: 30 days

Set the validity period of the token. Quantifiers can be any of: “hours”, “days”, “weeks”.

security_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 app will allow all origins.

E.g:

security_cross_origin_whitelist:
  - https://yourcompany.toucantoco.com
  - https://cockpit.yourcompany.com

Connectors

connectors

In this part you can list all the connectors you will enable on your instance.

All the available connectors are listed on our public repository ToucanToco/toucan-connectors

E.g:

connectors:
  - mysql
  - postgres
  - google_spreadsheet

If you want to install all the connectors you can just set the variable as following:

connectors:
  - all

If you prefer to avoid to install any connector, just remove this setting from your configuration file.

Misc

old_augment_whitelist

default value:

old_augment_whitelist:
- small_app_1
- small_app_2

This variable is used ONLY to allow old small apps to keep using the old augment. It is only used for instances that were deployed before v28.4 If your instance has been deployed after v28.4 you can merely delete this variable

Configuration example

Please find an example of configuration in the following file: laputa/shipping/group_vars/production

Installation

Once you finish to configure your laputa/shipping/group_vars/production, you just need to launch the following commands to run the full installation process:

cd laputa/
make fulldeploy stage=production

Note

If your user need a sudo password to run privileged commands during the installation process, please launch the previous command as following: make fulldeploy stage=production sudo=enable. A prompt to specify your sudo password will be displayed.

Finally you can check everything is fine with the following curls:

curl https://$vhost_server_name/

curl -A "Plop 4rQD3KzCxWzTYaRyp0NSEfd6" https://$vhost_server_name/status