https://github.com/seamys/luci-app-https-gateway
๐ OpenWrt LuCI application โ nginx reverse proxy + ACME certificate management + dnsmasq DNS automation for LAN HTTPS access
https://github.com/seamys/luci-app-https-gateway
acme certificate dns homelab https letsencrypt luci nginx openwrt reverse-proxy
Last synced: 11 days ago
JSON representation
๐ OpenWrt LuCI application โ nginx reverse proxy + ACME certificate management + dnsmasq DNS automation for LAN HTTPS access
- Host: GitHub
- URL: https://github.com/seamys/luci-app-https-gateway
- Owner: seamys
- License: mit
- Created: 2026-05-26T03:07:47.000Z (about 1 month ago)
- Default Branch: main
- Last Pushed: 2026-06-12T13:23:02.000Z (15 days ago)
- Last Synced: 2026-06-12T14:19:16.564Z (14 days ago)
- Topics: acme, certificate, dns, homelab, https, letsencrypt, luci, nginx, openwrt, reverse-proxy
- Language: Shell
- Size: 67.4 KB
- Stars: 0
- Watchers: 0
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- License: LICENSE
- Agents: AGENTS.md
Awesome Lists containing this project
README
# ๐ luci-app-https-gateway
**LAN HTTPS Reverse Proxy Gateway for OpenWrt**
[](https://github.com/seamys/luci-app-https-gateway/releases)
[](LICENSE)
[](#testing)
[](https://openwrt.org/)
[](src/bin/https-gateway)
[](#internationalization)
Manage nginx reverse proxy, automatic ACME certificate issuance, and local DNS resolution through a LuCI web UI โ providing HTTPS access for all your LAN services with zero manual configuration.
[๐ Documentation](docs/) ยท [๐ Report Bug](https://github.com/seamys/luci-app-https-gateway/issues) ยท [๐ก Request Feature](https://github.com/seamys/luci-app-https-gateway/issues)
---
## โจ Features
| Feature | Description |
|---------|-------------|
| ๐ **Multi-domain** | Add domains freely, each with an automatically issued TLS certificate |
| ๐ **Wildcard certs** | `*.example.com` โ one certificate covers all subdomains |
| ๐ **Reverse proxy** | Proxy any HTTP service on LAN or public networks |
| โก **WebSocket** | One-click Upgrade header injection for real-time apps |
| ๐งญ **Auto DNS** | Automatically add domain โ router IP resolution in dnsmasq |
| ๐ **Auto renewal** | Based on acme.sh, 90-day certificates auto-renew |
| ๐จ **LuCI native** | Three-page UI: status overview, certificate management, proxy rules |
| ๐ **i18n** | English + Chinese Simplified, easily extensible |
## ๐ Requirements
| Requirement | Details |
|-------------|---------|
| Platform | OpenWrt 25.x (APK package manager) |
| Domain | A registered domain name |
| DNS API | Provider API credentials (Alibaba Cloud, Cloudflare, DNSPod, or GoDaddy) |
## ๐ฆ Dependencies
Auto-installed:
## ๐๏ธ Project Structure
```
โโโ Makefile OpenWrt SDK build definition
โโโ src/
โ โโโ view/ LuCI JS frontend views (i18n via _())
โ โโโ bin/ Main service script โ /usr/sbin/https-gateway
โ โโโ rpcd/ RPC backend โ /usr/libexec/rpcd/https-gateway
โ โโโ config/ UCI default config โ /etc/config/https_gateway
โ โโโ init/ procd init โ /etc/init.d/https_gateway
โ โโโ uci-defaults/ First-boot script โ /etc/uci-defaults/
โ โโโ share/ LuCI menu + ACL JSON
โ โโโ i18n/ Translation files (POT + PO)
โ โโโ templates/ POT template (source strings)
โ โโโ zh_Hans/ Chinese Simplified translation
โโโ docs/ Documentation
โโโ tests/ Unit & integration tests (149 tests)
```
## ๐ Installation
### Pre-built Package (Recommended)
Download the `.ipk` matching your router's architecture from the [Releases](https://github.com/seamys/luci-app-https-gateway/releases) page:
| Architecture | Target Devices |
|--------------|----------------|
| `x86_64` | Virtual machines, PC routers |
| `aarch64_cortex-a53` | MediaTek MT7981/7986 (Filogic) |
| `aarch64_generic` | Rockchip ARM64 boards |
| `arm_cortex-a7_neon-vfpv4` | Allwinner sunxi |
```sh
# Transfer to router
scp luci-app-https-gateway_*_x86_64.ipk root@192.168.0.1:/tmp/
# Install (OpenWrt 23.x with opkg)
ssh root@192.168.0.1 'opkg install /tmp/luci-app-https-gateway_*.ipk'
# Or OpenWrt 25.x with APK
ssh root@192.168.0.1 'apk add --allow-untrusted /tmp/luci-app-https-gateway_*.ipk'
```
### Manual Deployment (Development/Debug)
```sh
ROUTER=root@192.168.0.1
scp src/bin/https-gateway ${ROUTER}:/usr/sbin/
scp src/rpcd/https-gateway ${ROUTER}:/usr/libexec/rpcd/
scp src/config/https_gateway ${ROUTER}:/etc/config/
scp src/init/https_gateway ${ROUTER}:/etc/init.d/
scp src/uci-defaults/50-luci-https-gateway ${ROUTER}:/etc/uci-defaults/
scp src/share/menu.d/luci-app-https-gateway.json ${ROUTER}:/usr/share/luci/menu.d/
scp src/share/acl.d/luci-app-https-gateway.json ${ROUTER}:/usr/share/rpcd/acl.d/
ssh ${ROUTER} 'mkdir -p /www/luci-static/resources/view/https-gateway'
scp src/view/*.js ${ROUTER}:/www/luci-static/resources/view/https-gateway/
ssh ${ROUTER} 'chmod +x /usr/sbin/https-gateway /usr/libexec/rpcd/https-gateway /etc/init.d/https_gateway'
ssh ${ROUTER} '/etc/init.d/rpcd restart && /etc/init.d/https_gateway enable'
```
### ImageBuilder Built-in
```sh
cp src/bin/https-gateway files/usr/sbin/
cp src/rpcd/https-gateway files/usr/libexec/rpcd/
cp src/config/https_gateway files/etc/config/
cp src/init/https_gateway files/etc/init.d/
cp src/uci-defaults/50-luci-https-gateway files/etc/uci-defaults/
cp src/share/menu.d/*.json files/usr/share/luci/menu.d/
cp src/share/acl.d/*.json files/usr/share/rpcd/acl.d/
mkdir -p files/www/luci-static/resources/view/https-gateway
cp src/view/*.js files/www/luci-static/resources/view/https-gateway/
```
### APK/opkg Package Install (After SDK Build)
```sh
# opkg (OpenWrt 23.x)
opkg install luci-app-https-gateway_1.0.1-1_all.ipk
# APK (OpenWrt 25.x)
apk add --allow-untrusted luci-app-https-gateway_1.0.1-1_all.apk
```
## โก Quick Configuration
1. Navigate to **LuCI โ Services โ HTTPS Gateway**
2. Enter email, select DNS provider, fill in API credentials
3. Add a certificate (e.g. `*.example.com`)
4. Add proxy rules (domain + path + upstream address)
5. Enable gateway โ **Save & Apply**
6. Click **"Issue/Renew Certificates"**
> ๐ก **Tip**: Start with staging mode enabled to test your setup without hitting Let's Encrypt rate limits.
## ๐งช Testing
Run the full test suite (no router required):
```sh
sh tests/run_all.sh
```
| Suite | Tests | Coverage |
|-------|-------|----------|
| `test_validation.sh` | 47 | Domain, location, upstream regex validation |
| `test_nginx_conf.sh` | 37 | nginx config generation, TLS, WebSocket |
| `test_dns_certs.sh` | 25 | Certificate paths, wildcard matching, DNS sync |
| `test_integration.sh` | 25 | JSON output, UCI validation, service states |
| `test_validate.sh` | 15 | Legacy regex smoke tests |
## ๐ Internationalization
The UI uses OpenWrt's standard PO/LMO i18n system:
- Source strings in English with `_()` markers in JS views
- Translations in `src/i18n//https-gateway.po`
- Build produces `.lmo` binary files for LuCI runtime
**Available languages**: English (base), ไธญๆ็ฎไฝ (zh_Hans)
To add a new language, copy `src/i18n/templates/https-gateway.pot` to `src/i18n//https-gateway.po` and translate the `msgstr` entries.
## ๐ Release
To create a new release:
```sh
# Bump version in Makefile, then:
git tag v1.1.0
git push origin v1.1.0
```
GitHub Actions will automatically:
1. Download the OpenWrt SDK for each supported architecture
2. Compile `.ipk` packages (x86_64, aarch64, arm)
3. Create a source tarball for manual SDK builds
4. Publish a GitHub Release with all assets attached
### Supported architectures
| Arch | SDK Target | Typical Devices |
|------|-----------|-----------------|
| x86_64 | x86/64 | VMs, soft routers |
| aarch64_cortex-a53 | mediatek/filogic | GL.iNet MT3000, Xiaomi AX series |
| aarch64_generic | rockchip/armv8 | NanoPi R4S/R5S, FriendlyElec |
| arm_cortex-a7 | sunxi/cortexa7 | Orange Pi, Banana Pi |
## ๐ค Contributing
1. Fork the repository
2. Create a feature branch (`git checkout -b feat/amazing-feature`)
3. Run tests (`sh tests/run_all.sh`)
4. Commit your changes (`git commit -m 'feat: add amazing feature'`)
5. Push to the branch (`git push origin feat/amazing-feature`)
6. Open a Pull Request
## ๐ License
This project is licensed under the MIT License โ see the [LICENSE](LICENSE) file for details.
---
**If this project helps you, consider giving it a โญ**