rdgen/setup.md

## Host the rdgen server with docker

1. First you will need to fork this repo on github
2. Next, setup a A Github fine-grained access token with permissions for your rdgen
   repository:
    * login to your github account  
    * click on your profile picture at the top right, click Settings  
    * at the bottom of the left panel, click Developer Settings  
    * click Personal access tokens  
    * click Fine-grained tokens  
    * click Generate new token  
    * give a token name, change expiration to whatever you want  
    * under Repository access, select Only select repositories, then pick your
      rdgen repo  
    * give Read and Write access to actions and workflows  
    * You might have to go to: https://github.com/USERNAME/rdgen/actions and hit green Enable Actions button so it works.
3. Next, login to your Github account, go to your rdgen repo page (https://github.com/USERNAME/rdgen)
   * Click on Settings
   * In the left pane, click on Secrets and variables, then click Actions
   * Now click New repository secret
   * Set the Name to GENURL
   * Set the Secret to https://rdgen.hostname.com (or whatever your server will be accessed from)
   * Now click New repository secret again
   * Set the Name to ZIP_PASSWORD
   * Set the Secret to any password you want (use this in the next step as well) - generate a password by running: ```python3 -c 'import secrets; print(secrets.token_hex(100))'```
4. Now download the docker-compose.yml file and fill in the environment variables:
  * SECRET_KEY="your secret key" - generate a secret key by running: ```python3 -c 'import secrets; print(secrets.token_hex(100))'```
  * GHUSER="your github username"  
  * GHBEARER="your fine-grained access token"  
  * ZIP_PASSWORD="the same password that you entered as a github secret"
  * PROTOCOL="https" *optional - defaults to "https", change to "http" if you need to
  * REPONAME="rdgen" *optional - defaults to "rdgen", change this if you renamed the repo when you forked it
5. Now just run ```docker compose up -d```


## Use a self hosted github runner for faster client generation (Windows only right now)

1. First you need to set up a Windows computer that can build rustdesk
2. Once you can build rustdesk, follow github instructions for setting up a self hosted github runner
3. Now you need to add an environment variable SH_SECRET, which has a key/password that you will need to send to the server
4. Save a json configuration file from your rdgen web ui
5. Use the [rdgen-cli] (https://github.com/AlekseyLapunov/rdgen-cli) to submit your json configuration with the added key "sh_secret_field" with the value matching your SH_SECRET

## Use your own Windows code signing token

1. You will need a USB signing token plugged into a Windows computer
2. On the computer with the USB signing token, you need to make sure it is set up correctly to sign using signtool.exe
3. Run a small [signing api](https://github.com/bryangerlach/signing_api) server on the computer with the USB token connected. Follow the setup instructions for this server.
4. Now for your rdgen repo, add github secrets for 
   - SIGN_BASE_URL (the accesible over the internet URL for the signing api server)
   - SIGN_API_KEY (the api key you have set on your signing api server)


## Choose a build platform: GitHub Actions or Gitea Actions

The rdgen server itself only dispatches workflow runs and polls their status;
the actual builds run on a CI platform. Two platforms are supported and can be
switched at any time in the admin UI (or via `BUILD_PLATFORM=github|gitea`):

| | GitHub Actions (default) | Gitea Actions (self-hosted) |
| --- | --- | --- |
| Build machines | Provided by GitHub (Windows / macOS / Linux) | You register your own `act_runner` machines |
| Network from runner back to rdgen | rdgen must be reachable from the public internet | Same LAN/VPN is enough (fully intranet capable) |
| Setup effort | Fork + token + 2 secrets, ~5 minutes | Deploy Gitea + register runners for every OS you build |
| Windows / macOS | Included | Physical/virtual Windows machines and Apple Macs required |
| Workflow files | `.github/workflows/` | `.gitea/workflows/` (adapted copy shipped in this repo) |
| Requirements | Fine-grained PAT | Gitea **1.27+ recommended** (1.23 minimum for workflow dispatch), act_runner 2.0+ |

Switching platforms only affects newly submitted builds; historical runs stay on
the platform where they ran and their status/log links keep working. Gitee is not
supported (its pipeline uses a proprietary DSL and has no parameterized remote
trigger API).

## Configure build platform settings from the admin UI (alternative to env vars)

Build settings (platform selection, GHUSER, GHBEARER, GITEA_SERVER_URL,
GITEA_TOKEN, GENURL, ZIP_PASSWORD, REPONAME, GHBRANCH, PROTOCOL, SH_SECRET,
WEBHOOK_SECRET, proxies) can also be configured in the web UI after logging in
as an admin user:

**Dashboard → 构建平台配置 (`/dashboard/settings/github/`)**

* Pick the platform with the GitHub/Gitea radio cards; the form shows only the
  fields relevant to the selected platform.
* Values saved in the admin UI take precedence over environment variables.
* Environment variables keep working as a fallback (value source is shown next
  to each field: 后台配置 / 环境变量 / 默认值).
* Secrets are never displayed back; leave a secret field empty to keep the saved
  value, or tick the "clear" checkbox to fall back to the env var/default.
* The page includes a step-by-step setup guide and a "Test GitHub/Gitea
  connection" button (the test target follows the selected platform). You still
  must add the `GENURL` and `ZIP_PASSWORD` repository secrets on the platform
  itself.
* Version lists are always fetched from GitHub tags and fall back to built-in
  versions when unreachable, independent of the selected build platform.

## Gitea 部署附录（自建 Gitea Actions）

适用场景：内网环境、构建产物回传不经过公网、希望 Windows/macOS 构建机在本地。
Gitea Actions 的工作流语法与 API 与 GitHub Actions 高度兼容，本仓库已附带适配
副本 `.gitea/workflows/`（6 个构建工作流 + 3 个可复用工作流 + 1 个 composite
action）。

### 1. Gitea 服务器与仓库

1. 部署 Gitea **1.27 或更高版本**（最低 1.23；1.27 随附 act_runner 2.0，对
   artifact/cache 与第三方 action 的兼容性最好）。注意：列表页的一键「停止」依赖
   Gitea 1.28+ 的取消运行 API；1.27 及更早版本点击停止会给出运行页链接，需到
   Gitea 界面手动 Cancel。
2. 把本仓库整体推送到 Gitea（保留 `.gitea/` 目录与默认分支名，后台填写的
   GITEA_BRANCH 必须与实际分支一致）。
3. 进入仓库 **Settings**，勾选 **Enable Repository Actions**。
4. 在仓库 **Settings → Actions → Secrets** 添加与 GitHub 同名的 Secret：
   * `GENURL`：rdgen 平台地址（runner 能访问到即可，例如 `http://10.0.0.5:8000`）
   * `ZIP_PASSWORD`：必须与 rdgen 服务端「配置压缩包密码」完全一致
   * 可选：`ANDROID_SIGNING_KEY`、`MACOS_P12_BASE64`、`SIGN_BASE_URL`、`SIGN_API_KEY`
5. 生成一个 Gitea API 令牌（Settings → Applications → Generate New Token，
   需要对该仓库的 **Actions 读写**权限），填入 rdgen 后台「Gitea 访问令牌」。

### 2. 注册 act_runner 构建机

Gitea 不提供云构建机，每个需要构建的平台都要自行注册 runner。注册令牌在
仓库 **Settings → Actions → Runners** 创建。runner 的自定义标签必须与工作流
里的 `runs-on` 完全一致：

| 标签 | 用途 | 运行方式 |
| --- | --- | --- |
| `ubuntu-24.04` | Linux x86_64、Android（armv7/aarch64 走 NDK 交叉编译）、drm/appimage/flatpak x86_64 | Linux x86_64 主机 Docker 模式 |
| `ubuntu-24.04-arm` | Linux arm64 的 deb/flatpak 原生构建 | arm64 Linux 主机 Docker 模式（需另注册） |
| `windows-2022` | Windows x64/x86 构建 | Windows 主机 host 模式（真机/虚拟机，需另注册） |
| `macos-14` | macOS arm64 构建 | Apple Silicon Mac host 模式（需另注册） |
| `macos-15-intel` | macOS x64 构建 | Intel Mac host 模式（需另注册） |

另外大量轻量步骤（拉取加密配置、收尾回调、artifact 清理）运行在
`ubuntu-latest` 标签上——act_runner 默认自带的 `ubuntu-latest`/`docker`/`amd64`
标签即可承接，但必须确保有 runner 显式提供 `ubuntu-24.04` 标签，否则主构建会
一直处于 waiting。只注册一台 x86_64 Linux runner 时 Android 与 Linux x86_64
构建即可工作；arm64 Linux、Windows、macOS 必须各自再注册对应机器，对应任务在
机器就绪前会排队等待。

**Linux（Docker 模式，推荐）**：

```bash
docker run -d --name gitea-runner --restart always \
  -v /var/run/docker.sock:/var/run/docker.sock \
  -v /opt/act-runner:/data \
  -e GITEA_INSTANCE_URL=https://gitea.example.com \
  -e GITEA_REGISTRATION_TOKEN=xxxx \
  gitea/act_runner:latest
```

首次启动生成 `/data/config.yaml` 后，按需把 `labels` 改为上面的标签，例如
`- "ubuntu-24.04:docker://ghcr.io/catthehacker/ubuntu:act-24.04"`（act 官方
镜像还有 `ubuntu:act-latest` 可挂到 `ubuntu-latest` 标签），再重启容器。
工作流把 vcpkg 二进制缓存放在容器内 `/opt/vcpkg-cache`，如需跨任务复用，可在
job 容器配置中把该路径挂为持久卷。

> **坑：注册地址必须是作业容器也能访问的地址。** 若 Gitea 与 act_runner 用
> docker-compose 部署，千万不要用 `http://gitea:3000` 这类 compose 内部服务名
> 注册（act_runner 容器自身可达，但 act_runner v3+ 的作业容器默认 host 网络，
> 解析不了该名）。否则上传/下载 artifact 时报
> `Failed to CreateArtifact: ... ENOTFOUND`。`GITEA_INSTANCE_URL` 用公网地址
> （如 `https://gitea.example.com`）或宿主机映射地址（如 `http://10.0.0.10:39630`），
> 改完编辑 `/data/config.yaml` 的 `runner.address` 重启即可，无需重新注册。

**Windows（host 模式）**：在准备好构建环境的 Windows 机器上构建。Gitea act
在 Windows 上默认 shell 是 bash，而本仓库工作流已显式把默认 shell 设为
**PowerShell 7（pwsh）**，因此机器上必须安装：

* **PowerShell 7+**（`pwsh` 必须在 PATH 中；仅有 Windows 自带的 5.1 不够）
* **Git for Windows**（提供 Git Bash，部分步骤显式使用 `shell: bash`）
* **Python 3**（decrypt-secrets composite action 需要，且能 `python -m pip`）
* **Visual Studio 2022**（含 C++ 桌面开发、MSVC、Windows SDK）
* **vcpkg** 固定位于 `C:\vcpkg`，并**预创建 `D:\vcpkg-cache`** 二进制缓存目录
* **Chocolatey / NuGet**（工作流用其安装 ImageMagick、WiX 等构建依赖）

```powershell
# 下载 https://gitea.com/gitea/act_runner/releases 的 act_runner.exe
.\act_runner.exe register --instance https://gitea.example.com --token xxxx --labels "windows-2022:host"
.\act_runner.exe daemon
```

确认稳定后再用任务计划程序/NSSM 注册为开机服务。

**macOS（host 模式）**：使用 Apple 硬件（arm64 对应 `macos-14`，Intel 对应
`macos-15-intel`）。仅安装 Xcode 命令行工具不够，必须安装**完整版 Xcode**
（Flutter macOS 构建与代码签名需要），并具备 Homebrew、CocoaPods
（`sudo gem install cocoapods` 或 brew 版）、运行 runner 的用户可**免密
sudo**。同样下载 act_runner 二进制后以 `macos-14:host` 标签注册并 launchd
守护。

### 3. 内网网络说明

* 工作流中的第三方 action（`actions/checkout`、`subosito/flutter-action` 等）
  默认从 github.com 拉取。纯内网可在 Gitea 的 `app.ini` 配置 action 镜像：

  ```ini
  [actions]
  DEFAULT_ACTIONS_URL = https://gitea.com
  ```

  （`gitea.com` 官方镜像了主流 actions；也可搭建自有镜像。）
* 工作流仍会从 GitHub 拉取 RustDesk 源码、Flutter 引擎、cargo/pub 依赖等，
  runner 主机需要可访问 github.com（直连、出网白名单或代理）。
* `.gitea/workflows` 已把构建所需的 patch 改为从仓库内本地目录取用
  （`.rdgen-src/.github/patches/`），不依赖 raw.githubusercontent.com。
* rdgen 后台的 `GITEA_PROXY` 仅用于「服务端 → Gitea API」的调用；Gitea 通常
  与 rdgen 在同一内网，留空直连即可。
* **runner 必须能反向访问 rdgen（`GENURL`）**：每个工作流结束时（无论成功、
  失败还是取消）都会向 `${GENURL}/updategh` 回调最终状态。收不到回调的构建
  会在 6 小时后被服务端误判为超时，因此 `GENURL` 要填 runner 实际可达的地址，
  不能只填浏览器端能访问的地址。

### 4. 在 rdgen 侧启用

在 **后台管理 → 构建平台配置** 选择 Gitea，填写服务器地址、令牌、属主、仓库、
分支后保存，点击「测试 Gitea 连接」：连接正常即可在客户端定制页提交构建。
也可以用环境变量配置：`BUILD_PLATFORM=gitea`、`GITEA_SERVER_URL`、
`GITEA_TOKEN`、`GITEA_OWNER`、`GITEA_REPO`、`GITEA_BRANCH`、`GITEA_PROXY`。

## Host manually:

1. A Github account with a fork of this repo  
2. A Github fine-grained access token with permissions for your rdgen
   repository:
    * login to your github account  
    * click on your profile picture at the top right, click Settings  
    * at the bottom of the left panel, click Developer Settings  
    * click Personal access tokens  
    * click Fine-grained tokens  
    * click Generate new token  
    * give a token name, change expiration to whatever you want  
    * under Repository access, select Only select repositories, then pick your
      rdgen repo  
    * give Read and Write access to actions and workflows  
    * You might have to go to: https://github.com/USERNAME/rdgen/actions and hit green Enable Actions button so it works.
3. Setup environment variables/secrets:
    * environment variables on the server running rdgen:  
        * GHUSER="your github username"  
        * GHBEARER="your fine-grained access token"  
        * PROTOCOL="https" *optional - defaults to "https", change to "http" if you need to
        * REPONAME="rdgen" *optional - defaults to "rdgen", change this if you renamed the repo when you forked it
    * github secrets (setup on your github account for your rdgen repo):  
        * GENURL="example.com:8000"  *this is the domain and port that you are
          running rdgen on, needs to be accessible on the internet, depending
          on how you have this setup the port may not be needed  

```
# Open to the directory you want to install rdgen (change /opt to wherever you want)  
cd /opt

# Clone your rdgen repo, change bryangerlach to your github username
git clone https://github.com/bryangerlach/rdgen.git

# Open the rdgen directory
cd rdgen

# Setup a python virtual environment called rdgen
python -m venv .venv

# Activate the python virtual environment 
source .venv/bin/activate

# Install the python dependencies
pip install -r requirements.txt

# Setup the database
python manage.py migrate

# Run the server, change 8000 with whatever you want
python manage.py runserver 0.0.0.0:8000
```

open your web browser to yourdomain:8000

use nginx, caddy, traefik, etc. for ssl reverse proxy

### To autostart the server on boot, you can set up a systemd service called rdgen.service

replace user, group, and port if you need to  replace /opt with wherever you
have installed rdgen  save the following file as
/etc/systemd/system/rdgen.service, and make sure to change GHUSER, GHBEARER

```
[Unit]
Description=Rustdesk Client Generator
[Service]
Type=simple
LimitNOFILE=1000000
Environment="GHUSER=yourgithubusername"
Environment="GHBEARER=yourgithubtoken"
PassEnvironment=GHUSER GHBEARER
ExecStart=/opt/rdgen/.venv/bin/python3 /opt/rdgen/manage.py runserver 0.0.0.0:8000
WorkingDirectory=/opt/rdgen/
User=root
Group=root
Restart=always
StandardOutput=file:/var/log/rdgen.log
StandardError=file:/var/log/rdgen.error
# Restart service after 10 seconds if node service crashes
RestartSec=10
[Install]
WantedBy=multi-user.target
```

then run this to enable autostarting the service on boot, and then start it
manually this time:

```
sudo systemctl enable rdgen.service
sudo systemctl start rdgen.service
```
and to get the status of the server, run:
```
sudo systemctl status rdgen.service
```