@devries-cameron20 / t3code Mirror · read-only
Fork 0

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

Mirrored from https://github.com/Camo67/t3code.git

Synced Nov 21, 06:00 UTC

main
mdx 202 lines 5.53 KB
Raw
1 ---
2 title: Octane
3 description: Deploy an OctaneJS app to Hetzner with Hetzner.Website.Octane — SSR as a systemd unit on port 3000, client assets baked into the unit, and Octane's own Vite dev server under alchemy dev.
4 sidebar:
5 order: 14
6 ---
7
8 import PackageManagers from "../../../../components/PackageManagers.astro";
9
10 export const devDeps = "@alchemy.run/frontend-frameworks";
11
12 `Hetzner.Website.Octane` deploys an [OctaneJS](https://octanejs.dev)
13 fullstack app to a Hetzner Cloud Server. Octane wraps Vite, so the
14 resource is deliberately thin: it runs your project's own
15 `vite build` — Octane's plugin builds the client bundle and the
16 self-contained SSR server bundle, and the Node deploy target's
17 finishing pass wraps its fetch handler as a Node HTTP program. The
18 server runs as a systemd unit on port 3000 (`Hetzner.Service` on a
19 `Hetzner.Server`); client assets are baked into the unit. The live
20 URL is `http://{ipv4}:3000` — no TLS on the Service. No Dockerfile,
21 no build command to run.
22
23 ## Install
24
25 The build integration is not bundled with alchemy. Install
26 `@alchemy.run/frontend-frameworks`; the resource loads the package's
27 `/octane` and `/octane/node` exports from your project at deploy
28 time. It is only used at build time, so a dev dependency is enough:
29
30 <PackageManagers dev={devDeps} />
31
32 ## Configure Octane
33
34 Keep native compiler and route settings in `octane.config.ts`, without
35 an adapter:
36
37 ```typescript
38 // octane.config.ts
39 import { defineConfig, RenderRoute } from "@octanejs/vite-plugin";
40
41 export default defineConfig({
42 router: {
43 routes: [new RenderRoute({ path: "/", entry: ["App", "/src/App.tsx"] })],
44 },
45 });
46 ```
47
48 `Hetzner.Website.Octane` selects hosting and automatically wraps Octane's
49 default native Node output as an HTTP server. The legacy Node marker
50 adapter remains optional for existing projects.
51
52 Vite plugins like Tailwind go in `vite.config.ts` next to it,
53 alongside the Octane plugin:
54
55 ```typescript
56 // vite.config.ts
57 import { octane } from "@octanejs/vite-plugin";
58 import tailwindcss from "@tailwindcss/vite";
59 import { defineConfig } from "vite";
60
61 export default defineConfig({
62 plugins: [octane(), tailwindcss()],
63 });
64 ```
65
66 ## Declare the Website
67
68 Declare the site as a module-level const (rather than inline in the
69 Stack):
70
71 ```typescript
72 // alchemy.run.ts
73 import * as Hetzner from "@alchemy.run/hetzner";
74
75 export const Website = Hetzner.Website.Octane("Website");
76 ```
77
78 Omit `server` and Alchemy creates a `cpx12` / `ubuntu-24.04` Server
79 in `fsn1`. Pass an existing Server so several sites or APIs share
80 one VM:
81
82 ```typescript
83 export const Box = Hetzner.Server("Box", {
84 serverType: "cpx12",
85 image: "ubuntu-24.04",
86 location: "fsn1",
87 });
88
89 export const Website = Hetzner.Website.Octane("Website", {
90 server: Box,
91 });
92 ```
93
94 ## Add it to the Stack
95
96 Yield the site from your Stack and return its URL:
97
98 ```typescript
99 // alchemy.run.ts
100 import * as Alchemy from "alchemy";
101 import * as Effect from "effect/Effect";
102
103 export default Alchemy.Stack(
104 "MyOctaneSite",
105 {
106 providers: Hetzner.providers(),
107 state: Alchemy.localState(),
108 },
109 Effect.gen(function* () {
110 const site = yield* Website;
111 return { url: site.url };
112 }),
113 );
114 ```
115
116 On deploy, `url` is `http://{ipv4}:3000`. The resolved site also
117 exposes `server` and `service` (both `undefined` under
118 `alchemy dev`).
119
120 ## Add environment variables
121
122 Process environment is configured under `env` — plain strings, or
123 `Redacted` values. They are copied onto `process.env` before the
124 build and onto the systemd unit at deploy time:
125
126 ```diff lang="typescript"
127 // alchemy.run.ts
128 export const Website = Hetzner.Website.Octane("Website", {
129 + env: {
130 + GREETING: "Hello from alchemy",
131 + API_BASE: "https://api.example.com",
132 + },
133 });
134 ```
135
136 The same values are injected into the dev server's process
137 environment under `alchemy dev`, so server code reads them in both
138 modes.
139
140 ## Read the environment in server code
141
142 Octane's server runs in Node on the Server, so middleware and
143 `ServerRoute` handlers read the environment from `process.env`:
144
145 ```typescript
146 // octane.config.ts
147 new ServerRoute({
148 path: "/api/greeting",
149 methods: ["GET"],
150 handler: async () => {
151 return Response.json({ greeting: process.env.GREETING ?? "hello" });
152 },
153 });
154 ```
155
156 ## Asset routing
157
158 Octane's intended setup is asset-first with SSR on miss: exact files
159 in `dist/client` are served by the Node process without invoking the
160 Octane handler, and every miss streams from Octane SSR. That is the
161 default — there is nothing to configure. `GET /health` answers for
162 the unit health check.
163
164 ## Local dev
165
166 ```sh
167 bun alchemy dev
168 ```
169
170 `alchemy dev` runs Octane's own Vite dev server — the plugin's
171 in-process SSR middleware serves rendering, server routes, and RPC
172 with full HMR. `site.url` is the local address and no Hetzner
173 resources are created (`server` and `service` are `undefined`). Wrap
174 the site in `Alchemy.remote()` to deploy the real infrastructure even
175 during dev.
176
177 ## Custom domain
178
179 `domain` requires an existing Hetzner DNS `zone`. Alchemy creates an
180 A `RecordSet` pointing at the Server's public IPv4. There is no TLS
181 on the Service — `url` becomes `http://{domain}:3000`. Passing
182 `domain` without `zone` fails.
183
184 ```typescript
185 const zone = yield* Hetzner.Zone("Dns", {
186 name: "example.com",
187 });
188
189 const site = yield* Hetzner.Website.Octane("Web", {
190 domain: "app.example.com",
191 zone,
192 });
193 ```
194
195 See [Zones & records](/hetzner/networking/dns).
196
197 ## Where next
198
199 - [`Hetzner.Website.Octane` reference](/providers/hetzner/website/octane)
200 - [Servers](/hetzner/compute/servers) and
201 [Services](/hetzner/compute/services)
202 - [Zones & records](/hetzner/networking/dns)