fix deployment
Kim committed
Mar 3, 2026 at 15:24 UTC
ab3bc6b0e356697f08fa8bbf15f2aa4f06fc3f7d
1 file changed
+55
-50
docs/deployment.md
+55
-50
@@ -1,86 +1,91 @@
1
-# Portal Relay Deploy Guide
1
+# Portal Relay Deployment Guide
2
3
-## Prerequisites
3
+This guide covers production-style deployment of Portal Relay on a public domain.
4
+It includes DNS setup, environment configuration, startup, validation, and basic operations.
5
5
-- Public domain (example: `example.com`)
6
-- Public server with public IP
7
-- Docker, Docker Compose
6
+## 1. Prerequisites
7
9
-## Quick Start
8
+You need:
9
11
-### 1. Register Domain in Cloudflare
10
+- A public domain (example: `example.com`)
11
+- A public Linux server with a static public IP
12
+- Open inbound ports: `443/tcp`, `4017/tcp`
13
+- Docker and Docker Compose
14
+- Cloudflare-managed DNS zone for your domain (required for automatic ACME DNS-01 flow)
15
13
-In Cloudflare Dashboard:
14
-1. Go to `Websites`
15
-2. Click `Add a Site`
16
-3. Enter your domain (example: `example.com`)
17
-4. Select a plan and complete setup
18
-5. Update nameservers at your registrar to the nameservers provided by Cloudflare
19
-6. Confirm the zone status is `Active`
16
+## 2. DNS and Cloudflare Setup
17
21
-### 2. Register DNS Records
18
+### 2.1 Add Domain to Cloudflare
19
23
-In Cloudflare Dashboard:
24
-1. Open your domain dashboard (`example.com`)
25
-2. Go to `DNS` -> `Records`
26
-3. Click `Add record`
20
+1. Cloudflare Dashboard -> `Websites` -> `Add a Site`
21
+2. Enter your domain (`example.com`)
22
+3. Complete onboarding and apply Cloudflare nameservers at your registrar
23
+4. Wait until zone status is `Active`
24
28
-Create record 1 (root domain):
29
-- Type: `A`
30
-- Name: `@`
31
-- IPv4 address: `<server-ip>`
32
-- Proxy status: `DNS only`
33
-- Save
25
+### 2.2 Create DNS Records
26
35
-Create record 2 (wildcard subdomain):
36
-- Type: `A`
37
-- Name: `*`
38
-- IPv4 address: `<server-ip>`
39
-- Proxy status: `DNS only`
40
-- Save
27
+Cloudflare Dashboard -> `DNS` -> `Records`:
28
+
29
+- Record 1 (apex)
30
+ - Type: `A`
31
+ - Name: `@`
32
+ - Content: `<server-ip>`
33
+ - Proxy status: `DNS only`
34
+- Record 2 (wildcard)
35
+ - Type: `A`
36
+ - Name: `*`
37
+ - Content: `<server-ip>`
38
+ - Proxy status: `DNS only`
39
+
40
+Expected:
41
42
-Example result:
42
- `example.com -> <server-ip>`
43
- `*.example.com -> <server-ip>`
44
46
-### 3. Create Cloudflare API Token
45
+### 2.3 Create Cloudflare API Token
46
+
47
+Cloudflare Dashboard -> `My Profile` -> `API Tokens` -> `Create Token`.
48
+
49
+Grant:
50
48
-Create token in Cloudflare Dashboard:
49
-1. `My Profile` -> `API Tokens` -> `Create Token`
50
-2. Custom permissions:
51
- - `Zone:Read`
52
- - `DNS:Edit`
53
-3. Zone resources: include your target zone (`example.com`)
54
-4. Copy and save the token value (you will use it as `CLOUDFLARE_TOKEN`)
51
+- `Zone:Read`
52
+- `DNS:Edit`
53
56
-### 4. Run the Relay Server
54
+Scope:
55
58
-Create `.env` in repository root:
56
+- Zone resources limited to your target zone (for example, `example.com`)
57
+
58
+Save this token for `CLOUDFLARE_TOKEN`.
59
+
60
+## 3. Run Relay Server
61
+
62
+### 3-1. Create `.env` at repository root:
63
64
```bash
65
PORTAL_URL=https://example.com
62
-ADMIN_SECRET_KEY=your-admin-key
66
+BOOTSTRAP_URIS=https://example.com
67
SNI_PORT=443
68
+ADMIN_SECRET_KEY=your-admin-secret
69
KEYLESS_DIR=/etc/portal/keyless
70
CLOUDFLARE_TOKEN=cf_xxxxxxxxxxxxxxxxx
71
```
72
68
-Run Docker Compose
73
+### 3-2. Start Relay
74
75
```bash
71
-docker compose up -d
72
-docker compose logs -f
76
+docker compose up
77
```
78
75
-## Troubleshooting
79
+## 4. Troubleshooting
80
+
81
+### 4.1 Ports blocked
82
77
-### Inbound ports are blocked
83
+Required inbound:
84
79
-Required inbound ports:
85
- `443/tcp`
86
- `4017/tcp`
87
83
-Linux example (UFW):
88
+UFW example:
89
90
```bash
91
sudo ufw allow 443/tcp