add portal deploy guide
rabbitprincess committed
Dec 8, 2025 at 21:18 UTC
a60a1154030aa06d7bc7a29571c48e66a7e7026e
2 files changed
+42
-11
README.md
+2
-11
@@ -42,18 +42,10 @@ docker compose up
42
# 2. Open in browser
43
http://localhost:4017
44
45
-# 3. Domain setup (optional)
46
-# Point DNS to this server:
47
-# A record for portal.example.com → server IP
48
-# A (wildcard) for *.example.com (or *.portal.example.com) → server IP
49
-#
50
-# Then edit docker-compose.yml environment for your domain:
51
-PORTAL_URL: https://portal.example.com
52
-PORTAL_APP_URL: https://*.example.com
53
-BOOTSTRAP_URIS: wss://portal.example.com/relay
54
-
45
```
46
47
+For a public deployment guide (DNS, TLS, reverse proxy), see [docs/portal-deploy-guide.md](docs/portal-deploy-guide.md).
48
+
49
### Running a Portal App using Tunnel
50
51
```bash
@@ -61,7 +53,6 @@ BOOTSTRAP_URIS: wss://portal.example.com/relay
53
54
# 2. Run the tunnel client to expose
55
curl -fsSL http://localhost:4017/tunnel | PORT=3000 NAME=myapp sh
64
-
56
```
57
58
### Running a Portal App using the SDK
docs/portal-deploy-guide.md
new
+40
@@ -0,0 +1,40 @@
1
+# Portal Deploy Guide
2
+
3
+How to run a public Portal relay with DNS, TLS, and wildcard subdomains.
4
+
5
+Portal does NOT manage TLS, certificates, or DNS. You must place an HTTPS reverse proxy or TLS terminator in front of Portal.
6
+
7
+## Prerequisites
8
+- A public server (VPS / cloud VM / on-prem with port forwarding)
9
+- A domain you can manage
10
+- Ports 80 and 443 open to the Internet
11
+- DNS A/AAAA records pointing to your server:
12
+ - `yourdomain.com -> <server IP>`
13
+ - `*.yourdomain.com -> <server IP>`
14
+
15
+## TLS & Wildcard Certificates
16
+Portal requires a single wildcard TLS certificate for all app subdomains (`*.yourdomain.com`).
17
+
18
+- Wildcard certificates require DNS-01.
19
+ - HTTP-01/TLS-ALPN-01 will not work for `*.` names.
20
+- Use any ACME client that supports DNS-01 (reverse proxy or standalone).
21
+- You must provide DNS credentials so the ACME client can create TXT records at
22
+ - `_acme-challenge.yourdomain.com`.
23
+
24
+## Environment (docker compose)
25
+- Set these for public deployment (via `environment:`):
26
+ ```
27
+ PORTAL_PORT=4017
28
+ PORTAL_URL=https://yourdomain.com
29
+ PORTAL_APP_URL=https://*.yourdomain.com
30
+ BOOTSTRAP_URIS=wss://yourdomain.com/relay
31
+ ```
32
+
33
+## Deploy
34
+- Run Portal (e.g., `docker compose up -d`) exposing 4017 internally.
35
+- Place an HTTPS reverse proxy in front, terminate TLS with your wildcard cert, and route `yourdomain.com` / `*.yourdomain.com` to Portal on 4017.
36
+- Supply your DNS API credentials to the ACME client so DNS-01 can obtain/renew the wildcard cert.
37
+
38
+## Validate
39
+- Health: `curl -vk https://yourdomain.com/healthz` → `{"status":"ok"}`.
40
+- Tunnel script fetch: `curl -fsSL https://yourdomain.com/tunnel | head`.