{
  "title": "راهنمای راه‌اندازی",
  "slug": "team/devops/setup-guide",
  "url": "/docs/team/devops/setup-guide",
  "frontmatter": {
    "layout": "doc",
    "title": "راهنمای راه‌اندازی",
    "description": "راهنمای گام‌به‌گام راه‌اندازی محیط توسعه از صفر تا اجرای سرویس‌ها",
    "version": "1.0.0",
    "status": "PRIVATE",
    "author": "xoxxel",
    "owner": "Devops Team",
    "created_at": "2026-06-15",
    "updated_at": "2026-06-15",
    "tags": "",
    "reviewers": ""
  },
  "sections": [
    {
      "level": 1,
      "heading": "راهنمای راه‌اندازی",
      "content": "**Development Setup Guide — Zero to Running**\n\n---"
    },
    {
      "level": 2,
      "heading": "مسیر رسمی توسعه و استقرار",
      "content": "پلتفرم NONS انحصاراً از مسیر **Kubernetes-Native (Helm + K3d)** برای توسعه، تست و استقرار پشتیبانی می‌کند. منبع حقیقت پیکربندی استقرار پروژه در پوشه `deploy/` قرار دارد.\n\n---"
    },
    {
      "level": 2,
      "heading": "مسیر رسمی: استقرار کامل با K3d + Helm",
      "content": ""
    },
    {
      "level": 3,
      "heading": "گام ۱: ایجاد کلاستر K3d",
      "content": "```bash\nk3d cluster create nons \\\n  -p \"80:80@loadbalancer\" \\\n  -p \"8085:8080@loadbalancer\" \\\n  --k3s-arg \"--disable=traefik@server:0\"\n```\n\nترافیک پیش‌فرض K3s غیرفعال می‌شود تا چارت سفارشی Traefik (v3) خودمان را نصب کنیم."
    },
    {
      "level": 3,
      "heading": "گام ۲: ایجاد Namespaceها",
      "content": "```bash\nkubectl create namespace nons-platform\nkubectl create namespace nons-system\n```"
    },
    {
      "level": 3,
      "heading": "گام ۳: نصب سرویس‌های زیرساختی",
      "content": "ترتیب نصب با توجه به وابستگی‌ها:\n\n```bash"
    },
    {
      "level": 1,
      "heading": "۱. پایگاه داده",
      "content": "helm install nons-postgres ./deploy/helm/postgres \\\n  -n nons-platform -f ./deploy/environments/local/values.yaml\n\nhelm install nons-redis ./deploy/helm/redis \\\n  -n nons-platform -f ./deploy/environments/local/values.yaml\n\nhelm install nons-nats ./deploy/helm/nats \\\n  -n nons-platform -f ./deploy/environments/local/values.yaml\n```"
    },
    {
      "level": 3,
      "heading": "گام ۴: نصب سرویس‌های احراز هویت",
      "content": "```bash"
    },
    {
      "level": 1,
      "heading": "۲. Ory Kratos (با migration خودکار)",
      "content": "helm install nons-kratos ./deploy/helm/kratos \\\n  -n nons-platform -f ./deploy/environments/local/values.yaml"
    },
    {
      "level": 1,
      "heading": "۳. Ory Hydra (با migration خودکار)",
      "content": "helm install nons-hydra ./deploy/helm/hydra \\\n  -n nons-platform -f ./deploy/environments/local/values.yaml"
    },
    {
      "level": 1,
      "heading": "۴. Auth Service (Bridge)",
      "content": "k3d image import nons-auth-service:latest -c nons\nhelm install nons-auth-service ./deploy/helm/auth-service \\\n  -n nons-platform -f ./deploy/environments/local/values.yaml\n```"
    },
    {
      "level": 3,
      "heading": "گام ۵: نصب Gateway",
      "content": "```bash\nhelm install nons-gateway ./deploy/helm/gateway \\\n  -n nons-system -f ./deploy/environments/local/values.yaml\n```"
    },
    {
      "level": 3,
      "heading": "گام ۶: تأیید وضعیت",
      "content": "```bash"
    },
    {
      "level": 1,
      "heading": "همه پادها باید Running باشند",
      "content": "kubectl get pods -n nons-platform\nkubectl get pods -n nons-system"
    },
    {
      "level": 1,
      "heading": "Gateway باید ۲۰۰ برگرداند",
      "content": "curl -i http://localhost/v1/auth/health"
    },
    {
      "level": 1,
      "heading": "Kratos باید redirect برگرداند",
      "content": "curl -i http://localhost/v1/auth/kratos/self-service/login/browser"
    },
    {
      "level": 1,
      "heading": "مسیر محافظت‌شده باید ۴۰۱ برگرداند (بدون توکن)",
      "content": "curl -i http://localhost/v1/protected\n```\n\n---"
    },
    {
      "level": 2,
      "heading": "بیلد و تست",
      "content": ""
    },
    {
      "level": 3,
      "heading": "بیلد همه پکیج‌ها",
      "content": "```bash\ncd nons-api\npnpm install\npnpm build\n```"
    },
    {
      "level": 3,
      "heading": "اجرای تست‌ها",
      "content": "```bash"
    },
    {
      "level": 1,
      "heading": "تست TypeScript",
      "content": "pnpm test"
    },
    {
      "level": 1,
      "heading": "تست Go Core",
      "content": "cd core && go test ./... -v\n```"
    },
    {
      "level": 3,
      "heading": "کد جنریشن (Proto → Bindings)",
      "content": "```bash\npnpm codegen\n```\n\nاین دستور از Proto files در `contracts/`، bindings TypeScript و Go تولید می‌کند.\n\n---"
    },
    {
      "level": 2,
      "heading": "استقرار نسخه جدید (مسیر Helm)",
      "content": "```bash"
    },
    {
      "level": 1,
      "heading": "۱. بیلد ایمیج",
      "content": "docker build -t nons/auth-service:v1.1.0 -f services/auth-service/Dockerfile ."
    },
    {
      "level": 1,
      "heading": "۲. ایمپورت به K3d",
      "content": "k3d image import nons/auth-service:v1.1.0 -c nons"
    },
    {
      "level": 1,
      "heading": "۳. آپگرید Helm",
      "content": "helm upgrade nons-auth-service ./deploy/helm/auth-service \\\n  --set image.tag=v1.1.0 \\\n  -n nons-platform \\\n  -f ./deploy/environments/local/values.yaml\n```\n\n---"
    },
    {
      "level": 2,
      "heading": "رول‌بک (Rollback)",
      "content": "در صورت بروز خطا در استقرار، به نسخه پایدار قبلی بازگردید:\n\n```bash"
    },
    {
      "level": 1,
      "heading": "بررسی وضعیت رول‌اوت",
      "content": "kubectl rollout status deployment/nons-auth-service -n nons-platform"
    },
    {
      "level": 1,
      "heading": "مشاهده تاریخچه نسخه‌ها",
      "content": "helm history nons-auth-service -n nons-platform"
    },
    {
      "level": 1,
      "heading": "بازگشت به نسخه پایدار",
      "content": "helm rollback nons-auth-service <REVISION> -n nons-platform\n```\n\n---"
    },
    {
      "level": 2,
      "heading": "مدیریت کلاستر K3d",
      "content": "```bash"
    },
    {
      "level": 1,
      "heading": "ایست کلاستر",
      "content": "k3d cluster stop nons"
    },
    {
      "level": 1,
      "heading": "شروع مجدد",
      "content": "k3d cluster start nons"
    },
    {
      "level": 1,
      "heading": "حذف و بازسازی",
      "content": "k3d cluster delete nons\n```\n\n---"
    },
    {
      "level": 2,
      "heading": "عیب‌یابی سریع",
      "content": "| مشکل | دستور تشخیص |\n|------|------------|\n| پاد در حال CrashLoopBackOff | `kubectl describe pod <pod> -n nons-platform` |\n| Gateway 503 می‌دهد | `kubectl logs -l app=auth-service -n nons-platform --tail=50` |\n| Kratos/Hydra migration failed | `kubectl logs job/nons-kratos-migration -n nons-platform` |\n| NATS وصل نمی‌شود | `kubectl exec -n nons-platform -it deployment/nons-nats -- nats stream list` |\n| Redis وصل نمی‌شود | `kubectl run tmp-redis --rm -i --tty --image=redis:alpine -n nons-platform -- redis-cli -h redis ping` |\n| Helm نصب نمی‌شود | `helm status <release> -n nons-platform` |\n| لاگ بلادرنگ | `kubectl logs -f -l app=<service> -n nons-platform` |\n| رول‌بک | `helm rollback <release> <revision> -n nons-platform` |\n\n---"
    },
    {
      "level": 2,
      "heading": "منابع",
      "content": "- [پیش‌نیازها](./prerequisites.md)\n- [راهنمای عملیات](./runbook.md)\n- [معماری Helm](./helm-architecture.md)\n- [معماری کانتینر](./container-delivery-architecture.md)"
    }
  ]
}