Installation & Configuration

Getting Started

The Timbr platform is built on Apache Superset, and so the key features of Apache Superset are available and maintained through the Timbr platform as well.

Superset is battle tested in large environments with hundreds of concurrent users. Airbnb\'s production environment runs inside Kubernetes and serves 600+ daily active users viewing over 100K charts a day.

The Timbr platform supports Python version 3.9 and is designed to be highly available. It is \"cloud-native\" as it has been designed scale out in large, distributed environments, and works well inside containers.

While you can easily test drive Timbr on a modest setup or simply on your laptop, there\'s virtually no limit around scaling out the platform.

Timbr is also cloud-native in the sense that it is flexible and lets you choose your web server (Gunicorn, Nginx, Apache), your metadata database engine (MySQL, Postgres, MariaDB, ...), your message queue (Redis, RabbitMQ, SQS, ...), your results backend (S3, Redis, Memcached, ...), your caching layer (Memcached, Redis, ...), works well with services like NewRelic, StatsD and DataDog, and has the ability to run analytic workloads against most popular database technologies.

The Timbr web server and the Timbr Celery workers (optional) are stateless, so you can scale out by running on as many servers as needed.

Install and Deploy Timbr Locally with Docker

To try Timbr locally, the best-supported currently method is via Docker, using docker-compose. Timbr does not have official support for Windows, so we have provided a VM workaround below. (We will update this documentation once Windows is supported.)

Step 0 - Install a Docker Engine and Docker Compose

Mac OSX:

Install Docker for Mac, which includes the Docker engine and a recent version of [docker-compose]{.title-ref} out of the box.

Once you have Docker for Mac installed, open up the preferences pane for Docker, go to the \"Resources\" section and increase the allocated memory to 6GB. With only the 2GB of RAM allocated by default, Timbr will fail to start.

Linux:

Install Docker on Linux by following Docker's instructions for whichever flavor of Linux suits you.

Because docker-compose is not installed as part of the base Docker installation on Linux, once you have a working engine, follow the docker-compose installation instructions for Linux.

Windows:

NOTE: Windows is currently not a supported environment for Timbr installation.

For Windows users, the best option may be to install an Ubuntu Desktop VM via VirtualBox and proceed with the Docker on Linux instructions inside of that VM. It is recommended to assign at least 8GB of RAM to the virtual machine as well as provisioning a hard drive of at least 40GB, so that there will be enough space for both the OS and all of the required dependencies.

Step 1 - Launch Timbr via `docker-compose up`

Next, cd into the folder you created in Step 1:

$ cd timbr

Once you\'re in the directory, run the following command:

$ docker-compose up

You should see a wall of logging output from the containers being launched on your machine. Once this output slows to a crawl, you should have a running instance of Timbr on your local machine!

Step 2 - Log In to Timbr

Your Timbr local instance also includes a Postgres server to store your data and is already pre-loaded with some example datasets that ship with Timbr. You can access Timbr now via your web browser by visiting http://localhost:5000. Note that many browsers now default to https - if yours is one of them, please make sure it uses http.

Log in with the default username and password:

    username: admin
    password: Admin@123

Congrats! You have successfully installed Timbr!

Configuration behind a load balancer

If you are running Timbr behind a load balancer or reverse proxy (e.g. NGINX or ELB on AWS), you may need to utilise a healthcheck endpoint so that your load balancer knows if your Timbr instance is running. This is provided at /health which will return a 200 response containing \"OK\" if the the webserver is running.

If the load balancer is inserting X-Forwarded-For/X-Forwarded-Proto headers, you should set [ENABLE_PROXY_FIX = True]{.title-ref} in the Timbr config file to extract and use the headers.

In case that the reverse proxy is used for providing ssl encryption, an explicit definition of the [X-Forwarded-Proto]{.title-ref} may be required. For the Apache webserver this can be set as follows: :

RequestHeader set X-Forwarded-Proto "https"

---

Configure SSO Azure AD in Timbr

Please make sure you have an HTTPS endpoint (Azure AD doesn't allow configuring HTTP servers). The Timbr platform should have an existing SSL certificate.

Once the SSL is configured, you can create the App Registration in Azure to enable the SSO authentication.

In order to configure the SSO with Azure AD in Timbr, you will need the following App Registration details:

• AZURE_APPLICATION_ID

• AZURE_TENANT_ID

• AZURE_SECRET

  Next, in the Timbr platform deployment YAML file, configure the following environment variables:

- name: OAUTH_PROVIDER
  value: azure
- name: OAUTH_CLIENT_ID
  value: <AZURE_APPLICATION_ID>
- name: OAUTH_SECRET
  value: <AZURE_SECRET>
- name: OAUTH_BASE_URL
  value: https://login.microsoftonline.com/<AZURE_TENANT_ID>/oauth2

The App Registration needs the following permissions:

Microsoft Graph (4)	Scope	Delegation	Description
	email	Delegated	View users' email address
	openid	Delegated	Sign users in
	profile	Delegated	View users' basic profile
	User.Read	Delegated	Sign in and read user profile

In the authentication tab of App Registration, add the redirect URL (Under web) with your Timbr public URL

                    https://<timbr-public-url>/oauth-authorized/azure

Once you have set the App Registration, you can configure the YAML file of timbr-platform together with the environment variable to enable the SSO authentication.

---

Sync Azure AD Groups with Timbr Roles

1. App Registration permissions:

The first step to sync the Azure AD Groups with Timbr roles, is to configure additional permissions in the App Registration where the platform’s SSO is defined.

Add the following permissions:

• User.Read.All

• Group.Read.All

• GroupMember.Read.All

2. Update timbr-server environment variables:

Set the App Registration client_id, tenant_id, and secret, in the following environment variables:

• name: AZURE_CLIENT_ID

  value:

• name: AZURE_TENANT_ID

  value:

• name: AZURE_CLIENT_SECRET

  value:

3. Choose timbr roles to sync from AD Groups:

Once we’ve set up the environment variables in timbr-server, you can set any role to sync from Azure AD Group.

To configure which group to sync, you can use the Group Name or Group ID or Group Email, and run the following SQL statements in Timbr:

ALTER ROLE `role_name` SYNC name = 'group_name'

or

ALTER ROLE `role_name` SYNC id = 'group_id'

or

ALTER ROLE `role_name` SYNC email = 'group_email'

Once a role is synced, it has a default update interval of 24 hours. The sync interval is configurable and can be customized by adding the variable SYNC_GROUPS_INTERVAL=time_in_seconds to the docker compose file under timbr server. In case you need to manually sync the role, run the following SQL statement:

SYNC ROLE `role_name`;

To automatically create users according to new users added to AD Groups, you can add the variable SYNC_GROUPS_AUTO_CREATE_USER=TRUE to the docker compose file under timbr server.

---

Environment Variables

You can pass in to the docker or kubernetes instance of the Timbr platform the following environment variables, as docker secret or kubernetes secret:

Environment Variable	Required	Default Value	Description
CAN_UPLOAD_CSV	No	False	Enables the form to upload CSVs as datasets
DB_CONNECTION	Yes	mysql	Database connection type used to store the Timbr platform db. Supported options are mysql, postgresql and mssql
DB_DATABASE	Yes	superset	Database name for the Timbr platform db. Default name is superset.
DB_HOST	Yes	localhost	Host name for the Timbr platform to access the Timbr platform db.
DB_PORT	Yes		Port for the Timbr platform to access the Timbr platform db.
DB_USERNAME	Yes		Username for the Timbr platform to access the Timbr platform db.
DB_PASSWORD	Yes		Password for the Timbr platform to access the Timbr platform db.
DB_SECRET_KEY	Yes		Secret key to validate the integrity of the connection with the Timbr platform db as a string (minimum recommended characters = 18)
FLASK_DEBUG	No	False	Should the server start in debug mode.
FLASK_ENV	No	production	Type of the server running the environment
FLASK_SECRET_KEY	No		Salt used to encrypt the key of the user sessions saved on the server side.
GOOGLE_ANALYTICS_TAG	No		Turned off by default. The value for the google analytic tag to track usage through Google Analytics
MAPBOX_API_KEY	No		Turned off by default. API Key required to render charts created with MapBobx
REDIS_AUTH	No	None	Turned off by default. Redis authentication user for Redis. Redis is used as message queue and Timbr platform cache to run with background workers.
REDIS_DB	No	None	Turned off by default. Redis database name to store results cache.
REDIS_HOST	No	None	Turned off by default. Redis database host
REDIS_PORT	No	None	Turned off by default. Redis database port
SQLLAB_LIMIT	No	1000	Default max limit to be applied on queries in the SQL Lab component

For more information or help in the installation process please contact [email protected]