106 lines
4.5 KiB
Markdown
106 lines
4.5 KiB
Markdown
# OS 起動時の自動起動（systemd）
|
||
|
||
MAESTRO を systemd サービスとして登録し、マシンの起動時に自動で立ち上げる手順。
|
||
プロセス監督・異常終了時の自動再起動・ログ集約（journald）も systemd が担う。
|
||
|
||
## 前提と役割分担
|
||
|
||
- **`scripts/server.sh`** … ビルド・手動運用・開発用。`start` は毎回ビルドしてから
|
||
`dist/main.js` を起動する。
|
||
- **systemd サービス** … boot 自動起動と本番のプロセス監督用。ビルドはしない
|
||
（`node dist/main.js` を直接監督する）。
|
||
|
||
> **同時起動しないこと**。`server.sh start` が動かしているプロセスと systemd の
|
||
> サービスを両方立てると、同じ DB に対して二重起動になる（`instance-lock` が最悪の
|
||
> 破損は防ぐが、正しくない状態）。systemd に任せると決めたら、運用中の起動・停止は
|
||
> `systemctl start/stop` に統一し、`server.sh start` は使わない。
|
||
|
||
## インストール
|
||
|
||
まずビルドして `dist/` を最新にする（**root では実行しない**。アプリを動かすユーザーで）。
|
||
|
||
```bash
|
||
scripts/server.sh start # ビルド＋起動を確認。この後 stop して systemd に委ねる
|
||
scripts/server.sh stop
|
||
```
|
||
|
||
生成されるユニットを先に確認したいときは `--print`（何もインストールしない）。
|
||
|
||
```bash
|
||
scripts/install-systemd.sh --print
|
||
```
|
||
|
||
### user サービス（既定・推奨）
|
||
|
||
root 不要。スクリプトを叩いたユーザー自身のサービスとして動く。引数なしがこれ。
|
||
|
||
```bash
|
||
scripts/install-systemd.sh
|
||
```
|
||
|
||
やっていること: `deploy/maestro.service`（テンプレート）を現在のチェックアウトから
|
||
埋めて `~/.config/systemd/user/maestro.service` に配置し、`systemctl --user enable
|
||
--now` する。ユニットに `User=` は付かない（起動ユーザーで動く）。
|
||
|
||
boot 時にログインなしで動かすため **linger** を有効化する（インストーラが自動で試す）。
|
||
自分のユーザーの linger は通常 root なしで有効化できる。ポリシー上できなかった場合だけ
|
||
警告が出るので、そのときは一度 `sudo loginctl enable-linger <user>` を実行する。
|
||
|
||
```bash
|
||
systemctl --user status maestro # 状態
|
||
journalctl --user -u maestro -f # ログ
|
||
systemctl --user restart maestro # 再起動（ビルドし直した後など）
|
||
```
|
||
|
||
### system サービス（マシン全体・root が使える場合）
|
||
|
||
ログインユーザーに依らずマシン起動時に立ち上げたいとき。インストールに sudo が要る。
|
||
|
||
```bash
|
||
scripts/install-systemd.sh --mode system --run-as <app-user>
|
||
```
|
||
|
||
`/etc/systemd/system/maestro.service` に配置し、`User=<app-user>` で動く。
|
||
状態・ログは `systemctl status maestro` / `journalctl -u maestro -f`。
|
||
|
||
## よく使うオプション
|
||
|
||
| オプション | 意味 |
|
||
|---|---|
|
||
| `--print` / `--dry-run` | 生成されるユニットを表示するだけ。インストールしない |
|
||
| `--mode system` | マシン全体の system サービスとして入れる（既定は `user`） |
|
||
| `--run-as <user>` | system モードのアプリ実行ユーザー |
|
||
| `--name <n>` | サービス名（既定 `maestro`）。複数インスタンス用 |
|
||
| `--no-start` | boot 用に enable するが、いますぐ起動はしない |
|
||
|
||
## デプロイ後の更新
|
||
|
||
新しいコードを反映するとき（user サービスの場合）:
|
||
|
||
```bash
|
||
git pull
|
||
npm run build # または scripts/server.sh を使わず build のみ
|
||
systemctl --user restart maestro # system サービスなら sudo systemctl restart maestro
|
||
```
|
||
|
||
## 設定・環境変数
|
||
|
||
- ポートやモードなどはリポジトリ内 `config.yaml` を読む（アプリが自前で読み込む）。
|
||
- `.env` があれば `EnvironmentFile` として読み込む（任意）。ただし systemd の
|
||
`.env` 解釈は素朴な `KEY=value` 前提。`server.sh` が対応している凝ったクォートは
|
||
効かないので、systemd 経由で使う値は単純な形式にすること。
|
||
- 既定の実行モードは `AAO_MODE=worker`（フルオーケストレータ）。gateway として
|
||
動かすなら `.env` に `AAO_MODE=gateway` を書く。
|
||
|
||
## アンインストール
|
||
|
||
```bash
|
||
# system
|
||
sudo systemctl disable --now maestro
|
||
sudo rm /etc/systemd/system/maestro.service && sudo systemctl daemon-reload
|
||
|
||
# user
|
||
systemctl --user disable --now maestro
|
||
rm ~/.config/systemd/user/maestro.service && systemctl --user daemon-reload
|
||
```
|