Skip to content

Commit 8c5c9ed

Browse files
agnersmarcelveldtMartinHjelmare
authored
Build container image on Python Matter server release (#327)
Co-authored-by: Marcel van der Veldt <m.vanderveldt@outlook.com> Co-authored-by: Martin Hjelmare <marhje52@gmail.com>
1 parent 381fd1a commit 8c5c9ed

File tree

5 files changed

+229
-49
lines changed

5 files changed

+229
-49
lines changed

‎.github/workflows/publish-to-pypi.yml

-43
This file was deleted.

‎.github/workflows/release.yml

+84
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,84 @@
1+
name: Publish releases
2+
3+
on:
4+
release:
5+
types: [published]
6+
7+
jobs:
8+
build-and-publish-pypi:
9+
name: Builds and publishes releases to PyPI
10+
runs-on: ubuntu-latest
11+
outputs:
12+
version: ${{ steps.vars.outputs.tag }}
13+
steps:
14+
- uses: actions/checkout@v3.5.3
15+
- name: Get tag
16+
id: vars
17+
run: echo "tag=${GITHUB_REF#refs/*/}" >> $GITHUB_OUTPUT
18+
- name: Set up Python 3.10
19+
uses: actions/setup-python@v4.6.1
20+
with:
21+
python-version: "3.10"
22+
- name: Install build
23+
run: >-
24+
pip install build tomli tomli-w
25+
- name: Set Python project version from tag
26+
shell: python
27+
run: |-
28+
import tomli
29+
import tomli_w
30+
31+
with open("pyproject.toml", "rb") as f:
32+
pyproject = tomli.load(f)
33+
34+
pyproject["project"]["version"] = "${{ steps.vars.outputs.tag }}"
35+
36+
with open("pyproject.toml", "wb") as f:
37+
tomli_w.dump(pyproject, f)
38+
- name: Build
39+
run: >-
40+
python3 -m build
41+
- name: Publish release to PyPI
42+
uses: pypa/gh-action-pypi-publish@v1.8.6
43+
with:
44+
user: __token__
45+
password: ${{ secrets.PYPI_TOKEN }}
46+
repository-url: https://test.pypi.org/legacy/
47+
build-and-push-container-image:
48+
name: Builds and pushes the Matter Server container to ghcr.io
49+
runs-on: ubuntu-latest
50+
permissions:
51+
packages: write
52+
needs: build-and-publish-pypi
53+
steps:
54+
- uses: actions/checkout@v3.5.3
55+
- name: Log in to the GitHub container registry
56+
uses: docker/login-action@v2.1.0
57+
with:
58+
registry: ghcr.io
59+
username: ${{ github.repository_owner }}
60+
password: ${{ secrets.GITHUB_TOKEN }}
61+
- name: Set up Docker Buildx
62+
uses: docker/setup-buildx-action@v2.2.1
63+
- name: Version number for tags
64+
id: tags
65+
shell: bash
66+
run: |-
67+
patch=${GITHUB_REF#refs/*/}
68+
echo "patch=${patch}" >> $GITHUB_OUTPUT
69+
echo "minor=${patch%.*}" >> $GITHUB_OUTPUT
70+
echo "major=${patch%.*.*}" >> $GITHUB_OUTPUT
71+
- name: Build and Push
72+
uses: docker/build-push-action@v3.3.0
73+
with:
74+
context: .
75+
platforms: linux/amd64,linux/arm64
76+
file: Dockerfile
77+
tags: |-
78+
ghcr.io/${{ github.repository_owner }}/python-matter-server:${{ steps.tags.outputs.patch }},
79+
ghcr.io/${{ github.repository_owner }}/python-matter-server:${{ steps.tags.outputs.minor }},
80+
ghcr.io/${{ github.repository_owner }}/python-matter-server:${{ steps.tags.outputs.major }},
81+
ghcr.io/${{ github.repository_owner }}/python-matter-server:stable
82+
push: true
83+
build-args:
84+
"PYTHON_MATTER_SERVER=${{ needs.build-and-publish-pypi.outputs.version }}"

‎Dockerfile

+34
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,34 @@
1+
FROM python:3.11-slim-bullseye
2+
3+
# Set shell
4+
SHELL ["/bin/bash", "-o", "pipefail", "-c"]
5+
6+
WORKDIR /app
7+
8+
RUN \
9+
set -x \
10+
&& apt-get update \
11+
&& apt-get install -y --no-install-recommends \
12+
libuv1 \
13+
openssl \
14+
zlib1g \
15+
libjson-c5 \
16+
libnl-3-200 \
17+
libnl-route-3-200 \
18+
unzip \
19+
gdb \
20+
&& apt-get purge -y --auto-remove \
21+
&& rm -rf \
22+
/var/lib/apt/lists/* \
23+
/usr/src/*
24+
25+
ARG PYTHON_MATTER_SERVER
26+
27+
# hadolint ignore=DL3013
28+
RUN \
29+
pip3 install --no-cache-dir "python-matter-server[server]==${PYTHON_MATTER_SERVER}"
30+
31+
VOLUME ["/data"]
32+
EXPOSE 5580
33+
34+
ENTRYPOINT ["matter-server", "--storage-path", "/data"]

‎README.md

+111-3
Original file line numberDiff line numberDiff line change
@@ -1,10 +1,118 @@
11
# Python Matter Server
22

3-
This project implements a Matter Controller Server over WebSockets using the [official Matter (formerly CHIP) SDK](https://github.com/project-chip/connectedhomeip) as a base and provides both a server and client implementation.
3+
This project implements a Matter Controller Server over WebSockets using the
4+
[official Matter (formerly CHIP) SDK](https://github.com/project-chip/connectedhomeip)
5+
as a base and provides both a server and client implementation.
46

5-
The goal of this project is primary to have Matter support in Home Assistant but its universal approach makes it suitable to be used in other projects too.
7+
The goal of this project is primary to have Matter support in Home Assistant
8+
but its universal approach makes it suitable to be used in other projects too.
69

7-
This repository is for development only (so not for enduser support). For enabling Matter support within Home Assistant, please refer to the [Home Assistant documentation](https://www.home-assistant.io/integrations/matter/).
10+
## Support
11+
12+
Got questions?
13+
14+
You have several options to get them answered:
15+
16+
* The Home Assistant [Community Forum](https://community.home-assistant.io/).
17+
* The Home Assistant [Discord Chat Server](https://discord.gg/c5DvZ4e).
18+
* Join [the Reddit subreddit in /r/homeassistant](https://reddit.com/r/homeassistant).
19+
20+
If you experience issues using Matter with Home Assistant, please open an issue
21+
report in the [Home Assistant Core repository](https://github.com/home-assistant/core/issues/new/choose).
22+
23+
You may also open issues in this repository if you are absolutely sure that your
24+
issue is related to the Matter Server component.
25+
26+
## Installation
27+
28+
We strongly recommend to use Home Assistant OS along with the official Matter
29+
Server add-on to use Matter with Home Assistant. The Matter integration
30+
automatically installs the Python Matter Server add-on. Please refer to the
31+
[Home Assistant documentation](https://www.home-assistant.io/integrations/matter/).
32+
Home Assistant OS has been tested and tuned to be used with Matter and Thead,
33+
which makes this combination the best tested and largely worry free
34+
environment.
35+
36+
If you still prefer a self-managed container installation, we do offer an
37+
official container image. Please keep in mind that you might experience
38+
communication issues with Matter devices, especially Thread based devices.
39+
This is mostly because the container installation uses host networking, and
40+
relies on the networking managed by your operating system.
41+
42+
### Requirements to communicate with Wi-Fi/Ethernet based Thread devices
43+
44+
Make sure your you run the container on the host network. The host network
45+
interface needs to be in the same network as the Android/iPhone device
46+
you are using for commissioning. Matter uses link-local multicast protocols
47+
which do not work accross different LANs or VLANs.
48+
49+
The host network interface needs IPv6 support enabled.
50+
51+
### Requirements to communicate with Thread devices through Thread border routers
52+
53+
For communication through Thread border routers which are not running on the same
54+
host as the Matter Controller server to work, IPv6 routing needs to be properly
55+
working. IPv6 routing is largely setup automatically through the IPv6 Neighbor
56+
Discovery Protocol, specifically the Route Information Options (RIO). However,
57+
if IPv6 ND RIO's are processed, and processed correctly depends on the network
58+
management software your system is using. There may be bugs and cavats in
59+
processing this Route Information Options.
60+
61+
In general, make sure the kernel option `CONFIG_IPV6_ROUTER_PREF` is enabled and
62+
that IPv6 forwarding is disabled (sysctl variable `net.ipv6.conf.all.forwarding`).
63+
If IPv6 forwarding is enabled, the Linux kernel doesn't employ reachability
64+
probing (RFC 4191), which can lead to longer outages (up to 30min) until
65+
network changes are detected.
66+
67+
If you are using NetworkManager, make sure to use at least NetworkManager 1.42.
68+
Previous versions lose track of routes and stale routes can lead to unreachable
69+
Thread devices. All current released NetworkManager versions can't handle
70+
multiple routes to the same network properly. This means if you have multiple
71+
Thread border routers, the fallback won't work immediately (see [NetworkManager
72+
issue #1232](https://gitlab.freedesktop.org/NetworkManager/NetworkManager/-/issues/1232)).
73+
74+
We currently don't have experience with systemd-networkd. It seems to have its
75+
own IPv6 Neighbor Discovery Protocol handling.
76+
77+
If you don't use NetworkManager or systemd-networkd, you can use the kernel's
78+
IPv6 Neighbor Discovery Protocol handling.
79+
80+
Make sure the kernel options `CONFIG_IPV6_ROUTE_INFO` is enabled and the
81+
following sysctl variables are set:
82+
83+
```
84+
sysctl -w net.ipv6.conf.wlan0.accept_ra=1
85+
sysctl -w net.ipv6.conf.wlan0.accept_ra_rt_info_max_plen=64
86+
```
87+
88+
If your system has IPv6 forwarding enabled (not recommended, see above), you'll
89+
have to use `2` for the accept_ra variable. See also the [Thread Border Router - Bidirectional IPv6 Connectivity and DNS-Based Service Discovery codelab](https://openthread.io/codelabs/openthread-border-router#6).
90+
91+
### Running the Matter Server using container image
92+
93+
With the following command you can run the Matter Server in a container using
94+
Docker. The Matter network data (fabric information) are stored in a newly
95+
created directory `data` in the current directory. Adjust the command to
96+
choose another location instead.
97+
98+
```
99+
mkdir data
100+
docker run -d \
101+
--name matter-server \
102+
--restart=unless-stopped \
103+
--security-opt apparmor=unconfined \
104+
-v $(pwd)/data:/data \
105+
-v /run/dbus:/run/dbus:ro \
106+
--network=host \
107+
ghcr.io/home-assistant-libs/python-matter-server:stable
108+
```
109+
110+
### Running using Docker compose
111+
112+
```sh
113+
docker compose up -d
114+
docker compose logs -f
115+
```
8116

9117
NOTE: Both Matter and this implementation are in early (v1) state and features are probably missing or could be improved. See our [development notes](#development) how you can help out, with development and/or testing.
10118

‎compose.yml

-3
Original file line numberDiff line numberDiff line change
@@ -2,9 +2,6 @@ version: "3.8"
22
services:
33
# python-matter-server
44
matter-server:
5-
build:
6-
context: ./
7-
dockerfile: Dockerfile.dev
85
image: matter-server:latest
96
container_name: matter-server
107
restart: unless-stopped

0 commit comments

Comments
 (0)