luci-app-zt-gateway/docs/INSTALL.md

Installing luci-app-zt-gateway

This package provides a ZeroTier Exit Gateway Switching UI for OpenWrt. It works on OpenWrt 24.10 (opkg) and 25.12+ (apk).

Prerequisites

The target device must have these packages installed:

Package	Provides
luci-base	LuCI framework
luci-compat	luci.ucodebridge (needed by modern LuCI)
ucode	Ucode runtime for rpcd backends
rpcd-mod-ucode	Ucode rpcd plugin
luci-theme-bootstrap	Default LuCI theme

Check with:

# OpenWrt 25.12+ (apk)
apk list --installed | grep -E 'luci-base|luci-compat|ucode|rpcd-mod-ucode|luci-theme'

# OpenWrt 24.10 and older (opkg)
opkg list-installed | grep -E 'luci-base|luci-compat|ucode|rpcd-mod-ucode|luci-theme'

Install missing prerequisites:

# apk
apk add luci-base luci-compat ucode rpcd-mod-ucode luci-theme-bootstrap

# opkg
opkg update
opkg install luci-base luci-compat ucode rpcd-mod-ucode luci-theme-bootstrap

---

Method 1: Local File Install (Development / Quick Testing)

The fastest way during development. No build step required.

mise run deploy:install
# or with a custom target:
HOST=root@10.0.0.1 mise run deploy:install

The deploy task auto-discovers all files from root/ and htdocs/, maps them to device paths, and restarts services. New files are automatically included without editing the task.

Open http://<device-ip>/cgi-bin/luci/admin/services/zt-gateway.

Note: This method has no dependency tracking. The package manager won't know about the installed files. Use for dev only.

Setting up as Exit Gateway

After deploying, run the setup wizard from the LuCI UI (Setup panel) or CLI:

ssh root@<device-ip> '/usr/sbin/zt-gateway-setup setup-all'

See SETUP-GATEWAY.md for detailed configuration and troubleshooting.

Method 2: Local Package Install via SCP

Build the .ipk (or .apk for 25.12+) with the OpenWrt SDK (see Method 5), then transfer and install:

# Transfer
scp luci-app-zt-gateway_*.ipk root@192.168.15.1:/tmp/

# OpenWrt 24.10 and older (opkg)
ssh root@192.168.15.1 'opkg update && opkg install /tmp/luci-app-zt-gateway_*.ipk'

# OpenWrt 25.12+ (apk)
ssh root@192.168.15.1 'apk add --allow-untrusted /tmp/luci-app-zt-gateway_*.apk'

You can also upload via the LuCI web UI: System → Software → Upload Package → select file → Install.

---

Method 3: OpenWrt SDK Build

Build from source using the official OpenWrt SDK. Produces a proper .ipk/.apk with dependency metadata.

# 1. Download the SDK matching your target architecture
#    https://downloads.openwrt.org/ → select release → SDK
tar -xf openwrt-sdk-*.tar.xz
cd openwrt-sdk-*

# 2. Place this package in the SDK tree
ln -s /path/to/luci-app-zt-gateway package/luci-app-zt-gateway

# 3. Update feeds (resolves luci-base, ucode, etc.)
./scripts/feeds update -a
./scripts/feeds install -a

# 4. Build just this package
make package/luci-app-zt-gateway/compile V=s

# 5. Find the output
find bin/ -name "luci-app-zt-gateway*"

Then install via Method 2.

To speed up the build:

make package/luci-app-zt-gateway/compile -j$(nproc) V=s

---

Method 4: Official Feeds Install

If the package is published to an OpenWrt feed (official or third-party):

# OpenWrt 25.12+ (apk)
apk update
apk add luci-app-zt-gateway

# OpenWrt 24.10 and older (opkg)
opkg update
opkg install luci-app-zt-gateway

Or via LuCI: System → Software → search "zt-gateway" → Install.

---

Method 5: Custom Package Feed

For distributing a third-party package to multiple devices, host the built .ipk/.apk files on an HTTP server and add a feed:

opkg-based (24.10 and older)

# On the router:
echo 'src/gz zt-gateway https://your-server.com/packages' >> /etc/opkg/customfeeds.conf
opkg update
opkg install luci-app-zt-gateway

apk-based (25.12+)

# On the router:
# Add the repo URL to /etc/apk/repositories.d/
echo 'https://your-server.com/packages' >> /etc/apk/repositories.d/custom.list
apk update
apk add --allow-untrusted luci-app-zt-gateway

The HTTP server must host:

• Package files (.ipk or .apk)
• An index file (Packages.gz for opkg, APKINDEX.tar.gz for apk)

The OpenWrt SDK's make package/index generates these indices.

---

Method 6: Image Builder / Attended Sysupgrade

Bake the package into a firmware image so it survives factory resets.

Via LuCI (recommended)

1. Install the attended sysupgrade tool:

# apk
apk add luci-app-attendedsysupgrade

# opkg
opkg install luci-app-attendedsysupgrade

2. Open System → Attended Sysupgrade
3. Click Search for firmware upgrade
4. Click Advanced Mode → add luci-app-zt-gateway to the package list
5. Click Request firmware image → wait for the build server to compile
6. Check Keep settings → Install firmware image

Via Image Builder

# Download the Image Builder for your target
tar -xf openwrt-imagebuilder-*.tar.xz
cd openwrt-imagebuilder-*

# Build with luci-app-zt-gateway included
make image PACKAGES="luci-app-zt-gateway luci-base ucode rpcd-mod-ucode luci-compat"

---

File Layout

These are the files installed by this package and their target locations:

Source	Target	Purpose
root/usr/sbin/zt-gateway-setup	/usr/sbin/zt-gateway-setup	Gateway setup script
root/usr/sbin/zt-gateway-switch	/usr/sbin/zt-gateway-switch	Gateway switching script
root/usr/share/rpcd/ucode/zt-gateway.uc	/usr/share/rpcd/ucode/zt-gateway.uc	rpcd backend
root/usr/share/rpcd/ucode/system.uc	/usr/share/rpcd/ucode/system.uc	system.board rpcd override
root/usr/share/ucode/luci/runtime.uc	/usr/share/ucode/luci/runtime.uc	LuCI ucode runtime patch
root/usr/share/luci/menu.d/luci-app-zt-gateway.json	/usr/share/luci/menu.d/luci-app-zt-gateway.json	LuCI menu registration
root/usr/share/rpcd/acl.d/luci-app-zt-gateway.json	/usr/share/rpcd/acl.d/luci-app-zt-gateway.json	rpcd ACL rules
root/etc/config/zt-gateway	/etc/config/zt-gateway	UCI config
htdocs/.../overview.js	/www/.../overview.js	LuCI frontend view