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:

```bash
# 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:

```bash
# 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.

```bash
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:

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

See [SETUP-GATEWAY.md](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:

```bash
# 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.

```bash
# 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:

```bash
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):

```bash
# 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)

```bash
# 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+)

```bash
# 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:

```bash
# 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

```bash
# 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 |