The best way to control Claude Code, Codex and more from any computer or phone

main
mdx 189 lines 4.91 KB
Raw
1 ---
2 title: Vocs
3 description: Deploy a Vocs docs site to Hetzner with Hetzner.Website.Vocs — prerendered HTML on a systemd unit, extensionless routes, and Vocs' own dev server under alchemy dev.
4 sidebar:
5 order: 10
6 ---
7
8 import PackageManagers from "../../../../components/PackageManagers.astro";
9
10 export const devDeps = "@alchemy.run/frontend-frameworks";
11
12 `Hetzner.Website.Vocs` deploys a [Vocs](https://vocs.dev)
13 documentation project to a Hetzner Cloud
14 [Server](/hetzner/compute/servers) as a systemd
15 [Service](/hetzner/compute/services) on port 3000. Vocs prerenders
16 static HTML; unmatched paths serve extensionless pages (`/about` →
17 `about/index.html`). The live URL is `http://{ipv4}:3000` — there is
18 no TLS on the Service. Your `vocs.config.*` loads natively — there
19 is no adapter to install.
20
21 ## Install
22
23 The build integration is not bundled with alchemy. Install
24 `@alchemy.run/frontend-frameworks`; the resource loads
25 `/vocs/node` from your project at deploy time. It is only used at
26 build time, so a dev dependency is enough:
27
28 <PackageManagers dev={devDeps} />
29
30 Your Vocs project already needs `vocs` installed.
31
32 ## Configure Vocs
33
34 Your `vocs.config.*` file loads natively — title, sidebar, and any
35 other Vocs options work exactly as they do outside Alchemy:
36
37 ```typescript
38 // vocs.config.ts
39 import { defineConfig } from "vocs/config";
40
41 export default defineConfig({
42 title: "Docs",
43 sidebar: [
44 { text: "Home", link: "/" },
45 { text: "Guide", link: "/guide" },
46 ],
47 });
48 ```
49
50 If `vocs.config.*` sets `outDir`, pass the same value on the
51 resource (default `"dist"`) so generated output stays outside the
52 rebuild hash:
53
54 ```typescript
55 export const Website = Hetzner.Website.Vocs("Website", {
56 rootDir: "./docs",
57 outDir: "build",
58 });
59 ```
60
61 ## Declare the Website
62
63 Declare the site as a module-level const (rather than inline in the
64 Stack):
65
66 ```typescript
67 // alchemy.run.ts
68 import * as Hetzner from "@alchemy.run/hetzner";
69
70 export const Website = Hetzner.Website.Vocs("Website", {
71 rootDir: "./docs",
72 });
73 ```
74
75 Omit `server` to create a `cpx12` / `ubuntu-24.04` box in `fsn1`.
76 Pass an existing `Hetzner.Server` when several sites or APIs should
77 share one VM:
78
79 ```typescript
80 export const Box = Hetzner.Server("box", {
81 serverType: "cpx12",
82 image: "ubuntu-24.04",
83 location: "fsn1",
84 });
85
86 export const Website = Hetzner.Website.Vocs("Website", {
87 rootDir: "./docs",
88 server: Box,
89 });
90 ```
91
92 ## Add it to the Stack
93
94 Yield the site from your Stack and return its URL:
95
96 ```typescript
97 // alchemy.run.ts
98 import * as Alchemy from "alchemy";
99 import * as Effect from "effect/Effect";
100
101 export default Alchemy.Stack(
102 "MyVocsSite",
103 {
104 providers: Hetzner.providers(),
105 state: Alchemy.localState(),
106 },
107 Effect.gen(function* () {
108 const site = yield* Website;
109 return { url: site.url };
110 }),
111 );
112 ```
113
114 The live URL is `http://{ipv4}:3000`. The unit listens on port 3000
115 and answers `GET /health` (`deployUnit` curls that path whenever
116 `PORT` is set). `site.server` and `site.service` are set on deploy.
117
118 ## Add environment variables
119
120 Top-level `env` is copied onto `process.env` before build and
121 `alchemy dev`, and onto the systemd unit at deploy:
122
123 ```diff lang="typescript"
124 // alchemy.run.ts
125 export const Website = Hetzner.Website.Vocs("Website", {
126 rootDir: "./docs",
127 + env: {
128 + DOCS_TITLE: "Hello from Alchemy!",
129 + },
130 });
131 ```
132
133 These are process environment variables, not Worker bindings.
134
135 ## Read the environment
136
137 Vocs prerenders at build time, so page content that reads
138 `process.env` is baked into the HTML. The same values are set on
139 the hosted Node process; there is no request-time Vocs server.
140
141 ```typescript
142 const title = process.env.DOCS_TITLE ?? "Docs";
143 ```
144
145 ## Local development
146
147 `alchemy dev` runs Vocs' own dev server (native HMR) instead of
148 deploying; `site.url` is the local address and no Hetzner resources
149 are created (`server` and `service` are `undefined`). Wrap the site
150 in `Alchemy.remote()` to deploy the live Server and Service even
151 during dev:
152
153 ```typescript
154 export const Website = Hetzner.Website.Vocs("Website", {
155 rootDir: "./docs",
156 }).pipe(Alchemy.remote());
157 ```
158
159 ## Custom domain
160
161 `domain` requires an existing Hetzner DNS [Zone](/hetzner/networking/dns)
162 (`zone`). Alchemy creates an A [RecordSet](/hetzner/networking/dns)
163 pointing at the Server's public IPv4; `url` becomes
164 `http://{domain}:3000`. v1 does not provision a Zone — omitting
165 `zone` when `domain` is set fails:
166
167 ```typescript
168 export const Dns = Hetzner.Zone("dns", {
169 name: "example.com",
170 });
171
172 export const Website = Hetzner.Website.Vocs("Website", {
173 rootDir: "./docs",
174 domain: "docs.example.com",
175 zone: Dns,
176 });
177 ```
178
179 There is no TLS on the Service.
180
181 ## Where next
182
183 - [`Vocs` reference](/providers/hetzner/website/vocs) — every prop
184 and attribute
185 - [Servers](/hetzner/compute/servers) and
186 [Services](/hetzner/compute/services) — the VM and systemd unit
187 - [Zones & records](/hetzner/networking/dns) — the Zone `domain`
188 requires
189 - [Hetzner](/hetzner) — the Hetzner provider hub