rustdesk-server/README.md

# rustdesk-server

## Decommissioned — 2026-07-27

**Status: DECOMMISSIONED.** The `rustdesk-server` stack (account 328440206208, us-east-1) was deployed 2026-06-28 and fully torn down on 2026-07-27.

What was destroyed:

- CloudFormation stack `rustdesk-server` deleted: EC2 instance `i-02d98e3476ff82213`, Elastic IP `100.27.82.124` (released — **permanently unrecoverable**), security group, launch template, IAM roles `rustdesk-server-instance` and `rustdesk-server-dlm`, the DLM snapshot policy, and Route 53 records `rustdesk.seahaven.com` / `rustdesk-admin.int.seahaven.com`.
- Orphaned data volumes `vol-0e5a1a57612c2706e` and `vol-0fee83b3e96f3fcc9` deleted with **no final snapshot taken** — an explicit owner decision accepting total loss of the server key pair and the RustDesk connection database. **No backups exist.**
- Secrets `rustdesk/server-key-pair` and `rustdesk/pro-license` force-deleted with no recovery window. SSM parameters `/rustdesk-server/relay-host` and `/rustdesk-server/public-key` deleted. OIDC deploy role `githubdeploy-rustdesk-server` and the repo secret `AWS_DEPLOY_ROLE_ARN` deleted.
- Any RustDesk client still pointed at `rustdesk.seahaven.com` is permanently dead — the Elastic IP was released and will not come back.

This repository is archived and kept for historical reference only. Everything below this section documents the system as it existed while deployed; it does not describe anything currently running, and should not be used to attempt a redeploy without re-provisioning secrets, key material, and DNS from scratch.

---

[![CI](https://github.com/Sea-Haven-Industries/rustdesk-server/actions/workflows/ci.yaml/badge.svg)](https://github.com/Sea-Haven-Industries/rustdesk-server/actions/workflows/ci.yaml)
[![Dependency Review](https://github.com/Sea-Haven-Industries/rustdesk-server/actions/workflows/dependency-review.yml/badge.svg)](https://github.com/Sea-Haven-Industries/rustdesk-server/actions/workflows/dependency-review.yml)
![TypeScript](https://img.shields.io/badge/TypeScript-3178C6?logo=typescript&logoColor=white)
![AWS CDK](https://img.shields.io/badge/AWS%20CDK-2.261.0-FF9900?logo=amazonaws&logoColor=white)

Self-hosted [RustDesk Server Pro](https://rustdesk.com/docs/en/self-host/) (remote-desktop relay + rendezvous) for Sea Haven Industries, deployed to AWS via CDK.

> Status: deployed 2026-06-28, decommissioned 2026-07-27. See the decommission notice above.

## Architecture

A single ARM64 EC2 instance runs RustDesk Server Pro (`hbbs` rendezvous/ID + `hbbr` relay) in Docker. Clients connect from anywhere over the public internet to a stable Elastic IP fronted by `rustdesk.seahaven.com`.

```
RustDesk clients (anywhere)
        │  TCP 21114-21119 / UDP 21116
        ▼
   Elastic IP ──► EC2 t4g.small (AL2023 arm64, SSM-managed)
                    │  Docker: hbbs + hbbr (network_mode: host)
                    ├─ /dev/xvda  20 GiB root (OS only, ephemeral)
                    └─ /var/lib/rustdesk ◄── standalone EBS 20 GiB (RETAIN)
                                              key pair + sled DB
   Nightly DLM snapshots (retain 30, tag rustdesk-backup=true)
```

All durable state (the `id_ed25519` server key pair and the sled database) lives on a **standalone, RETAINed** EBS data volume, never an inline block device, so it survives instance replacement and stack deletion. See [RUNBOOK.md](RUNBOOK.md).

## CDK app

This repository is an AWS CDK v2 app written in TypeScript. It defines a single `rustdesk-server` CloudFormation stack — everything under [Resources](#resources) is declared as infrastructure-as-code here rather than provisioned by hand.

| Path | Role |
|---|---|
| `cdk.json` | CDK app manifest. Its `app` command (`npx tsx bin/app.ts`) tells the CDK CLI how to synthesize the app — `tsx` executes the TypeScript entry point directly, with no separate compile step. Also holds the `watch` globs for `cdk watch` and the CDK feature-flag `context`. |
| `bin/app.ts` | App entry point. Instantiates one `RustdeskServerStack` with an explicit `stackName: "rustdesk-server"` (kebab-case, matching the repo) pinned to account `328440206208` / `us-east-1`. |
| `lib/rustdesk-server-stack.ts` | The stack definition — EC2 instance, standalone EBS data volume, Elastic IP, security group, IAM role, DLM policy, and Route 53 records. Deploy-time tunables (pinned image tag, VPC/subnet IDs, the `RUSTDESK_PORTS` map) are constants at the top of the file. |
| `cdk.context.json` | Cached context lookups (VPC / subnet / AZ metadata) written by the CDK CLI; committed so synth is deterministic. |
| `tsconfig.json`, `package.json` | TypeScript config and dependencies. `aws-cdk-lib` is pinned to an exact version and kept current by Dependabot; `npm run synth` / `diff` / `deploy` wrap the CDK CLI. |

Synthesized CloudFormation templates land in `cdk.out/` (git-ignored). See [Deployment](#deployment) for the synth/deploy commands.

## Documentation

The canonical map of Sea Haven's AWS infrastructure lives in Confluence. This project's `rustdesk-server` stack is represented there as a Mermaid subgraph.

- **[AWS Architecture Map](https://seahaven.atlassian.net/wiki/spaces/IT/pages/1540098)** (Confluence, IT space, page 1540098)

## Ports

| Port | Proto | Purpose | Exposure |
|---|---|---|---|
| 21114 | TCP | Pro web console / API | **VPN/VPC only** (10.10.0.0/16, 10.20.0.0/16) |
| 21115 | TCP | hbbs NAT type test | public |
| 21116 | TCP + UDP | hbbs registration / hole punch / heartbeat | public |
| 21117 | TCP | hbbr relay | public |
| 21118 | TCP | hbbs web client (websocket) | public |
| 21119 | TCP | hbbr web client (websocket) | public |

Relay/rendezvous ports are public so clients connect from anywhere. The Pro admin console (21114) is restricted to the office VPN + VPC, so you administer the server and activate the Pro license over VPN. To take the relay VPN-only later, flip the `public` flags in `RUSTDESK_PORTS` in the stack.

## Resources

- **EC2** `rustdesk-server` — AL2023 arm64, `t4g.small`, SSM-managed (no inbound SSH)
- **EBS data volume** `rustdesk-data` — 20 GiB GP3, encrypted, `RemovalPolicy.RETAIN`, attached at `/dev/xvdf`
- **Elastic IP** — stable public address, associated to the instance
- **Security group** `rustdesk-server` — RustDesk ports above
- **IAM role** `rustdesk-server-instance` — `AmazonSSMManagedInstanceCore` + `secretsmanager:GetSecretValue` on `rustdesk/*`
- **DLM** `rustdesk-server-dlm` — nightly instance snapshots, retain 30
- **Route 53** A record `rustdesk.seahaven.com` → EIP

## Configuration

### Secrets (Secrets Manager) — created out of band

| Secret | Contents |
|---|---|
| `rustdesk/server-key-pair` | `id_ed25519` private + `.pub` public key generated by `hbbs` on first boot (mirror up post-deploy so a replacement host keeps the same key) |
| `rustdesk/pro-license` | RustDesk Server Pro license key |

### SSM parameters (non-secret)

| Parameter | Purpose |
|---|---|
| `/rustdesk-server/relay-host` | Public hostname clients use (`rustdesk.seahaven.com`) |

The pinned Docker image tag lives in `lib/rustdesk-server-stack.ts` (`RUSTDESK_IMAGE_TAG`).

## Deployment

CI/CD runs through the reusable org workflows (`ci-typescript-cdk.yaml`, `cd-cdk.yaml`). Pushes to `main` deploy automatically.

```bash
npm ci
npx cdk diff
npx cdk deploy
```

## First deploy

1. Confirm a **public** subnet ID in `us-east-1a` and set `PUBLIC_SUBNET_ID` in `lib/rustdesk-server-stack.ts` (replace `subnet-REPLACE_ME`).
2. Verify/pin `RUSTDESK_IMAGE_TAG`.
3. Create the OIDC deploy role `githubdeploy-rustdesk-server` and the repo secret `AWS_DEPLOY_ROLE_ARN`.
4. `cdk deploy` (or push to `main`). The instance boots, pulls the images, and `hbbs` generates the key pair on the empty data volume.
5. SSM in, read `/var/lib/rustdesk/id_ed25519{,.pub}`, store into `rustdesk/server-key-pair`.
6. Over the office VPN, open `http://rustdesk.seahaven.com:21114`, activate the Pro license, create users (the console is not reachable off-VPN).
7. Point a test client at `rustdesk.seahaven.com` + the public key; confirm a session relays.

## Operations

See [RUNBOOK.md](RUNBOOK.md) for key rotation, restore-from-snapshot, and instance replacement.