replace ark webapp --daemon with systemd user service (ark webapp install/uninstall)

Author: lyzx2001

README.md

@@ -161,6 +161,10 @@ ARK parses the PDF with PyMuPDF + Claude Haiku, pre-fills the wizard, and can ki
 | `ark delete <name>` | Remove project entirely |
 | `ark setup-bot` | Configure Telegram bot (one-time) |
 | `ark list` | List all projects with status |
+| `ark webapp install` | Install web portal as systemd user service |
+| `ark webapp uninstall` | Stop and remove the web portal service |
+
+> **Note:** `ark webapp --daemon` is deprecated and will be removed in a future release. Use `ark webapp install` instead.
 
 <details>
 <summary><strong>Direct orchestrator invocation</strong></summary>

README_ar.md

@@ -161,6 +161,10 @@ ark new mma --from-pdf proposal.pdf
 | `ark delete <name>` | حذف المشروع بالكامل |
 | `ark setup-bot` | إعداد بوت تيليغرام (مرة واحدة) |
 | `ark list` | سرد جميع المشاريع وحالتها |
+| `ark webapp install` | تثبيت بوابة الويب كخدمة systemd للمستخدم |
+| `ark webapp uninstall` | إيقاف وإزالة خدمة بوابة الويب |
+
+> **ملاحظة:** `ark webapp --daemon` مهمل وسيتم إزالته في إصدار مستقبلي. استخدم `ark webapp install` بدلاً منه.
 
 <details>
 <summary><strong>استدعاء المُنسق مباشرة</strong></summary>

README_zh.md

@@ -161,6 +161,10 @@ ARK 使用 PyMuPDF + Claude Haiku 解析 PDF，预填向导内容，可从提取
 | `ark delete <name>` | 完全删除项目 |
 | `ark setup-bot` | 配置 Telegram 机器人（一次性） |
 | `ark list` | 列出所有项目及状态 |
+| `ark webapp install` | 将 Web 门户安装为 systemd 用户服务 |
+| `ark webapp uninstall` | 停止并移除 Web 门户服务 |
+
+> **注意：** `ark webapp --daemon` 已废弃，将在未来版本中移除。请使用 `ark webapp install` 代替。
 
 <details>
 <summary><strong>直接调用 orchestrator</strong></summary>

ark/cli.py

@@ -2886,6 +2886,92 @@ class RunArgs:
 #  ark webapp
 # ============================================================
 
+_SYSTEMD_SERVICE_NAME = "ark-webapp"
+
+
+def _service_file_path() -> Path:
+    return Path.home() / ".config" / "systemd" / "user" / f"{_SYSTEMD_SERVICE_NAME}.service"
+
+
+def _generate_service_unit(host: str, port: int) -> str:
+    """Generate a systemd user service unit file for the ARK webapp."""
+    python_bin = sys.executable
+    ark_root = get_ark_root()
+    return f"""\
+[Unit]
+Description=ARK Research Portal
+After=network.target
+
+[Service]
+Type=simple
+WorkingDirectory={ark_root}
+ExecStart={python_bin} -m ark.cli webapp --host {host} --port {port}
+Restart=on-failure
+RestartSec=5
+StandardOutput=journal
+StandardError=journal
+
+[Install]
+WantedBy=default.target
+"""
+
+
+def _cmd_webapp_install(host: str, port: int):
+    """Install and start ARK webapp as a systemd user service."""
+    import subprocess as _sp
+
+    svc_path = _service_file_path()
+    svc_path.parent.mkdir(parents=True, exist_ok=True)
+
+    unit = _generate_service_unit(host, port)
+    svc_path.write_text(unit)
+    print(f"  Service file written to {_c(str(svc_path), Colors.CYAN)}")
+
+    # Reload, enable, and start
+    _sp.run(["systemctl", "--user", "daemon-reload"], check=True)
+    _sp.run(["systemctl", "--user", "enable", _SYSTEMD_SERVICE_NAME], check=True)
+    _sp.run(["systemctl", "--user", "start", _SYSTEMD_SERVICE_NAME], check=True)
+
+    print(f"\n  {_c('ARK Webapp', Colors.BOLD)} installed and started as systemd user service.")
+    print(f"  URL: {_c(f'http://{host}:{port}', Colors.CYAN)}")
+    print()
+    print(f"  Manage with:")
+    print(f"    {_c(f'systemctl --user status {_SYSTEMD_SERVICE_NAME}', Colors.DIM)}")
+    print(f"    {_c(f'systemctl --user restart {_SYSTEMD_SERVICE_NAME}', Colors.DIM)}")
+    print(f"    {_c(f'journalctl --user -u {_SYSTEMD_SERVICE_NAME} -f', Colors.DIM)}")
+    print()
+
+    # Check linger
+    try:
+        r = _sp.run(["loginctl", "show-user", os.environ.get("USER", "")],
+                     capture_output=True, text=True)
+        if "Linger=no" in r.stdout:
+            print(f"  {_c('Note:', Colors.YELLOW)} Linger is not enabled for your user.")
+            print(f"  The service will stop when you log out. To keep it running:")
+            user = os.environ.get("USER", "")
+            print(f"    {_c(f'sudo loginctl enable-linger {user}', Colors.BOLD)}")
+            print()
+    except FileNotFoundError:
+        pass
+
+
+def _cmd_webapp_uninstall():
+    """Stop and remove the ARK webapp systemd user service."""
+    import subprocess as _sp
+
+    svc_path = _service_file_path()
+    if not svc_path.exists():
+        print(f"  {_c('Not installed:', Colors.YELLOW)} No systemd service found at {svc_path}")
+        return
+
+    _sp.run(["systemctl", "--user", "stop", _SYSTEMD_SERVICE_NAME], capture_output=True)
+    _sp.run(["systemctl", "--user", "disable", _SYSTEMD_SERVICE_NAME], capture_output=True)
+    svc_path.unlink(missing_ok=True)
+    _sp.run(["systemctl", "--user", "daemon-reload"], check=True)
+
+    print(f"  {_c('ARK Webapp', Colors.BOLD)} service stopped and removed.")
+
+
 def cmd_webapp(args):
     """Start the ARK web app (lab-facing project submission portal)."""
     subcmd = getattr(args, 'webapp_cmd', None)
@@ -2896,6 +2982,13 @@ def cmd_webapp(args):
         cmd_web(args)
         return
 
+    if subcmd == 'install':
+        _cmd_webapp_install(args.host, args.port)
+        return
+    if subcmd == 'uninstall':
+        _cmd_webapp_uninstall()
+        return
+
     try:
         import uvicorn
         from ark.webapp import create_app
@@ -2915,6 +3008,8 @@ def cmd_webapp(args):
         print(f"  Edit {_c(str(_env_file()), Colors.CYAN)} and set SMTP_USER / SMTP_PASSWORD.\n")
 
     if args.daemon:
+        print(f"\n  {_c('Deprecation:', Colors.YELLOW)} --daemon uses os.fork() and will be removed in a future release.")
+        print(f"  Use {_c('ark webapp install', Colors.BOLD)} instead for a systemd user service.\n")
         _root = get_ark_root()
         _webapp_dir = _root / "ark_webapp"
         _webapp_dir.mkdir(exist_ok=True)
@@ -3401,9 +3496,11 @@ def main():
     webapp_sub = p_webapp.add_subparsers(dest="webapp_cmd")
     webapp_sub.add_parser("disable", help="Block new project submissions")
     webapp_sub.add_parser("enable", help="Allow new project submissions")
+    webapp_sub.add_parser("install", help="Install as systemd user service (auto-start on boot)")
+    webapp_sub.add_parser("uninstall", help="Stop and remove systemd user service")
     p_webapp.add_argument("--port", type=int, default=8423, help="Port (default: 8423)")
     p_webapp.add_argument("--host", default="0.0.0.0", help="Host (default: 0.0.0.0)")
-    p_webapp.add_argument("--daemon", action="store_true", help="Run in background")
+    p_webapp.add_argument("--daemon", action="store_true", help="Run in background (deprecated, use 'install')")
     p_webapp.set_defaults(func=cmd_webapp)
 
     # ark web disable/enable [project]