Running Tiledesk with Docker Compose

This guide is still in beta. The docker images is nightly build so can contains bugs and instability.

Note that you need to know a bit of Docker and Docker Compose to follow these instructions.

Tiledesk uses Chat21 as messaging platform. Refer to Architecture overview to undestand the product's modules.

Please help us improving this documentation: if you encounter a problem, something you don’t understand or a typo, use this link to ask a question. You could also open a PR to directly fix the documentation on Github, if you want.

1. Run Docker Compose services

Run the following code:

mkdir tiledesk && cd tiledesk
curl --output docker-compose.yml
curl --output .env

Start all the Tiledesk services just typing:

docker-compose up -d

If docker is installed with root user run: sudo docker-compose up -d

Ensure the required tiledesk ports are open.

Verify the installation to

You should see the message "Hello from Tiledesk server. It's UP."

To see the log run:

docker-compose logs -t -f --tail 5

2. Firebase setup

2.1 Create a Firebase project

Sign up on Firebase and create a project. Please refer to our guide or directly to Firebase to accomplish and better understand this task.

Tiledesk uses Chat21 and Chat21 relies on Firebase as the backend, so it's really important for you to acquire familiarity with Firebase and all of his services.

3. Chat21 Cloud Functions installation and setup

3.1 Install Chat21 Cloud Functions

Start chat21-cloud-function service command line interface (CLI) typing:

docker-compose run --service-ports cloud-functions

Use sudo if you installed docker with root privilege.

More info here: Detailed Chat21 Cloud Function installation.

Authenticate to Firebase running :

firebase login

Select the firebase project where you want to install Chat21 Cloud Functions

firebase use --add

Deploy the Chat21 Cloud Functions:

firebase deploy

Exit from the Chat21 Cloud Functions CLI with :


3.2 Configure the Chat21 webhooks

Chat21 communicates with Tiledesk through webhooks. When a Chat21 event occurs - a new message arrives, a new member join a group, etc - a new Event is created and notified to Tiledesk Server. Chat21 then makes an HTTP POST request to send the Event to the Tiledesk webhook endpoint.

Chat21 needs a public Tiledesk endpoint to work properly.

Firebase requires an active billing project to perform external calls. It is necessary to do external HTTP requests and since Tiledesk Server lives outside Google’s servers we need to switch to the Blaze plan, which is surprisingly cheap.

3.2.1 Make the Tiledesk server endpoint public

If you have a public URL (public IP) of your Tiledesk server installation please skip this paragraph.

To expose Tiledesk server endpoint as public resource, we use ngrok. This simple tool allows you to create a public URLs of your local Tiledesk installation. Tiledesk docker installation has a built-in ngrok service.

Open the the following URL:


At this point, you have a tunnel to your local Tiledesk server. It means your development server is exposed to the outside world. Try making requests to your tunnel URLs – you will see that they hit your local server.

3.2.2 Setting up the webhook endpoint

If not already in use, start cloud-function service command line interface (CLI) typing:

docker-compose run --service-ports cloud-functions

Enable the webhook with :

firebase functions:config:set webhook.enabled=true

Configure the webhook endpoint with:

firebase functions:config:set webhook.url=<PUBLIC_TILEDESK_URL>/chat21/requests

Example with ngrok: firebase functions:config:set webhook.url=

Exit from the Chat21 Cloud Functions CLI with :


4. Configure the .env file

Tiledesk is composed by different clients (web widget, web chat, dashboard, etc..).

You must configure the following properties:

  • FIREBASE_PRIVATE_KEY. Get it here. More info about firebase private key here.


  • FIREBASE_PROJECT_ID. Get it here.

  • FIREBASE_APIKEY. Get it here.




  • FIREBASE_MESSAGINGSENDERID. Get it here. A unique numerical value created when you create your Firebase project, available in the Cloud Messaging tab of the Firebase console Settings pane.

  • CHAT21_ENABLED. Enable Chat21 channel with true value.

  • CHAT21_URL. Get it here.

  • CHAT21_APPID. Enter the value tilechat

  • CHAT21_ADMIN_TOKEN. The Chat21 admin token. The default value is chat21-secret-orgAa,. See here to change it.



To configure the parameters run the following command:

nano .env #configure your environment
docker-compose stop #restart docker compose
docker-compose up -d

Open the the following URL and signin as admin with :

  • email:

  • password: adminadmin