Skip to content

Commit 99c28cb

Browse files
committed
docs(#69): two-port + autocert TLS quickstart, drop nginx from default path
- quickstart \u00a75: replace 'nginx in front terminating TLS' with the built-in two-port + --public-tls-domain autocert flow; keep the 'already running nginx' case as a tip. - cli.md: document --admin-listen / --public-listen / --public-tls-domain / --acme-http-listen / --acme-directory-url; mark --listen deprecated. - architecture.md: TLS terminated in-process, no reverse proxy needed by default. Docs site builds clean (vitepress); auto-deploys to curio-core-docs.pages.dev.
1 parent bcfba33 commit 99c28cb

3 files changed

Lines changed: 47 additions & 10 deletions

File tree

docs/concepts/architecture.md

Lines changed: 5 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -57,7 +57,11 @@ Everything inside the box is in one process. The only external dependencies are:
5757

5858
- the Filecoin chain itself (via Lantern's libp2p peers + the FEVM bridge upstream)
5959
- the local filesystem (state DB + piece bytes)
60-
- (optionally) an nginx reverse proxy in front for TLS + path filtering
60+
61+
TLS is terminated in-process via baked-in `autocert` (the two-port model, see
62+
[Quickstart §5](/getting-started/quickstart)), so no nginx / reverse proxy is needed in
63+
the default deploy. Operators who already run nginx for other services can still front a
64+
plaintext `--public-listen` loopback port if they prefer.
6165

6266
## Key seams
6367

docs/getting-started/quickstart.md

Lines changed: 36 additions & 8 deletions
Original file line numberDiff line numberDiff line change
@@ -74,14 +74,42 @@ You should see:
7474

7575
## 5. (Optional) Wire to a public hostname
7676

77-
If you want this SP to receive client traffic, you need:
78-
79-
1. A public DNS name (`sp.example.com`) pointing at the box.
80-
2. nginx in front terminating TLS, proxying to `127.0.0.1:14994`. Important: forward
81-
only `/pdp/*`, `/piece/*`, and `/.well-known/*` to the public side. **Never** expose
82-
`/admin/*` or `/`/dashboard paths.
83-
3. The service registered on the Filecoin **Service Registry** so clients can discover
84-
you (see [Operate → Registration](/operating/dashboard)).
77+
curio-core terminates TLS itself — **no nginx required**. It runs a two-port model:
78+
79+
- **Admin port** (`--admin-listen`, default `127.0.0.1:14994`): dashboard, `/setup`,
80+
`/admin/*`. Loopback-only; never exposed publicly.
81+
- **Public port** (`--public-listen`): `/pdp/*` + `/piece/*`. Gets a LetsEncrypt cert
82+
automatically via baked-in [`autocert`](https://pkg.go.dev/golang.org/x/crypto/acme/autocert).
83+
84+
To receive client traffic:
85+
86+
1. Point a public DNS name (`sp.example.com`) at the box.
87+
2. Open ports **80** (ACME HTTP-01 challenge) and **443** (HTTPS).
88+
3. Start with the public surface enabled:
89+
90+
```bash
91+
curio-core run \
92+
--data-dir /var/lib/curio-core \
93+
--network calibration \
94+
--admin-listen 127.0.0.1:14994 \
95+
--public-listen 0.0.0.0:443 \
96+
--public-tls-domain sp.example.com
97+
```
98+
99+
On first boot curio-core provisions a cert from LetsEncrypt and serves valid TLS within
100+
~30s. The cert + ACME account state persist in the `autocert_cache` SQLite table, so
101+
restarts never trigger a fresh ACME round-trip. The `/admin/*` and dashboard surfaces
102+
stay on the loopback admin port and are never reachable from the public internet.
103+
104+
4. Register the service on the Filecoin **Service Registry** so clients can discover you
105+
(see [Operate → Registration](/operating/dashboard)).
106+
107+
::: tip Already running nginx for other services?
108+
Point the public surface at a loopback port and proxy to it:
109+
`--public-listen 127.0.0.1:14995` (plaintext, no `--public-tls-domain`), then terminate
110+
TLS in your existing nginx and forward only `/pdp/*` + `/piece/*`. Never proxy `/admin/*`
111+
or `/`.
112+
:::
85113

86114
## What's next
87115

docs/reference/cli.md

Lines changed: 6 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -20,7 +20,12 @@ Flags:
2020
|---|---|---|
2121
| `--data-dir` | `~/.curio-core` | Persistent state directory (SQLite + Lantern + stash) |
2222
| `--network` | (from build) | `calibration` or `mainnet` |
23-
| `--listen` | `127.0.0.1:14994` | HTTP listen address |
23+
| `--listen` | `127.0.0.1:14994` | Deprecated alias for `--admin-listen` |
24+
| `--admin-listen` | (falls back to `--listen`) | Loopback admin/UI surface: dashboard, `/setup`, `/admin/*` |
25+
| `--public-listen` | (empty = single-port) | Public surface: `/pdp/*` + `/piece/*`. Empty keeps everything on the admin port |
26+
| `--public-tls-domain` | (empty) | Domain for baked-in `autocert` TLS on the public port. Empty serves plaintext (dev) and refuses `:443` |
27+
| `--acme-http-listen` | `:80` | ACME HTTP-01 challenge + HTTP→HTTPS redirect bind (only with `--public-tls-domain`) |
28+
| `--acme-directory-url` | (empty) | Override ACME directory (LetsEncrypt staging / tests) |
2429
| `--vm-bridge-rpc` | per-network default | Upstream Filecoin RPC for FEVM operations |
2530
| `--vm-bridge-rpc-disable` | false | Disable the FEVM bridge entirely (offline-only mode) |
2631
| `--engine-cpu` | 4 | harmonytask CPU budget |

0 commit comments

Comments
 (0)