Matter Server Docker Container Install Help Needed

Configuration Matter/Thread
, ,
1

Just installed the latest stable version of Home Assistant in a Docker container on Ubuntu 22.04.5 LTS. and I am attempting to install and configure the Matter Integration / Server via Docker run.

The Matter-Server container is running but when I attempt to add the Matter integration I am greeted with the following:

“Failed to connect”.

The URL is ws://localhost:5580/ws. I have also attempted to connect via its local ip address.

To add the Matter integration does IPv6 need to be enabled? I realize that it is needed for the adding and controlling of devices but not sure if it is needed for the initial configuration.

Can someone provide a SIMPLE to follow guide to setting up the Matter integration when using the Docker container version of Home Assistant.

As an added bonus it would be nice to have a simple guide on how to configure IPv6 LAN/VLAN to enable Matter functionality.

Guessing that there are a number of people using Home Assistant Container in conjunction with Ubuntu server on a network utilizing a pfSense firewall/router.

FWIW For the past two years I have been running Home Assistant via Docker Container with multiple added integrations via containers.

2

I have HA and Matter running under docker on Ubuntu.

No. HA and python-matter-server talk to each other over websockets (ws) which can use IPv4 or IPv6. Assuming the networking is setup correctly HA should actually auto-discover the python-matter-server as a new integration.

The docs recommend using host networking for the python-matter-server container, but it can be made to work with macvlan network if you know what you’re doing.

If you’re running ufw or any other firewall on the Ubuntu server, make sure port 5580 is open for incoming connections.

You should be able to access the python-matter-server web dashboard in your browser at http://hostnameorip:5580 — if your browser can’t reach it, HA likely won’t be able to make a websockets connection either.

Ubuntu should have IPv6 enabled by default, but if it was somehow disabled, there are plenty of guides to enable it. As long as you use a single subnet, default link local addresses should work fine. If you have a Thread subnet, you do need to make sure the kernel is adding Router Advertisements (RAs) to the IPv6 route table. There is a guide on the python-matter-server GitHub.

If you are trying to use multiple VLANs, things get complicated because Matter traffic was not designed to pass through regular routers. Most guides suggest not even trying, but are workarounds that require some networking knowledge (e.g. tagged vlan interfaces on the Ubuntu server).

3

Add it to a common docker network with HA and use its hostname

4

@peterxian Apparently the Matter Server is actually never starting.

I appear to be missing chip.json in the data directory. See log excerpt below.

2025-07-03 21:15:54.272 (MainThread) INFO [chip.storage] Initializing persistent storage from file: /data/chip.json
2025-07-03 21:15:54.272 (MainThread) ERROR [chip.storage] [Errno 2] No such file or directory: '/data/chip.json'
2025-07-03 21:15:54.272 (MainThread) CRITICAL [chip.storage] Could not load configuration from /data/chip.json - resetting configuration...
2025-07-03 21:15:54.272 (MainThread) WARNING [chip.storage] No valid SDK configuration present - clearing out configuration
2025-07-03 21:15:54.272 (MainThread) WARNING [chip.storage] No valid REPL configuration present - clearing out configuration
2025-07-03 21:15:54.274 (MainThread) ERROR [root] Uncaught exception
5

Post compose or docker run

If folder exists on host and is mounted correctly, maybe it doesn’t have permission to access folder. If it didn’t exist at all it generally mounts it in a volume but if it exists but cannot access it fails with missing file

6

Hi @tmjpugh Thanks for your assistance with this.

I created the matter-server directory and it’s sub directory data prior to executing the Docker Run below.

docker run -d \
  --name matter-server \
  --restart=unless-stopped \
  --security-opt apparmor=unconfined \
  -v /docker/matter-server/data:/data \
  -v /run/dbus:/run/dbus:ro \
  --network=host \
  ghcr.io/home-assistant-libs/python-matter-server:stable --storage-path /data --paa-root-cert-dir /data/credentials --bluetooth-adapter 0

Was wondering does --storage-path /data need to be altered as well or does -v /docker/matter-server/data:/data map to the correct location?

The following items were found in /docker/matter-server/data directory

hip_config.ini  chip_counters.ini  chip_factory.ini
7

try running specific version like below.

I didnt see anything wrong with what you had but much of what you had was default so below just has that removed.

i dont use bluetooth on my server and i think the /run/dbus is for that. shouldnt effect start but you can try run without. I always run minimum setup for troubleshooting to eliminate all possiblities.

also try specify version.

docker run -d \
  --name matter-server \
  --restart=unless-stopped \
  -v /docker/matter-server/data:/data \
  -v /run/dbus:/run/dbus:ro \
  --network=host \
  ghcr.io/home-assistant-libs/python-matter-server:8.0.0
8

EDIT: It’s working now!!!

OKAY so I have made progress.

Taking your advice “I always run minimum setup for troubleshooting” I discovered that IPv6 was disabled in GRUB. Enabling it seemed to help in getting the Matter Server running.

However I am now greeted with the following error when attempting to add the integration to HA.

The Matter server is not the correct version

In an attempt to overcome this I deleted the Matter Server container and image and started over with STABLE which did not resolve the issue.

Home Assistant log show the following

2025-07-04 07:06:36.904 ERROR (MainThread) [frontend.js.latest.202301040] http://192.168.5.3:8124/config/integrations:0:0 ResizeObserver loop completed with undelivered notifications.

I can reach the Python Matter Server web interface.

FabricId: 1
Compressed FabricId: 17635571447967429000
SDK Wheels Version: 2025.4.0
Schema Version: 11
Node count: 0

EDIT: It’s working now!!!

Some how my second Home Assistant container running the latest stable reverted to using the stable from 2023.

I checked docker container ls and it showed both containers now using home-assistant:stable from 2 years ago.

I checked docker image list and there was now only one image for stable.

Have no idea how the latest Home Assistant image was deleted as I made sure to install the newest version yesterday.

So I deleted the Home Assistant container I created to install and test Matter. I then recreated the new Home Assistant container this time I specified the version rather than choosing stable. Someone smart suggested “also try specify version.”

Once the new Home Assistant container was up and running and after setting up the user account the Matter integration was automatically discovered.

Again thanks for your assistance.

1 Like
9

Hi @peterxian was able to get the Matter server integration installed and working with Home Assistant.

While the container was running the actual Matter server was continually restarting. Apparently this was due to IPv6 being disabled on the host via its GRUB file. I then discovered I needed to reinstall the latest HA container as well as the Matter container.

Once all of that was done HA automagicly discovered the Matter server.

Now I need to figure out what what settings need to be configured on my AP (OpenWRT) and router (pfSense) to allow the Matter IPv6 traffic to pass. I am setting everything up on it’s own VLAN

Thanks again for your input.

10

Really nothing special here
I set my phone to matter vlan when I provision devices. For this I just allow connection to HA server and matter server from the vlan. Everything else is blocked.