feat: update README with portal-tunnel usage instructions
YoonHyunWoo committed
Nov 16, 2025 at 13:25 UTC
73dfb12b681b63ab35fde9671f09235e38d175e8
3 files changed
+18
-99
README.md
+18
@@ -61,6 +61,24 @@ See [portal-toys](https://github.com/gosuda/portal-toys)
61
62
For a detailed overview of system components and data flow, see the [architecture documentation](docs/architecture.md).
63
64
+## Portal-tunnel
65
+
66
+portal-tunnel is a tunneling tool that connects a locally running service to a relay server, allowing external access.
67
+
68
+1. **Run with a config file** (Check the [example](cmd/portal-tunnel/config.yaml.example) for configuration details)
69
+
70
+```bash
71
+bin/portal-tunnel expose --config config.yaml
72
+```
73
+
74
+2. **Expose a single service directly**
75
+
76
+```bash
77
+bin/portal-tunnel expose --relay <url> --host localhost --port 8080 --name <service>
78
+```
79
+
80
+
81
+
82
## Glossary
83
84
If you need Portal-specific terminology, check the [Portal glossary](docs/glossary.md)
cmd/portal-tunnel/README.md
deleted
-98
@@ -1,98 +0,0 @@
1
-# portal-tunnel User Guide
2
-
3
-`portal-tunnel` is a tunneling tool that registers locally running services to a Portal relay server, allowing external access through the `/peer/<service-name>` path. A single process can manage multiple relays and multiple services simultaneously.
4
-
5
-## Requirements
6
-
7
-* Go 1.25 or later
8
-* Portal relay server URL (e.g., `wss://portal.gosuda.org/relay`)
9
-* Local TCP-based services to expose through the relay (e.g., HTTP, gRPC)
10
-
11
-## Running the Tool
12
-
13
-### Build the binary
14
-
15
-```bash
16
-go build -o bin/portal-tunnel ./cmd/portal-tunnel
17
-bin/portal-tunnel expose --help
18
-```
19
-
20
-### Run with `go run`
21
-
22
-```bash
23
-go run ./cmd/portal-tunnel expose \
24
- --relay ws://localhost:4017/relay \
25
- --host localhost \
26
- --port 4018
27
-```
28
-
29
-## Using a Configuration File
30
-
31
-1. Copy the example configuration:
32
-
33
- ```bash
34
- cp cmd/portal-tunnel/config.yaml.example portal-tunnel.yaml
35
- ```
36
-
37
-2. Update relay and service definitions in `portal-tunnel.yaml`.
38
-
39
-3. Start the tunnel:
40
-
41
- ```bash
42
- bin/portal-tunnel expose --config portal-tunnel.yaml
43
- ```
44
-
45
-4. To run only a specific service, add the `--service <name>` flag.
46
-
47
-### config.yaml Fields
48
-
49
-```yaml
50
-relays:
51
- - name: gosuda
52
- urls:
53
- - wss://portal.gosuda.org.kr/relay
54
-
55
-services:
56
- - name: my-api
57
- relayPreference: # Relays are attempted in the listed order.
58
- - gosuda
59
- target: localhost:8080 # Local proxy target (host:port)
60
- protocols: # Optional; defaults to ["http/1.1"]
61
- - http/1.1
62
- - h2
63
-```
64
-
65
-* `relays`: List of relay servers. Each entry must include `name` and one or more `urls`.
66
-* `services`: List of local services to expose.
67
-
68
- * `name`: Service name to register with the relay. If omitted, a name is generated as `tunnel-<lease-id>`.
69
- * `relayPreference`: Ordered list of relay names. Unknown names are ignored; at least one valid URL must remain.
70
- * `target`: Local proxy target (`host:port`).
71
- * `protocols`: ALPN protocol list. Defaults to `http/1.1` if omitted.
72
-
73
-The process gracefully shuts down all tunnels when it receives `SIGINT` or `SIGTERM`.
74
-
75
-## Running a Single Service with Flags
76
-
77
-You can expose a single temporary service without a configuration file.
78
-
79
-```bash
80
-bin/portal-tunnel expose \
81
- --relay wss://portal.gosuda.org.kr/relay \
82
- --host localhost \
83
- --port 8080 \
84
- --name dev-api
85
-```
86
-
87
-* `--relay`: Required. WebSocket URL of the relay server.
88
-* `--host`, `--port`: Local service address to proxy. Defaults to `localhost:4018`.
89
-* `--name`: Public service name. Auto-generated if omitted.
90
-
91
-## Verifying Access
92
-
93
-When the tunnel is established, the log prints the accessible URL.
94
-
95
-* Access via `/peer/<service-name>` or `/peer/<lease-id>`.
96
-* Example: `http://portal.gosuda.org.kr/peer/dev-api`
97
-
98
-Relay logs show connection events (`->`) and disconnect events (`<-`), allowing real-time monitoring.
cmd/portal-tunnel/main.go
-1
@@ -265,7 +265,6 @@ func runServiceTunnel(ctx context.Context, relayDir *RelayDirectory, service *Se
265
266
client, err := sdk.NewClient(func(c *sdk.RDClientConfig) {
267
c.BootstrapServers = bootstrapServers
268
-
268
})
269
if err != nil {
270
return fmt.Errorf("service %s: failed to connect to relay: %w", serviceName, err)