ParleyPort
Docker app from junkerderprovinz's Repository
Your own relay for apps that pair their instances.
Overview
Readme
View on GitHub
Build Lint Docker Pulls Image Size Arch Go Unraid License: AGPL-3.0
ParleyPort is a relay for apps that pair their instances. When two of your instances sit on different networks and neither can reach the other, both dial out to ParleyPort and meet there. It passes their messages on without being able to read them, and it runs as one small container that keeps no accounts and stores nothing.
- Download
- Support
- What it looks like
- What it does
- Getting started
- For app authors
- How AI is used here
A one-knight job: I build it, keep it running, work through the issues and add what people ask for, until nothing is missing. It is free, with no accounts, no telemetry, no ads and no paid tier. No asterisk anywhere. Nothing readable ever leaves your own walls. Forged on evenings and weekends, with heart and stubbornness.
If it has earned a place on your server or computer, toss a coin to your knight: it helps cover the costs and keeps the project alive. It also makes this knight's heart beat a little faster. Three ways below, whichever suits you.
Its address shows a short page that says what it is, and that is all of ParleyPort a browser sees. The rest is the relay setting in your apps and the container's log.
An app's relay card pointing at your own ParleyPort
The container's log after a start: ready and listening
Apps that use ParleyPort pair their instances with twelve words. Instances on the same network talk directly. Instances on different networks, behind NAT or a firewall that lets nothing in, need a third point both can dial out to, and that point is a relay. ParleyPort groups the connections that present the same relay key, a hash of your twelve words, and passes their messages between them.
- It cannot read what it carries. Every message is sealed with AES-256-GCM under a key derived from the twelve words, and the routing fields are bound into the seal, so a relay can neither open a message nor send it to another instance.
- It keeps nothing. No accounts, no database and no record of who connects. Client addresses are left out of its log. What any relay can still see is which instances talk and when, which is the reason to run your own.
- It brings its own certificate. Give it a domain and it fetches and renews a Let's Encrypt certificate on port 443, with port 80 left closed. Without a domain it serves plain HTTP on port 8760 for a reverse proxy in front.
- It is small. A few megabytes for amd64 and arm64, fine on a small VPS while your instances stay at home.
You probably do not need it: these apps use a project relay by default, and an instance that is already reachable from outside can often serve as the relay itself. ParleyPort is for your own relay without putting the app itself on the open internet.
On Unraid, install ParleyPort from Community Applications. Anywhere else, for a reverse proxy in front:
docker run -d --name parleyport -p 8760:8760 junkerderprovinz/parleyport:latest
The proxy sends /relay/connect to port 8760 with WebSocket upgrades allowed (in Nginx Proxy Manager, switch on Websockets Support). Set PARLEYPORT_PUBLIC_URL to the address your instances dial, for example https://relay.example.org. If the proxy runs in another container or on another machine, also name it in PARLEYPORT_TRUSTED_PROXIES, for example 172.18.0.5. Failed handshakes then count against the caller and not against the proxy that everyone comes through.
To let ParleyPort handle TLS itself instead, set PARLEYPORT_DOMAIN, forward port 443 to it and keep its certificates on a volume:
docker run -d --name parleyport -p 443:443 \
-e PARLEYPORT_DOMAIN=relay.example.org \
-v /path/to/parleyport:/var/lib/parleyport \
junkerderprovinz/parleyport:latest
Then, on every instance of the group, open Settings, Pairing, Relay, Own relay and enter the address, for example https://relay.example.org. The twelve words stay the same, so switching relays needs no new pairing. A relay that ran from the old knightloader-relay image can switch images as it is, since ParleyPort still reads its KL_RELAY_* variables.
Other Docker hosts
compose.yaml runs ParleyPort on any Linux server with Docker. Put it in a folder of its own and start it with docker compose up -d. The folders are created next to the file.
- Synology: in Container Manager, create a project from the file (DSM 7.2 or newer).
- Proxmox: run it in a VM or an LXC container that has Docker.
- MOS: install ParleyPort from the MOS Hub.
The other half of ParleyPort is the kit, the client side of the protocol as a Go module of its own. An app that pairs its instances imports it and gets the twelve words, the member keys, the relay client, the group that finds its members on the network or over the relay, and the fortress that puts all of a household's apps under one phrase.
go get github.com/junkerderprovinz/parleyport/kit@latest
The kit has a version line of its own. The server's tags are vX.Y.Z, the kit's are kit/vX.Y.Z, so an app moves to a new kit without waiting for a new relay. kit/README.md lists the packages, and kit/CHANGELOG.md says what each version brought.
A plugin without Go code takes part through the two helpers attached to every release, built for linux/amd64 and arm64. fortress joins a fortress, lists the members, reads their status, asks one of them for an action and takes one out. notify sends a message to the channels in a file and shows and saves those channels with every secret masked. Check what you download against helpers-sha256sums.txt:
base=https://github.com/junkerderprovinz/parleyport/releases/latest/download
curl -fsSL -O "$base/fortress-linux-amd64" -O "$base/helpers-sha256sums.txt"
sha256sum --check --ignore-missing helpers-sha256sums.txt
One knight builds this, and AI is one of the tools I work with, the same way I work with an editor or a compiler. It helps me write code and documentation and it checks my work, and that saves me a good many evenings. It does not make the decisions, though. I read and understand everything before it ships, and if something here breaks, that is on me and not on the tool.
You do not have to take my word for it. The code is open and every release note is written by hand. The issue tracker shows how problems actually get handled, including the ones I got wrong the first time. If you find something that is not right, open an issue and I will look at it.
Bugs, ideas or feature requests? Please open a GitHub issue.
The name ParleyPort, its logo and its branding are not covered by the AGPL-3.0 licence of the code: a fork needs its own name and look.
Categories
Download Statistics
Related apps
Explore more like this
Explore allLinks
Details
junkerderprovinz/parleyport:latestRuntime arguments
- Network
bridge- Shell
sh- Privileged
- false
- Extra Params
--restart unless-stopped
Template configuration
Plain HTTP for a reverse proxy in front. Point the proxy at this port and allow WebSocket upgrades on /relay/connect. /health answers with the status and version.
- Target
- 8760
- Default
- 8760
- Value
- 8760
Only with a domain set below. Enter the host port your router forwards 443 to. Leave it empty in plain mode, and keep it off 443 if the Unraid web interface already uses that port.
- Target
- 443
Your relay's domain, for example relay.example.org. With it set, ParleyPort serves TLS on 443 inside the container and gets its own Let's Encrypt certificate through port 443 alone. Several names can be given, separated by commas, to keep an old name working during a move. Leave it empty for plain mode behind a proxy.
- Target
- PARLEYPORT_DOMAIN
The address your instances dial, for example https://relay.example.org, or several separated by commas. An instance may prove who it is only to the relay it names when it connects, so set this in plain mode behind a proxy. In domain mode the names above already count and this can stay empty.
- Target
- PARLEYPORT_PUBLIC_URL
For a reverse proxy in another container or on another machine: its address, for example 172.18.0.5, or a range no wider than a /28 (IPv4) or /124 (IPv6). Separate several with commas. Failed handshakes then count against the caller and not against the proxy everyone comes through. Left empty, only a proxy on the same host is trusted; none trusts no proxy at all.
- Target
- PARLEYPORT_TRUSTED_PROXIES
Holds the certificates in domain mode, so a restart does not ask Let's Encrypt for a new one. Stays empty in plain mode.
- Target
- /var/lib/parleyport
- Default
- /mnt/user/appdata/parleyport
- Value
- /mnt/user/appdata/parleyport