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"
services:
echo-speaks-server:
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
ports:
- 8091:8091 # WebUI must match PORT below
# Set environment variables
environment:
- 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
volumes:
- data:/root
volumes:
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 0.0.0.0 for the IP.
error: Config Check Did Not Pass
info: ** Echo Speaks Config Service (v2.8.0) is Running at (IP: 192.168.1.10 | 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:
https://cloud.hubitat.com/api/YOUR-HUB-ID/apps/APP-ID/receiveData?access_token=XXXXXX-XXXX-XXXX-XXXX-XXXXXXXX
Replace this section of the URL:
https://cloud.hubitat.com/api/YOUR-HUB-ID/apps/
With this new local URL:
http://LOCAL.HUB.IP/apps/api/
Full Resulting URL Example:
http://HUB.IP/apps/api/APP-ID/receiveData?access_token=XXXXXX-XXXX-XXXX-XXXX-XXXXXXXX
Now use this new URL in the server setup screen where it asks for the callback URL.
