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 的兼容性最好）。
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-22.04` | Linux x86_64、Android 构建 | Linux 主机 Docker 模式 |
| `ubuntu-22.04-arm` | Linux arm64、Android arm 构建 | 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 模式 |

**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-22.04:docker://ghcr.io/catthehacker/ubuntu:act-22.04"`，再重启容器。
工作流把 vcpkg 二进制缓存放在容器内 `/opt/vcpkg-cache`，如需跨任务复用，可在
job 容器配置中把该路径挂为持久卷。

**Windows（host 模式）**：在准备好构建环境的 Windows 机器上
（Git、PowerShell、Visual Studio 2022、vcpkg 位于 `C:\vcpkg`，并预创建
`D:\vcpkg-cache`；ImageMagick 等由工作流自动安装）：

```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 命令行工具），同样下载 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 在同一内网，留空直连即可。

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