8000 feat(deck): run the deck as a user service so it survives terminal close (#29) by simon-inkie · Pull Request #48 · simon-inkie/inkie-deck · GitHub
[go: up one dir, main page]

Skip to content
Closed
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
110 changes: 106 additions & 4 deletions INSTALL.md
Original file line number Diff line number Diff line change
Expand Up @@ -224,9 +224,9 @@ the optional settings (a port, the activity panel, an agent allowlist). Copy
from it if you would rather start there. Two notes on it that have cost people
time:

- The file to write is `.env`. `.env.production` is read by nothing in this
repository; it exists for a systemd `EnvironmentFile`, and a value you put
there will not reach the application when you start it by hand.
- The file to write for a terminal or tmux start is `.env`. The systemd option
below reads `.env.production` through its `EnvironmentFile`; that file is
not loaded when you start the launcher by hand.
- Anything already set in your environment beats the file. That is what makes
a systemd unit's `EnvironmentFile` authoritative, and it is also how you
override one value for one run.
Expand Down Expand Up @@ -273,7 +273,8 @@ pnpm build
(cd packages/deck && node scripts/start-production.mjs)
```

That keeps running too. The subshell is deliberate: the launcher must run with
That runs in the foreground: closing the terminal stops Deck. The subshell is
deliberate: the launcher must run with
`packages/deck` as its working directory (it resolves the build and the `.env`
relative to it), and the brackets mean your own shell stays where it was.

Expand Down Expand Up @@ -307,6 +308,107 @@ Agents appear once something writes into `INBOX_ROOT`, which is tier 3.
to the web server and skips the launcher that validates the roots and loads
the `.env`. `node scripts/start-production.mjs` is the supported way in.

### Keep it running after closing the terminal

Stop the foreground instance with Ctrl+C before choosing one of these options,
so only one Deck instance uses the port. Run the commands from the repository
root after building.

**Detached tmux:** this uses the same `.env` as the foreground launcher.
If a `deck` session already exists, inspect it with `tmux attach -t deck`.
Stop its launcher, then use `tmux kill-session -t deck` before creating a
replacement session with the command below.

```sh
tmux new-session -d -s deck -c "$(pwd -P)/packages/deck" 'node scripts/start-production.mjs'
```

You can now close the terminal. Inspect Deck with `tmux attach -t deck`, then
detach with Ctrl+B followed by D. Stop it with `tmux kill-session -t deck`.
Agents started by `boot-agents.sh` run in the separate `agents` tmux session,
which also survives closing an attached terminal. Starting Deck does not boot
agents, and stopping the `deck` session does not stop the `agents` session.

**systemd user service (Ubuntu 24.04):** this runs Deck outside the terminal
and restarts it if the launcher exits. On WSL, systemd must be enabled in your
distribution first; check that `systemctl --user status` reaches a user manager.
This option supervises Deck and its launcher children, not agent startup.

Copy the configuration and keep it private. If `.env.production` already
exists, edit it instead of overwriting it. Use literal values in this file:
systemd does not expand shell variables such as `$HOME` in an EnvironmentFile.
Remove any `export` prefixes and trailing inline comments copied from `.env`:
use `KEY=value`, with comments on separate lines, and check quoted values
against systemd's EnvironmentFile syntax.

```sh
cp -n packages/deck/.env packages/deck/.env.production
chmod 600 packages/deck/.env.production
```

Render the example unit with this checkout's directory and the Node executable
currently in use, including installations managed by a version manager. The
generated unit is machine-local; do not commit it or either environment file.
`EnvironmentFile` uses glob syntax, so the renderer escapes `\`, `*`, `?` and
`[` there so each of them matches only the literal character.
`WorkingDirectory` is not globbed, so it keeps those characters unchanged.
Systemd can load these paths, but Node's ES module loader rejects backslashes
in module filenames. Use a checkout path without backslashes to run Deck.

```sh
deck_unit_dir="$(systemd-path user-configuration)/systemd/user"
mkdir -p "$deck_unit_dir"
DECK_DIRECTORY="$(cd packages/deck && pwd -P)" \
NODE_BINARY="$(node -p 'process.execPath')" \
python3 - "$deck_unit_dir/deck.service" <<'PY'
import os
from pathlib import Path
import re
import sys

def escape_command(value):
return ''.join('%%' if c == 37 else '\\x%02x' % c
if c <= 32 or c >= 127 or c in (34, 92) else chr(c)
for c in value.encode('utf-8'))

directory = os.environ['DECK_DIRECTORY']
unit = Path('packages/deck/scripts/deck.service').read_text()
for token, value in {
'@DECK_DIRECTORY@': directory,
'@ENVIRONMENT_FILE@': str(Path(directory) / '.env.production'),
'@NODE_BINARY@': os.environ['NODE_BINARY'],
}.items():
if '\n' in value or '\r' in value:
raise ValueError('Unit paths cannot contain line breaks')
# Only ExecStart unescapes C escapes. EnvironmentFile uses glob syntax,
# so escape its glob characters (backslash first) to match them literally.
if token == '@ENVIRONMENT_FILE@':
value = re.sub(r'([\\*?\[])', r'\\\1', value)
value = ('"' + escape_command(value) + '"' if token == '@NODE_BINARY@'
else value.replace('%', '%%'))
unit = unit.replace(token, value)
Path(sys.argv[1]).write_text(unit)
PY
systemctl --user daemon-reload
loginctl enable-linger "$(id -un)"
systemctl --user start deck
systemctl --user status deck
```

Lingering keeps the user manager running after logout; without it, a user
service can stop when your last login closes. If enabling it requires
administrator authorisation, complete that step before relying on logout
survival. Logs are available with `journalctl --user -u deck -f`. Stop Deck
with `systemctl --user stop deck`; an explicit stop does not trigger a restart.
After rebuilding, use `systemctl --user restart deck`.
Repeated failures are limited to five starts within 60 seconds. After fixing
the cause, use `systemctl --user reset-failed deck` and start it again.

Neither option configures automatic Deck or agent startup after a reboot.
Closing every WSL window is also different from shutting down WSL or the host,
which stops both Deck and its agents. Re-render the unit if the checkout or
Node executable moves.

## 5. Bring your agents to life

**This tier is manual, and cannot be otherwise from here.** An agent is a
Expand Down
14 changes: 14 additions & 0 deletions 8000 packages/deck/scripts/deck.service
Original file line number Diff line number Diff line change
@@ -0,0 +1,14 @@
[Unit]
Description=Inkie Deck
StartLimitIntervalSec=60
StartLimitBurst=5

[Service]
Type=simple
WorkingDirectory=@DECK_DIRECTORY@
EnvironmentFile=@ENVIRONMENT_FILE@
ExecStart=@NODE_BINARY@ scripts/start-production.mjs
Restart=always
RestartSec=5s
KillMode=control-group
NoNewPrivileges=yes
150 changes: 150 additions & 0 deletions packages/deck/test/deck-service.test.ts
Original file line number Diff line number Diff line change
@@ -0,0 +1,150 @@
import { afterAll, beforeAll, describe, expect, it } from "vitest";
import { execFileSync, spawnSync } from "node:child_process";
import { mkdirSync, readFileSync, symlinkSync, writeFileSync } from "node:fs";
import path from "node:path";
import { fileURLToPath } from "node:url";
import { mkdtempSync, rmSync } from "~/lib/test-helpers";

const deckDirectory = fileURLToPath(new URL("../", import.meta.url));
const instructions = readFileSync(path.join(deckDirectory, "../../INSTALL.md"), "utf8");
const template = readFileSync(path.join(deckDirectory, "scripts/deck.service"), "utf8");
const renderer = instructions.match(/<<'PY'\n([\s\S]*?)\nPY/);
// Probe the transient-unit capability used below, including in sandboxed runs.
const managerAvailable = spawnSync("systemd-run", ["--user", "--wait", "--pipe", "--collect",
"/usr/bin/true"], { timeout: 15_000 }).status === 0;
const parserBinary = "/lib/systemd/systemd";
const parserAvailable = process.getuid?.() !== 0 &&
spawnSync(parserBinary, ["--version"]).status === 0;
const verifierAvailable = spawnSync("systemd-analyze", ["--version"]).status === 0;
const escapeEnvironmentFile = (value: string) =>
value.replace(/\\/g, "\\\\").replace(/\*/g, "\\*").replace(/\?/g, "\\?").replace(/\[/g, "\\[");

describe("documented Deck user service", () => {
let sandbox: string;
let unitPath: string;
let rendered: string;
let directory: string;
let nodeBinary: string;

beforeAll(() => {
sandbox = mkdtempSync();
directory = path.join(sandbox, 'checkout with spaces % and "quotes" and \\backslash [x] *?');
mkdirSync(directory);
nodeBinary = path.join(sandbox, 'node with \u2003 space %');
symlinkSync(process.execPath, nodeBinary);
writeFileSync(path.join(directory, ".env.production"), "DECK_SERVICE_PROBE=loaded\n");
// Matches the EnvironmentFile glob if `*` and `?` are left unescaped, and
// sorts after the real directory, so its value would clobber the probe's.
const decoy = path.join(sandbox, 'checkout with spaces % and "quotes" and \\backslash [x] AB');
mkdirSync(decoy);
writeFileSync(path.join(decoy, ".env.production"), "DECK_SERVICE_PROBE=decoy\n");
mkdirSync(path.join(directory, "scripts"));
// CommonJS isolates systemd path handling from Node's ESM URL restrictions.
writeFileSync(path.join(directory, "scripts/start-production.cjs"),
'console.log(JSON.stringify({ cwd: process.cwd(), env: process.env.DECK_SERVICE_PROBE }));\n');
unitPath = path.join(sandbox, "deck.service");
expect(renderer, 'INSTALL.md heading "Keep it running after closing the terminal" must supply the unit renderer').not.toBeNull();
execFileSync("python3", ["-", unitPath], {
cwd: path.resolve(deckDirectory, "../.."),
input: renderer![1],
env: { ...process.env, DECK_DIRECTORY: directory, NODE_BINARY: nodeBinary },
});
rendered = readFileSync(unitPath, "utf8");
});

afterAll(() => {
if (sandbox) rmSync(sandbox);
});

it("supervises the production launcher and its children without enabling reboot startup", () => {
expect(template).toContain("Type=simple\n");
expect(template).toContain("ExecStart=@NODE_BINARY@ scripts/start-production.mjs\n");
expect(template).toContain("EnvironmentFile=@ENVIRONMENT_FILE@\n");
expect(template).toContain("Restart=always\n");
expect(template).toContain("RestartSe 8000 c=5s\n");
expect(template).toContain("StartLimitIntervalSec=60\n");
expect(template).toContain("StartLimitBurst=5\n");
expect(template).toContain("NoNewPrivileges=yes\n");
expect(template).toContain("KillMode=control-group\n");
expect(template).not.toContain("[Install]");
expect(readFileSync(path.join(deckDirectory, "scripts/start-production.mjs"), "utf8"))
.toContain("const root = process.cwd()");
});

it("renders machine-local paths and escapes systemd specifiers, globs and quoted paths", () => {
expect(rendered).not.toMatch(/@[A-Z_]+@/);
expect(rendered).toContain(`WorkingDirectory=${directory.replace(/%/g, "%%")}\n`);
expect(rendered).toContain(`EnvironmentFile=${escapeEnvironmentFile(directory).replace(/%/g, "%%")}/.env.production\n`);
expect(rendered).toContain('\\xe2\\x80\\x83');
expect(rendered).not.toContain('\\x2003');
});

it("escapes EnvironmentFile as a glob while WorkingDirectory stays literal", () => {
const fixed = '/checkouts/deck [x] *? \\dir %';
const fixedUnit = path.join(sandbox, "fixed.service");
execFileSync("python3", ["-", fixedUnit], {
cwd: path.resolve(deckDirectory, "../.."),
input: renderer![1],
env: { ...process.env, DECK_DIRECTORY: fixed, NODE_BINARY: "/usr/bin/node" },
});
const unit = readFileSync(fixedUnit, "utf8");
expect(unit).toContain("WorkingDirectory=/checkouts/deck [x] *? \\dir %%\n");
expect(unit).toContain("EnvironmentFile=/checkouts/deck \\[x] \\*\\? \\\\dir %%/.env.production\n");
});

it.skipIf(!verifierAvailable)("passes systemd's unit verifier after following the documented renderer", () => {
const result = spawnSync("systemd-analyze", ["--user", "verify", unitPath], {
encoding: "utf8",
env: { ...process.env, XDG_RUNTIME_DIR: sandbox, XDG_CONFIG_HOME: sandbox },
});
expect(result.status, result.stderr).toBe(0);
expect(result.stderr).not.toMatch(/ignoring:|not absolute|fatal error/);
});

it.skipIf(!parserAvailable)("parses escaped directive paths and UTF-8 command bytes with systemd", () => {
const probePath = path.join(sandbox, "probe.service");
writeFileSync(probePath, rendered.replace("[Unit]\n", "[Unit]\nDefaultDependencies=no\n"));
const result = spawnSync(parserBinary, ["--user", "--test", "--unit=probe.service"], {
encoding: "utf8",
env: { ...process.env, XDG_RUNTIME_DIR: sandbox, XDG_CONFIG_HOME: sandbox,
XDG_CONFIG_DIRS: sandbox, SYSTEMD_UNIT_PATH: sandbox },
maxBuffer: 8 * 1024 * 1024,
});
expect(result.status, result.stderr).toBe(0);
const unit = result.stdout.split("-> Unit probe.service:")[1]?.split("\n\t-> Unit ")[0];
expect(unit).toBeDefined();
expect(unit).toContain(`WorkingDirectory: ${directory}\n`);
expect(unit).toContain(`EnvironmentFile: ${escapeEnvironmentFile(directory)}/.env.production\n`);
expect(unit).toContain(`Command Line: "${nodeBinary}" scripts/start-production.mjs\n`);
expect(unit).not.toContain('node with 03');
});

it.skipIf(!managerAvailable)("starts a launcher with a literal working directory and a glob-escaped environment file", () => {
// Transient properties skip specifier expansion but retain glob escaping.
const environmentFile = rendered.match(/^EnvironmentFile=(.+)$/m)![1].replace(/%%/g, "%");
const result = spawnSync("systemd-run", ["--user", "--wait", "--pipe", "--collect",
"--property", `WorkingDirectory=${directory}`,
"--property", `EnvironmentFile=${environmentFile}`,
"--property", "NoNewPrivileges=yes", nodeBinary, "scripts/start-production.cjs"],
{ encoding: "utf8", timeout: 15_000 });
expect(result.status, result.stderr).toBe(0);
expect(JSON.parse(result.stdout.trim())).toEqual({ cwd: directory, env: "loaded" });
});

it.each(["\n", "\r"])("rejects line breaks in rendered paths (%j)", (lineBreak) => {
const result = spawnSync("python3", ["-", path.join(sandbox, "invalid.service")], {
cwd: path.resolve(deckDirectory, "../.."), input: renderer![1], encoding: "utf8",
env: { ...process.env, DECK_DIRECTORY: directory + lineBreak, NODE_BINARY: nodeBinary },
});
expect(result.status).not.toBe(0);
expect(result.stderr).toContain("Unit paths cannot contain line breaks");
});

it("documents environment-file conversion and replacing an existing tmux session", () => {
expect(instructions).toContain("Remove any `export` prefixes and trailing inline comments");
expect(instructions).toContain("with comments on separate lines");
expect(instructions).toContain("If a `deck` session already exists, inspect it");
expect(instructions).toContain("`tmux kill-session -t deck` before creating a");
expect(instructions).toContain("`systemctl --user reset-failed deck`");
});
});
Loading
0