Build from Docker Images

Updated 5 days ago by Maurizio Cibelli


Hu:toma AI is an open source stack designed to help you create compelling conversational interfaces with little effort and above industry accuracy. You can view an intro to the platform here:

To support launching a simple, local version of the Hutoma system check the following instructions. For comments, issues, suggestions please visit our community


You will need to have installed:

  1. Docker (, then check the instructions for your Operating System)
  2. Docker-Compose (

For Mac and Windows users it is recommended to set the docker memory limit above 5GB.

Getting Started

  1. Clone or Download the Repo to your local machine.
  2. Open a terminal window and go to directory where you just downloaded the project (ex. ~/hutoma_system_launcher-master)
  3. Type . to run the setup - this will download all the docker container images and run it through docker-compose. The first time you run it will take a while as the database will be initialized, volumes created, etc. Subsequent runs should spin up faster.
  4. Verify step 3 is completed by navigating to https://localhost:8443. Tell your browser to ignore the security warning due to the use of the self-signed certificate. If you see the login form then you can proceed to step 5, otherwise wait a bit more.
  5. If the platform is up, go to a new terminal window and type . to create a test user
  6. Go back to https://localhost:8443 and login with:
    • username:
    • password: Pass@word1


Additional setup

Running the Word2Vec service locally

  1. If you wish to run the Word2Vec service locally, set the's USE_LOCAL_W2V variable to TRUE (USE_LOCAL_W2V=true). Set it to FALSE to use the public service (this is the recommended default)

Customizing the test user

A convenience script is included to create a user without having to go through the registration process.

  1. Edit and change the USER_EMAIL variable to contain the email address you want to use. All remaining variables should just work with the existing defaults
  2. If no errors are shown during the execution of the script, you should have now a new user created
  3. Navigate to https://localhost:8443, tell your browser to ignore the security warning due to the use of the self-signed certificate, and login with:
    • username: (the email address you defined on step 1, or if you haven't changed this)
    • password: Pass@word1

Enabling new user registration and password resets

If you want to enable the web console to support the creation of new users, you will need to add a few extra environment variables.

To add Google Re-Captcha support: You will need to get your recaptcha public and private "keys" from Google (, and update the following environment variables within the script:


Additionally, you will need a SMTP2GO account (, and update the following environment variables accordingly with an account that has permissions to use the SMTP service:


Enabling additional languages (optional)

You can define which languages to use by changing the languages_array variable. If you make changes to this then you'll also need to update the languages_w2v_files variable to include the respective Word2Vec vector pickled files. Recommended to leave this as it is for now. The only built-in language is English, which is always enabled by default. To support Spanish and Italian, you need to tell the system to turn the support on. A convenience script enable_languages.shis included to make this process easy. You just need to run the script, and wait up to a minute, and the new languages will now be accepted by the system.


How do I create a bot in Spanish? Currently there is no way to do it through the web console. You will need to create a bot (which will default to English), and export it. Edit the exported JSON file, and look for the field

"language": "en"

Set it to "es" for Spanish, or "it" for Italian and save the file. Then either import the bod-inplace, or create a new one using the updated file. Note, if you get an error message stating that the language is not supported, make sure you've only used one of the supported languages mentioned here, and that when you run the there were no errors.

How did we do?