[GUIDE] Echo Speaks Server on Docker (or without)

A compilation of instructions and tips to get Echo Speaks running locally through docker

Other Guides and Links are in the next post, including how to install without Docker!

Installing echo-speaks-server on Docker

This assumes you already have docker / docker-compose / portainer installed and operational on your chosen platform.

Portainer / Docker-Compose

If you already have Portainer installed this is the easiest way to install and manage the container. You can create the container manually but I prefer to use Stacks with a compose file.

Instructions are for portainer but you could also use the yaml with a docker-compose command line (untested).

  • Select: Stacks >> +Add Stack
  • Name the new stack: echo-speaks-server
  • Web Editor paste in the yaml config below:
version: "3"
    container_name: echo-speaks-server
    image: tonesto7/echo-speaks-server
    restart: unless-stopped
    # Network mode host allows IP to be automatically detected
    # Windows MUST change from host to bridge mode and set IP in settings below
    network_mode: host
    #network_mode: bridge
    # Port mappings are ignored with host mode
      - 8091:8091   # WebUI must match PORT below
    # Set environment variables
      - useHeroku=false
      - hubPlatform=Hubitat

      #### UNCOMMENT Options to use them (remove the # and keep the -) ####
      ## Host IP Address Override if needed
      ## MUST Uncomment next line and set IP when using network_mode: bridge
      #- ipAddress=192.168.1.XXX

      ## Change WebUI Port if needed
      #- PORT=8091

      ## Set callback URL here if you want
      #- appCallbackUrl=

      ## Set amazon domain and locale if need to change from default
      #- amazonDomain=amazon.com
      #- regionLocale=en-US

    # Keeps login and session if re-deployed
      - data:/root
  data: {}
  • This config will work as-is for the majority of users without any changes.
    • Running on Windows will require bridge networking and setting the IP.
    • The various options are explained in the comments.
    • Callback URL can be set to local URL here, see section at bottom.
  • Once you have the config set scroll down and press Deploy the stack

NOTE: ARM or other non-amd64 systems (ex: Raspberry Pi)

If you need to build the image for a non-amd64 system, replace the image definition with this build definition instead.

    # Replace image definition with build for non-amd64 systems
    build: https://github.com/tonesto7/echo-speaks-server.git

Once Deployed:
Complete the setup through the Echo Speaks app on Hubitat

Docker for Windows

From a cmd prompt or PowerShell terminal use the following command to setup and run the container.
Note: You must fill in your hosting server IP address on Windows because bridged networking mode is used

docker run -e ipAddress=X.X.X.X -p 8091:8091 --name echo-speaks-server --restart=unless-stopped -d tonesto7/echo-speaks-server
  • -e ipAddress=X.X.X.X --- Sets an environment variable so the ES server knows what IP to send back to Hubitat
  • -p 8091:8091 --- Maps the port across the bridged docker connection
  • --restart=unless-stopped --- This will make the container restart if it crashes

In the Docker Desktop UI you should now have a running container in the Containers section.
Click the name of the container to go to the logs, you should have something like this below. The most important bit is that your host server IP is shown and not for the IP.

error:        Config Check Did Not Pass
info:         ** Echo Speaks Config Service (v2.8.0) is Running at (IP: | Port: 8091) | ProcessId: 1 **
info:         ** On Heroku: (false) **
info:         Checking for Server Version Updates...
info:         Server Version is Up-to-Date.

You can try browsing to http://SERVER.IP:8091 to test if it is working.

Complete the setup through the Echo Speaks app on Hubitat!

Docker on Linux

Note: The ipAddress variable is OPTIONAL with host networking mode.
If the server is sending the wrong IP back to Hubitat you will need to delete the container. Then try again using the ipAddress variable, filling your own host server IP.

docker run \
  --network host \
  --name echo-speaks-server \
  -e ipAddress=X.X.X.X \
  --restart=unless-stopped \
  -d tonesto7/echo-speaks-server
  • --network host --- Uses the host network directly instead of a bridge
  • -e ipAddress=X.X.X.X --- Sets an environment variable so the ES server knows what IP to send back to Hubitat
  • --restart=unless-stopped --- This will make the container restart if it crashes

You can try browsing to http://SERVER.IP:8091 to test if it is working.

Complete the setup through the Echo Speaks app on Hubitat!

Setting Amazon domain and/or Locale

The docker-compose example now provides an example in the environment options.
If you need to set them for docker command line it is set similar to the ipAddress variable

      -e amazonDomain=amazon.com
      -e regionLocale=en-US

Hubitat App Login

  • Open Echo Speaks App
  • Click button under Alexa Login Status text
  • Click Manage Cookie Login Status
  • Deselect the Use Heroku option
  • Select your Domain and Locale
  • Click Begin Server Setup and KEEP THIS POP UP OPEN
    • See supplemental instructions in next section to use a local callback URL
  • Open your server in another tab http://SERVER.IP:8091
    • First fill in the callback URL and click Save Settings
    • Then log into Amazon using the button at the top and wait to be redirected back to the settings page (do NOT click Save at bottom again)
    • Close server login tab and the callback url popup
    • Go back to the Hubitat app browser window
    • Page should refresh and show you are logged in (otherwise press next)
  • If you get red error text that you still need to login:
    • Restart the docker container
    • Click the Amazon Login Page button
    • Log in again (do not click Save at bottom)
    • Close the server login tab, and the main app should refresh
  • You should now be logged in with no errors in the Hubitat app

Local callback URL

The default setup has the server using a cloud callback URL. If you would like to keep this local you can modify the callback URL and remove the cloud link. Copy the entire callback URL into a text editor and then replace the start of the URL as shown below (keep end part the same).

Original URL Example:

Replace this section of the URL:

With this new local URL:

Full Resulting URL Example:

Now use this new URL in the server setup screen where it asks for the callback URL.


Linux: Installing echo-speaks-server without Docker

You need Node.js and npm installed first (this may vary depending on your OS):

sudo apt install nodejs
sudo apt install npm

Install and Run the Server:

Log in with the user who will run the server (does not need to be root).
Change to directory you wish to run the server from (can be home folder, subfolders will be created).

sudo npm install -g pm2
npm i https://github.com/tonesto7/echo-speaks-server
cd node_modules/echo-speaks-server
pm2 -n echo-speaks start index.js
pm2 startup
pm2 save
pm2 list

:star: Complete the setup through the Echo Speaks app on Hubitat!

If your server is not detecting the correct IP address. You can manually set it to the LAN IP of the host machine this server is running on with the command below. You only need to run this once.

ipAddress=192.168.X.X pm2 restart echo-speaks --update-env

If you need to change the Amazon domain or Locale use these commands
(adjust the domain/locale as needed)

amazonDomain=amazon.com pm2 restart echo-speaks --update-env
regionLocale=en-US pm2 restart echo-speaks --update-env

Links to Other Helpful Posts

Other Helpful Guides

Docker on Synology: [GUIDE] Synology docker for echo-speaks-server ( echo-speaks)

Directly on Node.js Linux without Docker, should work for RPi: [RELEASE] Echo Speaks V4 - #629 by user2305

How to manually specify ipAddress when NOT using Docker: [RELEASE] Echo Speaks V4 - #1229 by jtp10181

Other Posts with Tips

Setup using Portainer without Stacks config: [RELEASE] Echo Speaks V4 - #1286 by dJOS


Running the tonesto7/echo-speaks-server docker on my QNAP.

It installed/setup fine and seems to be running so far.. For the past 3 days when I get home from work, I send a test to the Echo and it works and I see no errors when going the the HE app page for echo speaks..

What's not working right is the website for the docker and pinging the docker.
Yes I'm pinging the right IP and it's a DHCP static. I've rebooted a couple times to verify that its keeping the ip.

Weird part is pinging the docker. It mostly times out and sometimes gets a reply. Than it will go through a long session where the pings are good for a long time.. But I've yet to be able to get back to the web site again.

Isn't really an issue right now, seeing that it works. But I'd like to know why it's happening.

I'm just running the docker in Container Station.

check for dupe IP's. shutdown your nas - then ping and see if something responds

What are your network settings for the container? I had to switch to bridge mode and assign a static IP otherwise it would get a container station assigned IP which wasn’t accessible from HE.

1 Like

I'm a little new to Docker and have been doing some research...

I thought it was getting an IP from my Wireless router..

When I look at the console for the Echo Speaks docker I see an IP 192.168.2 187.
I'm now able to ping it all the time and its been staying up and running.

Problem is, if the docker station gets rebooted the MAC address changes because it is random.
But it keeps that same IP and I am not able to put it in my DHCP static table for my router.

I now see the bridge settings and will have to look into it to see how to utilize them.

But as far as the Echo speaks goes, it is has been working for a while.
I haven't setup a rule yet. but I do a test every day to see if my Echo Speaks will play a message and it does..

Thanks for the info.

1 Like

Yep new MAC address every time which is frustrating. I mostly use bridge mode networking for my containers so I know each container’s IP.


Is that something just with Container Station? I use host mode and it just assumes the IP of the host and no port forwarding is needed, which is the intention. Sounds like that is not working as intended? I could add a note to the guide to use bridge mode for container station. Do you run it with the command line or using the YAML compose config?

If you Google qnap container station mac address you will find many complaints. Here is one way to fix though not something I have tried myself.

easy guide, thanks for sharing.

1 Like

Having an odd problem on an unraid setup. Everything appears to be configured correctly, log shows the containerized server logging in to amazon successfully...then it immediately logs back out. Echo Speaks app shows it as logged out immediately after the server shows it as logged in.

Not certain what's going on. Tried the local url (using IP of my hub and format of http://{hubip}/apps/api/136/receiveData?access_token={token here}) and that didn't work. Got the login page and all, logged in fine...then was just logged out automatically again.

EDIT: Solved it...somehow. I set things up in a private tab and it seemed to take. Not certain what the deal was, but it's resolved!

Does anyone know how to make this work on windows 11 using wsl? I have everything installed but I cannot connect to the linux machine from outside the container

Do you have network bridging turned on for the container?

I don't know.. This is my first foray into wsl, I have ubuntu installed , echo speaks inside that

This is why I quickly abandoned using WSL2 when I was trying it out.
Here are some ways to hack around the issue that I found:
This [WSL 2] NIC Bridge mode 🖧 (Has TCP Workaround🔨) · Issue #4150 · microsoft/WSL · GitHub
And this Accessing network applications with WSL | Microsoft Learn

Unless you plan to use this WSL2 Ubuntu for other development work I would honestly just install Docker for Windows and have that use WSL2 (its the default I think), then add Portainer. Docker takes care of the bridge network and port forwarding. Portainer gives you a nice web UI to manage containers.


I agree! I only need this for echo speaks really.

I would chose one of these two options then.

  1. Install it directly on windows
  2. Use Docker for Windows.

Direct on Windows would be the lightest on resources but I don't have a guide for it. For installing on Windows you really just need to install Node.js for windows and then the install is similar to the no-docker instructions. Catch being pm2 does not work on windows so you have to use something like NSSM to set it up as a system service. NSSM - the Non-Sucking Service Manager . You could also just make a shortcut in your startup folder but then you need to be logged in for it to run.

Docker uses the same WSL backend and takes care of the rest for you, I think it will be a lighter system overall as well. Be warned though WSL will consume 2Gb of RAM by default, including when using with Docker. Here is some info on how to change it if you wanted, I had mine set to 1Gb when I tested and it could probably go even lower for just ES: https://fizzylogic.nl/2023/01/05/how-to-configure-memory-limits-in-wsl2

1 Like

Good morning Sir. Can you help me? I am following your instructions on installing echo speak without docker.
Ok made some progress but stuck. I installed node and npm. I confirmed by doing a node - v and npm -v in a cmd prompt. I also tested my server with hello word.

But where/how do I type the following command (remember I am on Windows!)

Install and Run the Server:

Log in with the user who will run the server (does not need to be root).
Change to directory you wish to run the server from (can be home folder, subfolders will be created).

sudo npm install -g pm2
npm i https://github.com/tonesto7/echo-speaks-server
cd node_modules/echo-speaks-server
pm2 -n echo-speaks start index.js
pm2 startup
pm2 save
pm2 list

Thank you!

Just for reference if anyone else finds this, I posted some quick instructions for installing on Windows without docker here:

Sorry jtp10181 but I got this error trying the npm i https....
see pic.