sailfork / t3code-github / .repos/ alchemy-effect/ website/ src/ content/ docs/ hetzner/ compute/ services.mdx

A Service is your code on a Server: an Effect program that Alchemy bundles with Rolldown, copies over SSH, and runs under systemd with Restart=always. You never write a unit file, a Dockerfile, or a deploy script — and several Services can share one Server.

Declare a Service

A Service is a class with an infrastructure definition and a runtime implementation:

// src/api.ts
import * as Hetzner from "@alchemy.run/hetzner";
import * as Effect from "effect/Effect";
import * as HttpServerResponse from "effect/http/HttpServerResponse";
import { Box } from "./server.ts";

export default class Api extends Hetzner.Service<Api>()(
  "Api",
  { server: Box, main: import.meta.url, port: 3000 },
  Effect.gen(function* () {
    return {
      fetch: Effect.succeed(HttpServerResponse.text("hello")),
    };
  }),
) {}
  • server — the machine to run on (a Hetzner.Server, yielded or module-scope). Changing it replaces the Service.
  • main: import.meta.url — this file is the bundle entrypoint.
  • port — written to the PORT env var and used to build the url attribute (http://<server-ipv4>:<port>). Default 3000.
  • fetch — returning it from the constructor Effect boots an HTTP server on that port; omit it for a background service.

The resolved resource exposes url, port, unitName, serverId, and the bundle's code.hash.

What a deploy does

One SSH session, using the Server's Alchemy-managed deploy key:

  1. Bundle main with Rolldown into a single ESM file (a generated bootstrap wires up the Bun HTTP server, logging, and config from the environment).

  2. Attach and mount any bound Volumes.

  3. Unpack the bundle to /opt/<unitName>/, write the env file, and install the systemd unit:

    [Service]
    WorkingDirectory=/opt/<unitName>
    EnvironmentFile=-/opt/<unitName>/env
    ExecStart=/root/.bun/bin/bun --no-install /opt/<unitName>/index.mjs
    Restart=always
    RestartSec=5
  4. systemctl enable --now, restart, and wait for the unit to be active — and, when a port is declared, for http://127.0.0.1:<port>/health to answer.

On later deploys Alchemy compares the bundle's content hash against what's deployed: unchanged code is a no-op; changed code is copied up and the unit restarted, a few seconds end to end.

:::caution[The /health route is load-bearing] A Service that declares a port must serve /health — the deploy polls it and fails (dumping the unit's journal into the output) if it never answers. Keep it trivial:

if (url.pathname === "/health") {
  return HttpServerResponse.json({ ok: true });
}

:::

Reachability

The url is the Server's public IP and the Service's port — there's no proxy in between. A fresh Hetzner server has no firewall (every port open); once you apply a Firewall, inbound is default-deny and you choose who reaches the port. For a stable front door with health checks and TLS, put a Load Balancer in front and allow the port only from the private network.

Environment & config

Pass static values with env; read them at runtime through Effect's Config (the runtime's ConfigProvider is backed by the process environment):

import * as Config from "effect/Config";

export default class Api extends Hetzner.Service<Api>()(
  "Api",
  {
    server: Box,
    main: import.meta.url,
    port: 3000,
    env: { GREETING: "hello" },
  },
  Effect.gen(function* () {
    const greeting = yield* Config.String("GREETING");
    // ...
  }),
) {}

Alchemy also injects PORT (when port is set) and the stack metadata (ALCHEMY_STACK_NAME, ALCHEMY_STAGE). Values from bindings are merged first, so your env wins on conflict. See Secrets & Config for handling secret values.

Background services

Omit port/fetch and use ServerHost.run to register a long-running loop — a worker, a queue consumer, a cron-ish daemon:

// src/worker.ts
import * as Hetzner from "@alchemy.run/hetzner";
import { ServerHost } from "alchemy/Runtime/Process";
import * as Effect from "effect/Effect";

export default class Worker extends Hetzner.Service<Worker>()(
  "Worker",
  { server: Box, main: import.meta.url },
  Effect.gen(function* () {
    const host = yield* ServerHost;

    yield* host.run(
      Effect.gen(function* () {
        // do work forever
        return yield* Effect.never;
      }).pipe(Effect.orDie),
    );
  }),
) {}

systemd still supervises the process — if your loop exits or crashes, the unit restarts after 5 seconds.

Multiple Services, one Server

Each Service is its own unit with its own bundle, env file, and lifecycle. Point several at the same server and share resources between them — two Services mounting the same Volume at the same path is one attach and one mount:

// Api serves what Worker writes — same Box, same Volume
class Api extends Hetzner.Service<Api>()(
  "Api",
  { server: Box, main: import.meta.url, port: 3000 },
  /* mounts Data at /data, serves files */
) {}

class Worker extends Hetzner.Service<Worker>()(
  "Worker",
  { server: Box, main: import.meta.url },
  /* mounts Data at /data, writes files */
) {}

Logs

Service logs go to the systemd journal. alchemy logs/alchemy tail don't support Hetzner Services yet — read them over SSH:

ssh root@<server-ip> journalctl -u <unitName> -f

The unit name is the Service's unitName output (surface it as a stack output to keep it handy). Failed deploys already print the last 80 journal lines.

Where next