Skip to content

Installation

Jump to bottom
madmachinations edited this page Jan 5, 2025 · 4 revisions

Please read through these steps carefully and with some patience.

There are a few steps involved to getting it all set up and installed, and half of the issues which get opened are simply due to people skipping steps or not reading instructions.

Everyone makes mistakes and that's fine, but I am one person and it's extremely time consuming to walk people individually through these steps.

Use the menu in the side bar on the right to navigate this guide a bit easier.

Requirements

Before you begin, you should be sure you can meet these requirements:

Hardware

You need a computer on your network capable of running the server application 24/7. This computer must have either an x86_64 OR an Arm64 CPU. For most this will be the system where you are running Home Assistant currently.

The server application itself is very light weight, however, during a sync process it will start up a web browser to access the Amazon website. As such, the computer running this needs to be powerful enough to handle this process while running Home Assistant.

Raspberry Pis will likely struggle, but would probably work on a pi4 or 5. Though this is entirely a guess and is untested.

Amazon account

You need the login details for the Amazon account where your Alexa device is going to add things to the shopping list.

Currently, if your amazon account has a passkey associated with it - this can cause problems during the authentication process.

I have no proof of this, yet, but I suspect you MUST have MFA setup on your Amazon account. And that you must ONLY have 1 form of MFA set up on your account, preferably the one where it texts you. I suspect some people have had issues because the MFA form changes during the login process when you have none or several forms of MFA set up on your account.

Step 1 - Installing the server

The server runs as a headless background service.

The server runs on TCP port 4000. This does NOT need to be accessible to the outside world, but DOES need to be accessible to your local network in some form. If you have very restrictive rules setup on your rig, you might need to open this up. But most should be fine.

There are a few different ways to install the server:

Via the pre-build container on docker hub

You can find pre-built containers on docker hub here:

https://hub.docker.com/r/madmachinations/ha-alexa-shopping-list-sync

When you run the container, make sure you mount a local directory into the container's /config path. This is where configuration and session data will be persisted.

These have been built for x86_64 and arm64 environments.

Via the HASS Add-on

If you are using HASS / HomeAssistant OS - There is a HASS Add-on of the server.

Add this repository to your HASS installation, and then install the alexa shopping list add-on:

https://github.com/madmachinations/home-assistant-alexa-shopping-list-hass

Build your own container image

  1. Download this repository
  2. cd into the server directory
  3. Run your docker build ... command

When you run the container, make sure you mount a local directory into the container's /config path. This is where configuration and session data will be persisted.

Manually with python and systemd

You can run the server manually as a service within systemd.

First, download this repository and mv the server directory to wherever you want it to be installed within your file system.

Next, your system needs to have the following packages installed:

  • chromium
  • chromium-chromedriver
  • python3
  • pip3

Now let's install the python packages that are required:

  • cd /wherever/you/installed/the/server/
  • sudo pip3 install -r requirements.txt

Next, we need to setup a systemd service file:

To do this, create a new file called alexa-shopping-list.service within your /etc/systemd/service/ directory, which contains the following:

[Unit]
Description=Alexa Shopping List
After=network.target

[Service]
ExecStart=/usr/bin/python3 /path/to/server/server.py

# If the script crashes, restart it automatically
Restart=always
RestartSec=5

[Install]
WantedBy=multi-user.target

After this file is saved, now run these commands:

  • sudo systemctl daemon-reload
  • sudo systemctl enable alexa-shopping-list
  • sudo systemctl start alexa-shopping-list

You can check if it is running with sudo systemctl status alexa-shopping-list

Step 2 - Configure the server

Before the server can do anything, it needs to be configured.

You can do this with the client script in this repository.

What is the client?

You can think of the client being like a remote control for the server.

You run it on your laptop or whatever computer you are sat on right now, and it connects to the server you just installed so you can talk with it and get it all set up and logged into your amazon account.

Download the client

You can download each version of the project files on the releases page here:

https://github.com/madmachinations/home-assistant-alexa-shopping-list/releases

You probably want whatever the latest one is.

THE CLIENT SCRIPT IS RUN ON THE COMPUTER YOU ARE USING RIGHT NOW, NOT ON YOUR HOME ASSISTANT BOX AND NOT WITHIN THE RUNNING CONTAINER. YOU NEED TO DOWNLOAD THE FILES FROM THIS REPOSITORY TO YOUR COMPUTER, AND THE CLIENT SCRIPT IS INSIDE THE CLIENT FOLDER

Run the client

Before we begin, you need to make sure your system has both python3 and pip3 installed.

If that is the case, cd into the client directory

If this is the first time using the client, install it's dependencies with something like:

pip3 install --user -r requirements.txt

Now we are ready to run the client and configure our server.

The client is opened like this:

python3 client.py <IP_ADDRESS_OF_SERVER>

So, let's assume the system you have installed the server onto has the IP address 192.168.0.200; You would start the client like this:

python3 client.py 192.168.0.200

When the client starts it immediately tries to connect to the server. If it can connect, it checks to see if the server is configured.

If the server is not yet configured, the configuration process will start:

  1. The first thing it will ask, is what domain name do you access the amazon website through. The default value is amazon.co.uk, because I'm British, so... it is what it is. This has only been tested on amazon.co.uk so far.
  2. Next it will check if the server is logged into your account on the amazon website, which it won't be. So it will immediately ask you to enter the email address and password you login to Amazon with.
  3. If your account has MFA enabled, after a few moments it should ask you to enter your MFA code.
  4. Assuming all of this went to plan, the server should now be authenticated with your account on the Amazon website.
  5. You will now find yourself on the client command line, you can just type quit and press enter to close it, or press ctrl + c. If you have things on your alexa shopping list already, you can check if you can see them by typing list and pressing enter. After 5-10 seconds you should see your shopping list in the terminal.

As far as Amazon is concerned, this is like you opening the website in chromium and using your account to use the shopping list.

Your actual login credentials, your email and password, are NOT stored anywhere. They are used to perform the login, and they are forgotten immediately after this.

Instead, all the cookies and values in the web browser session once logged in are saved by the server, and reloaded each time it has to do something.

If it is synchronising regularly, this session should just stay alive. But it possible your session will expire or become invalidated after a long while. In which case you will have to open the client again at some point and perform the login steps again.

Step 3 - Install the custom component to Home Assistant

The custom component connects to the server and uses it to keep your HA shopping list synchronised.

  1. In your HA config directory, make sure there is a folder called custom_components. Create it if it does not exist.
  2. Copy the alexa_shopping_list folder out of custom_components folder in this projects files, which you downloaded earlier to use the client. Paste the alexa_shopping_list folder into your HA's custom_components folder.
  3. Restart Home Assistant and wait for it to reload
  4. In HA, go to Settings > Devices & Integrations and press Add integration. Find Alexa Shopping List and click on that to start the configuration process
  5. The first config screen will ask you to enter the IP address and port number of the server we installed earlier. Enter your IP address, and the default port is 4000. Press next and the component will check if it can connect.
  6. Once a successful connection is established to the server, it will ask you how frequently you want to synchronise the shopping list in minutes. I am running mine every 60 minutes. There is also a server which you can call at any time to force it to synchronise now. Choose a figure that is reasonable, don't spam it.
  7. That's it! After a few moments, your HA shopping list should be replaced with whatever is on your alexa shopping list.
Clone this wiki locally