Merge pull request #2788 from alexbelgium/claude/zealous-wozniak-qk5ow5

Add Zoraxy reverse proxy add-on
2026-06-24 00:06:04 +02:00 · 2026-06-19 22:16:32 +02:00
parent 36f84b36e9 7323936899
commit 6e611fe3d2
8 changed files with 305 additions and 0 deletions
--- a/zoraxy/CHANGELOG.md
+++ b/zoraxy/CHANGELOG.md
@@ -0,0 +1,7 @@
+## 3.3.3 (2026-06-19)
+- Initial release
+- Zoraxy reverse proxy with web management UI (port 8000) for Home Assistant
+- Persistent configuration stored in the add-on config directory (/config)
+- Options exposed: NOAUTH, ZEROTIER, FASTGEOIP, MDNS, plus env_vars passthrough
+- ZeroTier mode supported via the NET_ADMIN capability and /dev/net/tun device
+- Based on upstream tobychui/zoraxy (https://github.com/tobychui/zoraxy/releases)
--- a/zoraxy/Dockerfile
+++ b/zoraxy/Dockerfile
@@ -0,0 +1,130 @@
+#============================#
+#  ALEXBELGIUM'S DOCKERFILE  #
+#============================#
+#           _.------.
+#       _.-`    ('>.-`"""-.
+# '.--'`       _'`   _ .--.)
+#    -'         '-.-';`   `
+#    ' -      _.'  ``'--.
+#        '---`    .-'""`
+#               /`
+#=== Home Assistant Addon ===#
+
+#################
+# 1 Build Image #
+#################
+
+ARG BUILD_FROM
+ARG BUILD_VERSION
+FROM ${BUILD_FROM}
+
+##################
+# 2 Modify Image #
+##################
+
+# Set S6 wait time
+ENV S6_CMD_WAIT_FOR_SERVICES=1 \
+    S6_CMD_WAIT_FOR_SERVICES_MAXTIME=0 \
+    S6_SERVICES_GRACETIME=0
+
+USER root
+
+##################
+# 3 Install apps #
+##################
+
+# Add rootfs
+COPY rootfs/ /
+RUN find . -type f \( -name "*.sh" -o -name "run" -o -name "finish" \) -print -exec chmod +x {} \;
+
+# Uses /bin for compatibility purposes
+# hadolint ignore=DL4005
+RUN if [ ! -f /bin/sh ] && [ -f /usr/bin/sh ]; then ln -s /usr/bin/sh /bin/sh; fi && \
+    if [ ! -f /bin/bash ] && [ -f /usr/bin/bash ]; then ln -s /usr/bin/bash /bin/bash; fi
+
+# Persist Zoraxy data in /config (addon_config) instead of the ephemeral
+# upstream working directory, so the configuration survives add-on updates.
+RUN sed -i 's#/opt/zoraxy/config#/config#g' /opt/zoraxy/entrypoint.py
+
+# Modules
+ARG MODULES="00-banner.sh"
+
+# Automatic modules download
+COPY ha_automodules.sh /ha_automodules.sh
+RUN chmod 744 /ha_automodules.sh && /ha_automodules.sh "$MODULES" && rm /ha_automodules.sh
+
+# Manual apps
+ENV PACKAGES="jq"
+
+# Automatic apps & bashio
+COPY ha_autoapps.sh /ha_autoapps.sh
+RUN chmod 744 /ha_autoapps.sh && /ha_autoapps.sh "$PACKAGES" && rm /ha_autoapps.sh
+
+# Install bashio
+RUN BASHIO_VERSION="0.14.3" && \
+    mkdir -p /tmp/bashio && \
+    curl -f -L -s -S "https://github.com/hassio-addons/bashio/archive/v${BASHIO_VERSION}.tar.gz" | tar -xzf - --strip 1 -C /tmp/bashio && \
+    mv /tmp/bashio/lib /usr/lib/bashio && \
+    ln -s /usr/lib/bashio/bashio /usr/bin/bashio && \
+    rm -rf /tmp/bashio
+
+################
+# 4 Entrypoint #
+################
+
+# Add entrypoint
+ENV S6_STAGE2_HOOK=/ha_entrypoint.sh
+COPY ha_entrypoint.sh /ha_entrypoint.sh
+RUN chmod 777 /ha_entrypoint.sh
+
+# Install bashio standalone fallback
+COPY bashio-standalone.sh /usr/local/lib/bashio-standalone.sh
+RUN chmod 0755 /usr/local/lib/bashio-standalone.sh
+
+WORKDIR /
+ENTRYPOINT [ "/usr/bin/env" ]
+CMD [ "/ha_entrypoint.sh" ]
+
+############
+# 5 Labels #
+############
+
+ARG BUILD_ARCH
+ARG BUILD_DATE
+ARG BUILD_DESCRIPTION
+ARG BUILD_NAME
+ARG BUILD_REF
+ARG BUILD_REPOSITORY
+ARG BUILD_VERSION
+ENV BUILD_VERSION="${BUILD_VERSION}"
+LABEL \
+    io.hass.name="${BUILD_NAME}" \
+    io.hass.description="${BUILD_DESCRIPTION}" \
+    io.hass.arch="${BUILD_ARCH}" \
+    io.hass.type="addon" \
+    io.hass.version=${BUILD_VERSION} \
+    maintainer="alexbelgium (https://github.com/alexbelgium)" \
+    org.opencontainers.image.title="${BUILD_NAME}" \
+    org.opencontainers.image.description="${BUILD_DESCRIPTION}" \
+    org.opencontainers.image.vendor="Home Assistant Add-ons" \
+    org.opencontainers.image.authors="alexbelgium (https://github.com/alexbelgium)" \
+    org.opencontainers.image.licenses="MIT" \
+    org.opencontainers.image.url="https://github.com/alexbelgium" \
+    org.opencontainers.image.source="https://github.com/${BUILD_REPOSITORY}" \
+    org.opencontainers.image.documentation="https://github.com/${BUILD_REPOSITORY}/blob/main/README.md" \
+    org.opencontainers.image.created=${BUILD_DATE} \
+    org.opencontainers.image.revision=${BUILD_REF} \
+    org.opencontainers.image.version=${BUILD_VERSION}
+
+#################
+# 6 Healthcheck #
+#################
+
+ENV HEALTH_PORT="8000" \
+    HEALTH_URL=""
+HEALTHCHECK \
+    --interval=5s \
+    --retries=5 \
+    --start-period=30s \
+    --timeout=25s \
+    CMD curl -A "HealthCheck: Docker/1.0" -s -f "http://127.0.0.1:${HEALTH_PORT}${HEALTH_URL}" &>/dev/null || curl -k --fail "https://127.0.0.1:${HEALTH_PORT}${HEALTH_URL}" &>/dev/null || exit 1
--- a/zoraxy/README.md
+++ b/zoraxy/README.md
@@ -0,0 +1,78 @@
+# Home assistant add-on: Zoraxy
+
+
+I maintain this and other Home Assistant add-ons in my free time: keeping up with upstream changes, HA changes, and testing on real hardware takes a lot of time (and some money). I use around 5-10 of my >110 addons so regularly I install test machines (and purchase some test services such as vpn) that I don't use myself to troubleshoot and improve the addons
+
+If this add-on saves you time or makes your setup easier, I would be very grateful for your support!
+
+[![Buy me a coffee][donation-badge]](https://www.buymeacoffee.com/alexbelgium)
+[![Donate via PayPal][paypal-badge]](https://www.paypal.com/donate/?hosted_button_id=DZFULJZTP3UQA)
+
+## Addon informations
+
+![Version](https://img.shields.io/badge/dynamic/yaml?label=Version&query=%24.version&url=https%3A%2F%2Fraw.githubusercontent.com%2Falexbelgium%2Fhassio-addons%2Fmaster%2Fzoraxy%2Fconfig.yaml)
+![Arch](https://img.shields.io/badge/dynamic/yaml?color=success&label=Arch&query=%24.arch&url=https%3A%2F%2Fraw.githubusercontent.com%2Falexbelgium%2Fhassio-addons%2Fmaster%2Fzoraxy%2Fconfig.yaml)
+
+[donation-badge]: https://img.shields.io/badge/Buy%20me%20a%20coffee-%23d32f2f?logo=buy-me-a-coffee&style=flat&logoColor=white
+[paypal-badge]: https://img.shields.io/badge/Donate%20via%20PayPal-0070BA?logo=paypal&style=flat&logoColor=white
+
+## About
+
+[Zoraxy](https://github.com/tobychui/zoraxy) is a general purpose HTTP request (reverse) proxy and forwarding tool with a clean web management UI. It can be used as a modern, actively-maintained alternative to Nginx Proxy Manager: create reverse proxy hosts, manage TLS certificates (including ACME / Let's Encrypt), set up redirections, access rules, a basic web server and more.
+
+This add-on is based on the official [docker image](https://github.com/tobychui/zoraxy/tree/main/docker) from tobychui.
+
+## Installation
+
+The installation of this add-on is pretty straightforward and not different in
+comparison to installing any other Hass.io add-on.
+
+1. Add my add-ons repository to your home assistant instance (in supervisor addons store at top right, or click button below if you have configured my HA)
+   [![Open your Home Assistant instance and show the add add-on repository dialog with a specific repository URL pre-filled.](https://my.home-assistant.io/badges/supervisor_add_addon_repository.svg)](https://my.home-assistant.io/redirect/supervisor_add_addon_repository/?repository_url=https%3A%2F%2Fgithub.com%2Falexbelgium%2Fhassio-addons)
+1. Install this add-on.
+1. Click the `Save` button to store your configuration.
+1. Start the add-on.
+1. Check the logs of the add-on to see if everything went well.
+1. Open the Web UI and create your administrator account.
+
+## Configuration
+
+The management Web UI is exposed on port `8000`. Because Zoraxy acts as a reverse
+proxy that must own the standard web ports, it is **not** served through Home
+Assistant ingress — open it directly:
+
+Webui can be found at `http://homeassistant.local:8000`
+
+The reverse proxy itself listens on ports `80` (HTTP) and `443` (HTTPS). Make
+sure these ports are free on the host (e.g. not used by another proxy add-on)
+and, if you want to reach your services from outside, forward them on your
+router.
+
+All configuration, the database, logs and plugins are stored persistently in the
+add-on configuration folder (`/addon_configs/<slug>_zoraxy/`, exposed inside the
+container as `/config`), so they survive add-on updates and restarts.
+
+### Options
+
+| Option      | Default | Description                                                                                  |
+| ----------- | ------- | -------------------------------------------------------------------------------------------- |
+| `NOAUTH`    | `false` | Disable authentication for the management interface (use with care).                          |
+| `ZEROTIER`  | `false` | Enable the ZeroTier global area network controller (uses the `NET_ADMIN` capability and `/dev/net/tun`, both granted by the add-on). |
+| `FASTGEOIP` | `false` | Enable high-speed GeoIP lookup (uses ~1 GB extra memory).                                      |
+| `MDNS`      | `true`  | Enable mDNS service discovery.                                                                 |
+| `TZ`        | -       | Timezone, e.g. `Europe/Brussels`.                                                             |
+| `env_vars`  | `[]`    | Pass any additional upstream environment variable (e.g. `AUTORENEW`, `DB`, `MDNSNAME`, ...).   |
+
+Any other upstream setting documented in the [Zoraxy docker README](https://github.com/tobychui/zoraxy/tree/main/docker) can be supplied through `env_vars`:
+
+```yaml
+env_vars:
+  - name: AUTORENEW
+    value: "86400"
+  - name: DB
+    value: "auto"
+```
+
+## Support
+
+Create an issue on the [repository](https://github.com/alexbelgium/hassio-addons).
--- a/zoraxy/build.json
+++ b/zoraxy/build.json
@@ -0,0 +1,6 @@
+{
+    "build_from": {
+        "aarch64": "zoraxydocker/zoraxy:latest",
+        "amd64": "zoraxydocker/zoraxy:latest"
+    }
+}
--- a/zoraxy/config.yaml
+++ b/zoraxy/config.yaml
@@ -0,0 +1,48 @@
+---
+arch:
+  - aarch64
+  - amd64
+description: "🦓 General purpose request (reverse) proxy and forwarding tool with web management UI"
+image: ghcr.io/alexbelgium/zoraxy-{arch}
+name: Zoraxy
+slug: zoraxy
+url: https://github.com/alexbelgium/hassio-addons/tree/master/zoraxy
+version: "3.3.3"
+init: false
+startup: services
+webui: "http://[HOST]:[PORT:8000]"
+ports:
+  80/tcp: 80
+  443/tcp: 443
+  8000/tcp: 8000
+ports_description:
+  80/tcp: HTTP traffic for reverse-proxied hosts
+  443/tcp: HTTPS traffic for reverse-proxied hosts
+  8000/tcp: Management Web UI
+map:
+  - addon_config:rw
+  - share:rw
+  - ssl
+privileged:
+  - NET_ADMIN
+devices:
+  - /dev/net/tun
+environment:
+  PORT: "8000"
+  DOCKER: "true"
+  PLUGIN: /config/plugin
+options:
+  NOAUTH: false
+  ZEROTIER: false
+  FASTGEOIP: false
+  MDNS: true
+  env_vars: []
+schema:
+  NOAUTH: bool
+  ZEROTIER: bool
+  FASTGEOIP: bool
+  MDNS: bool
+  TZ: str?
+  env_vars:
+    - name: match(^[A-Za-z0-9_]+$)
+      value: str?
--- a/zoraxy/rootfs/etc/cont-init.d/20-config.sh
+++ b/zoraxy/rootfs/etc/cont-init.d/20-config.sh
@@ -0,0 +1,14 @@
+#!/usr/bin/with-contenv bashio
+# shellcheck shell=bash
+set -e
+
+#############################################
+# Prepare persistent storage under /config  #
+#############################################
+
+# Zoraxy stores its database, configuration, logs and plugins relative to its
+# working directory. The Dockerfile patched the upstream entrypoint to use
+# /config (mapped to addon_config) so the data survives add-on updates.
+mkdir -p /config /config/plugin /config/conf /config/log /config/tmp
+
+bashio::log.info "Zoraxy data directory: /config"
--- a/zoraxy/rootfs/etc/services.d/zoraxy/run
+++ b/zoraxy/rootfs/etc/services.d/zoraxy/run
@@ -0,0 +1,9 @@
+#!/usr/bin/with-contenv bashio
+# shellcheck shell=bash
+
+bashio::log.info "Starting Zoraxy..."
+
+# All Zoraxy options are passed as environment variables (converted from the
+# add-on options by the 00-global_var module) and consumed by the upstream
+# entrypoint, which launches the zoraxy binary from /config.
+exec python3 -u /opt/zoraxy/entrypoint.py
--- a/zoraxy/updater.json
+++ b/zoraxy/updater.json
@@ -0,0 +1,13 @@
+{
+  "last_update": "2026-06-19",
+  "paused": false,
+  "repository": "alexbelgium/hassio-addons",
+  "slug": "zoraxy",
+  "source": "github",
+  "upstream_repo": "tobychui/zoraxy",
+  "upstream_version": "3.3.3",
+  "github_beta": false,
+  "github_fulltag": false,
+  "github_tagfilter": "",
+  "github_exclude": ""
+}