Skip to content

feat(deploy): 新增 systemd 裸机安装套件(manager 主机全栈部署) - #313

Draft
anrenlx2025 wants to merge 1 commit into
ongridio:mainfrom
anrenlx2025:feat/systemd-install-suite
Draft

anrenlx2025 wants to merge 1 commit into
ongridio:mainfrom
anrenlx2025:feat/systemd-install-suite

Conversation

@anrenlx2025

Copy link
Copy Markdown
Contributor

Summary

Adds a complete bare-metal systemd deployment suite for the ongrid manager host under deploy/install/systemd/, with the operational guide at docs/install/systemd.md. This complements the existing docker-compose install path (deploy/install/install.sh): it targets dedicated servers where operators want every component running as native systemd units (no containers), managed with standard tooling (journalctl, systemctl).

What's included

  • install-deps.sh - apt/dnf OS packages (mariadb-server, nginx, grafana) + pinned downloads of prometheus / loki / tempo / qdrant with sha256 verification. Idempotent: re-runs skip what is already at target version.
  • install-systemd.sh - installs manager + frontier + dependency stack as systemd units. Fail-closed: bails with a friendly message if any required binary is missing instead of producing a half-working system. --with-deps chains the dep installer.
  • 12 systemd units - ongrid, frontier, prometheus, loki, tempo, qdrant, node_exporter, process_exporter + a wait-for-deps drop-in for startup ordering.
  • nginx config - sites-available entry + location/upgrade-map snippets for serving the web UI and upgrade artifacts.
  • env templating - render-ongrid-env.sh + an annotated env example as the single source for unit EnvironmentFiles.
  • ops helpers - healthcheck script, uninstall script, example alert rules file, prometheus scrape config.
  • tests/ - fresh-host-assert.sh (fresh-host pre/post assertions) and e2e-checklist.sh (end-to-end smoke checklist).

Hardening notes

  • Dedicated system users per unit; secrets rendered root:ongrid 0640 (group-readable by the ongrid group, not world-readable).
  • All upstream binary downloads pinned + sha256-verified.
  • Fail-closed installers; explicit warnings instead of silent degradation (e.g. chown fallback helper).
  • nginx snippets hardened against directory traversal; management write-path endpoints (/-/ lifecycle, remote-write, loki push) blocked at the nginx layer.

Testing

  • Validated end-to-end on a dedicated Debian 13 host: fresh install, idempotent re-run, and uninstall/reinstall cycle.
  • All shell scripts pass bash -n; YAML configs parse-checked.
  • The suite ships its own verification scripts (tests/fresh-host-assert.sh, tests/e2e-checklist.sh) so the above can be reproduced on any fresh host.
  • Note: the deployment manifests CI job's bash -n list does not currently include these scripts; happy to follow up with a PR adding them if this suite is accepted.

Relationship to existing install paths

install.sh remains the quick-start path. This suite is for operators running the full manager stack (metrics, logs, traces, vector store) on dedicated bare-metal hosts under systemd - e.g. constrained environments where container runtimes are not permitted.

Author confirmation

deploy/install/systemd/ 下新增与既有 install.sh(docker-compose 路线)
互补的裸机 systemd 部署拓扑,面向不便使用容器的专用服务器场景:

- install-deps.sh:apt/dnf 安装 OS 依赖(mariadb/nginx/grafana)+
  固定版本下载 prometheus/loki/tempo/qdrant(sha256 校验,幂等重入)
- install-systemd.sh / uninstall-systemd.sh:单元装配 + 完整卸载,
  fail-closed(缺二进制即中止而非产出半成品安装)
- 12 个 systemd unit(ongrid/frontier/prometheus/loki/tempo/qdrant/
  node_exporter/process_exporter)+ wait-for-deps 启动顺序 drop-in
- render-ongrid-env.sh:env 渲染(密钥生成 / 幂等保留 / 权限收紧)
- generate-self-signed-ca.sh:自签 CA + broker server cert(SAN 参数化)
- nginx 子路径反代 snippets + WebSocket upgrade map + 健康检查探针
- tests/:fresh-host 验收断言 + E2E checklist

安全设计:dep 服务独立 uid+组与 manager env 秘密隔离;秘密文件
0600/0640 root:ongrid;nginx 层封禁管理端点(/-/、remote-write);
非交互场景 purge 需显式 --yes。

验证:bash -n 全绿 + YAML 解析全绿 + Debian 13 fresh host 端到端部署。
@anrenlx2025
anrenlx2025 requested a review from singchia as a code owner August 15, 2026 02:41
@anrenlx2025
anrenlx2025 marked this pull request as draft August 15, 2026 03:00
@anrenlx2025

Copy link
Copy Markdown
Contributor Author

Converting to draft: the deployment manifests check fails on this PR by design, and it uncovered a direction conflict I should have caught before opening it.

Commit 3f66e3f ("chore(release): remove manager systemd packaging", 2026-07-16) removed the previous - much simpler - manager systemd install suite and added a guard in scripts/test-compose-release-package.sh asserting that deploy/install/systemd/ stays empty. The trade-off at the time was release-engineering simplicity: the compose-only package pulls version-locked images from CNB and keeps install.sh / package.sh single-path, with the Helm chart covering the k8s side.

So this PR re-introduces exactly the deployment mode the project dropped about a month ago. Before any review time is spent here, a question for the maintainers: is there any appetite for taking this back - e.g. as a community-maintained bare-metal path kept fully out of the compose release package and the install.sh / uninstall.sh dispatchers - or is manager-side systemd permanently out of scope now? If the latter, I'll close this PR; the suite keeps serving our own deployment either way, so no hard feelings either direction.

For context, this is not a port of the removed suite. It is an independently engineered, hardened suite we run in production: per-unit system users with secret isolation, sha256-pinned dependency installs, idempotent install / uninstall (with purge), env rendering, nginx hardening, and bundled fresh-host verification scripts (tests/). If it were accepted, the directory guard would need a maintainer call - e.g. scope it to the release package contents instead of the repo path, or agree on a different home such as contrib/systemd/.

Apologies for the red check showing up before this explanation.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant