peikarband/docs/deployment/PRODUCTION_DEPLOYMENT.md

راهنمای کامل دیپلوی Production - پیکربند

این مستند شامل تمام مراحل لازم برای راه‌اندازی پروژه پیکربند در محیط Production با استفاده از Woodpecker CI، Harbor Registry و ArgoCD است.

📋 جدول محتویات

1. پیش‌نیازها
2. تنظیمات Harbor Registry
3. تنظیمات Kubernetes
4. تنظیمات ArgoCD
5. تنظیمات Woodpecker CI
6. دیپلوی اولیه
7. مانیتورینگ و لاگ
8. عیب‌یابی

---

🔧 پیش‌نیازها

Infrastructure Requirements

• Kubernetes Cluster: نسخه 1.24+ با حداقل 3 worker nodes
• Harbor Registry: نسخه 2.8+ برای نگهداری images
• ArgoCD: نسخه 2.9+ برای GitOps deployment
• Woodpecker CI: نسخه 2.0+ برای CI/CD pipeline
• PostgreSQL: نسخه 14+ برای database
• Redis: نسخه 7+ برای caching

Resources مورد نیاز

Production Environment:

• CPU: حداقل 6 cores (2 cores per pod × 3 replicas)
• Memory: حداقل 6GB (2GB per pod × 3 replicas)
• Storage: 50GB برای logs و uploads
• Network: Load Balancer با IP عمومی

Staging Environment:

• CPU: حداقل 3 cores
• Memory: حداقل 3GB
• Storage: 20GB

Domain & SSL

• Domain اصلی: peikarband.ir
• Staging: staging.peikarband.ir
• Harbor: harbor.peikarband.ir
• ArgoCD: argocd.peikarband.ir
• SSL Certificate: Let's Encrypt (via cert-manager)

---

🐳 تنظیمات Harbor Registry

1. نصب Harbor

# با Helm
helm repo add harbor https://helm.goharbor.io
helm repo update

helm install harbor harbor/harbor \
  --namespace harbor \
  --create-namespace \
  --set expose.type=ingress \
  --set expose.ingress.hosts.core=harbor.peikarband.ir \
  --set externalURL=https://harbor.peikarband.ir \
  --set persistence.enabled=true \
  --set harborAdminPassword="CHANGE_ME_STRONG_PASSWORD"

2. ساخت Project در Harbor

1. لاگین به Harbor UI: https://harbor.peikarband.ir
2. رفتن به Projects > New Project
3. نام: peikarband
4. Access Level: Private
5. فعال‌سازی Vulnerability Scanning

3. ساخت Robot Account

# از طریق Harbor UI:
# Projects > peikarband > Robot Accounts > New Robot Account

Name: deployer
Expiration: Never
Permissions: 
  - Push Repository
  - Pull Repository
  - Read Helm Chart
  - Create Helm Chart Version

# Token را کپی کنید (فقط یکبار نمایش داده می‌شود)

4. تست دسترسی به Harbor

# لاگین از local machine
docker login harbor.peikarband.ir
Username: robot$peikarband+deployer
Password: [TOKEN]

# تست push image
docker pull nginx:alpine
docker tag nginx:alpine harbor.peikarband.ir/peikarband/test:latest
docker push harbor.peikarband.ir/peikarband/test:latest

---

☸️ تنظیمات Kubernetes

1. ایجاد Namespaces

kubectl create namespace peikarband
kubectl create namespace peikarband-staging
kubectl create namespace argocd
kubectl create namespace woodpecker

2. نصب Cert-Manager (برای SSL)

kubectl apply -f https://github.com/cert-manager/cert-manager/releases/download/v1.13.0/cert-manager.yaml

# ایجاد ClusterIssuer برای Let's Encrypt
cat <<EOF | kubectl apply -f -
apiVersion: cert-manager.io/v1
kind: ClusterIssuer
metadata:
  name: letsencrypt-prod
spec:
  acme:
    server: https://acme-v02.api.letsencrypt.org/directory
    email: admin@peikarband.ir
    privateKeySecretRef:
      name: letsencrypt-prod
    solvers:
    - http01:
        ingress:
          class: nginx
EOF

3. نصب Ingress NGINX

helm repo add ingress-nginx https://kubernetes.github.io/ingress-nginx
helm repo update

helm install ingress-nginx ingress-nginx/ingress-nginx \
  --namespace ingress-nginx \
  --create-namespace \
  --set controller.service.type=LoadBalancer

4. ایجاد Harbor Pull Secret

# Production
kubectl create secret docker-registry harbor-registry-secret \
  --docker-server=harbor.peikarband.ir \
  --docker-username=robot\$peikarband+deployer \
  --docker-password="YOUR_ROBOT_TOKEN" \
  --docker-email=admin@peikarband.ir \
  --namespace=peikarband

# Staging
kubectl create secret docker-registry harbor-registry-secret \
  --docker-server=harbor.peikarband.ir \
  --docker-username=robot\$peikarband+deployer \
  --docker-password="YOUR_ROBOT_TOKEN" \
  --docker-email=admin@peikarband.ir \
  --namespace=peikarband-staging

5. ایجاد Application Secrets

# استفاده از template موجود در k8s/secrets-template.yaml
# ابتدا مقادیر واقعی را جایگزین کنید

# For Production
kubectl apply -f k8s/secrets-production.yaml -n peikarband

# For Staging
kubectl apply -f k8s/secrets-staging.yaml -n peikarband-staging

نمونه ایجاد سریع:

kubectl create secret generic peikarband-prod-secrets \
  --from-literal=db-username=peikarband_prod \
  --from-literal=db-password=YOUR_DB_PASSWORD \
  --from-literal=redis-password=YOUR_REDIS_PASSWORD \
  --from-literal=secret-key=YOUR_SECRET_KEY \
  --from-literal=jwt-secret-key=YOUR_JWT_SECRET \
  --namespace=peikarband

---

🔄 تنظیمات ArgoCD

1. نصب ArgoCD

kubectl create namespace argocd
kubectl apply -n argocd -f https://raw.githubusercontent.com/argoproj/argo-cd/stable/manifests/install.yaml

# دریافت پسورد اولیه admin
kubectl -n argocd get secret argocd-initial-admin-secret -o jsonpath="{.data.password}" | base64 -d

2. دسترسی به ArgoCD UI

# Port forward برای دسترسی موقت
kubectl port-forward svc/argocd-server -n argocd 8080:443

# یا ایجاد Ingress
cat <<EOF | kubectl apply -f -
apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
  name: argocd-server-ingress
  namespace: argocd
  annotations:
    cert-manager.io/cluster-issuer: letsencrypt-prod
    nginx.ingress.kubernetes.io/ssl-passthrough: "true"
    nginx.ingress.kubernetes.io/backend-protocol: "HTTPS"
spec:
  ingressClassName: nginx
  rules:
  - host: argocd.peikarband.ir
    http:
      paths:
      - path: /
        pathType: Prefix
        backend:
          service:
            name: argocd-server
            port:
              name: https
  tls:
  - hosts:
    - argocd.peikarband.ir
    secretName: argocd-tls
EOF

3. اضافه کردن Repository به ArgoCD

# لاگین به ArgoCD
argocd login argocd.peikarband.ir

# اضافه کردن Git repository
argocd repo add https://git.peikarband.ir/ehsan-minadd/peikarband.git \
  --username YOUR_GIT_USERNAME \
  --password YOUR_GIT_TOKEN

4. ایجاد Applications در ArgoCD

# Production
kubectl apply -f argocd/application.yaml

# Staging
kubectl apply -f argocd/application-staging.yaml

# بررسی وضعیت
argocd app list
argocd app get peikarband

5. تنظیم Notifications (اختیاری)

# تنظیم Telegram notifications
kubectl create secret generic argocd-notifications-secret \
  --from-literal=telegram-token=YOUR_BOT_TOKEN \
  --namespace=argocd

kubectl patch configmap argocd-notifications-cm -n argocd --patch '
data:
  service.telegram: |
    token: $telegram-token
  template.app-deployed: |
    message: |
      ✅ Application {{.app.metadata.name}} deployed successfully!
      Version: {{.app.status.sync.revision}}
  trigger.on-deployed: |
    - when: app.status.operationState.phase in ["Succeeded"]
      send: [app-deployed]
'

---

🚀 تنظیمات Woodpecker CI

1. نصب Woodpecker Server

helm repo add woodpecker https://woodpecker-ci.org/
helm repo update

helm install woodpecker woodpecker/woodpecker \
  --namespace woodpecker \
  --create-namespace \
  --set server.host=ci.peikarband.ir

2. اتصال به Git Repository

در Woodpecker UI:

1. لاگین با Git account
2. Activate کردن repository
3. تنظیم Webhooks

3. اضافه کردن Secrets به Woodpecker

از طریق Woodpecker UI یا CLI:

woodpecker-cli secret add \
  --repository peikarband/landing \
  --name harbor_username \
  --value "robot\$peikarband+deployer"

woodpecker-cli secret add \
  --repository peikarband/landing \
  --name harbor_password \
  --value "YOUR_ROBOT_TOKEN"

woodpecker-cli secret add \
  --repository peikarband/landing \
  --name argocd_server \
  --value "argocd.peikarband.ir"

woodpecker-cli secret add \
  --repository peikarband/landing \
  --name argocd_token \
  --value "YOUR_ARGOCD_TOKEN"

woodpecker-cli secret add \
  --repository peikarband/landing \
  --name telegram_bot_token \
  --value "YOUR_BOT_TOKEN"

woodpecker-cli secret add \
  --repository peikarband/landing \
  --name telegram_chat_id \
  --value "YOUR_CHAT_ID"

4. دریافت ArgoCD Token

# ساخت token برای CI/CD
argocd account generate-token --account ci-robot --id ci-robot

---

🎯 دیپلوی اولیه

1. آماده‌سازی کد

# کلون پروژه
git clone https://git.peikarband.ir/ehsan-minadd/peikarband.git
cd peikarband

# بررسی فایل‌های مورد نیاز
ls -la woodpecker.yml
ls -la Dockerfile
ls -la helm/peikarband/
ls -la argocd/

2. Build و Push اولیه Image

# لاگین به Harbor
docker login harbor.peikarband.ir

# Build
make docker-build VERSION=v0.1.0

# Push
make docker-push VERSION=v0.1.0

3. تنظیم DNS

peikarband.ir           A      YOUR_LOADBALANCER_IP
www.peikarband.ir       A      YOUR_LOADBALANCER_IP
staging.peikarband.ir   A      YOUR_LOADBALANCER_IP
harbor.peikarband.ir    A      YOUR_LOADBALANCER_IP
argocd.peikarband.ir    A      YOUR_LOADBALANCER_IP

4. Sync اولیه با ArgoCD

# Production
argocd app sync peikarband
argocd app wait peikarband --timeout 600

# Staging
argocd app sync peikarband-staging
argocd app wait peikarband-staging --timeout 600

5. بررسی وضعیت Deployment

# Pods
kubectl get pods -n peikarband
kubectl get pods -n peikarband-staging

# Services
kubectl get svc -n peikarband

# Ingress
kubectl get ingress -n peikarband

# Logs
kubectl logs -f deployment/peikarband -n peikarband

# Events
kubectl get events -n peikarband --sort-by='.lastTimestamp'

6. تست Health Checks

# Production
curl https://peikarband.ir/ping
curl https://peikarband.ir/health
curl https://peikarband.ir/ready

# Staging
curl https://staging.peikarband.ir/ping

---

📊 مانیتورینگ و لاگ

1. نصب Prometheus & Grafana

helm repo add prometheus-community https://prometheus-community.github.io/helm-charts
helm repo update

helm install prometheus prometheus-community/kube-prometheus-stack \
  --namespace monitoring \
  --create-namespace

2. فعال‌سازی ServiceMonitor

در values-production.yaml:

monitoring:
  serviceMonitor:
    enabled: true
    interval: 30s

3. دسترسی به Grafana

# Port forward
kubectl port-forward svc/prometheus-grafana -n monitoring 3000:80

# Default credentials
Username: admin
Password: prom-operator

4. مشاهده Logs

# Real-time logs
kubectl logs -f deployment/peikarband -n peikarband

# Logs از همه pods
kubectl logs -l app.kubernetes.io/name=peikarband -n peikarband --tail=100

# Logs با timestamp
kubectl logs deployment/peikarband -n peikarband --timestamps=true

---

🔧 عیب‌یابی

مشکلات متداول

1. Image Pull Error

# بررسی secret
kubectl get secret harbor-registry-secret -n peikarband -o yaml

# تست دسترسی به Harbor
docker login harbor.peikarband.ir

# بررسی logs
kubectl describe pod POD_NAME -n peikarband

2. Database Connection Error

# بررسی secrets
kubectl get secret peikarband-prod-secrets -n peikarband -o yaml

# تست اتصال به database
kubectl run -it --rm debug --image=postgres:14 --restart=Never -- \
  psql -h postgres-prod.default.svc.cluster.local -U peikarband_prod -d peikarband_prod

3. Pod در حالت CrashLoopBackOff

# بررسی logs
kubectl logs POD_NAME -n peikarband --previous

# بررسی events
kubectl describe pod POD_NAME -n peikarband

# Debug container
kubectl debug POD_NAME -it --image=busybox -n peikarband

4. Ingress کار نمی‌کند

# بررسی ingress
kubectl describe ingress peikarband -n peikarband

# بررسی certificate
kubectl describe certificate peikarband-tls -n peikarband

# لاگ ingress controller
kubectl logs -n ingress-nginx deployment/ingress-nginx-controller

5. ArgoCD Sync Failed

# بررسی وضعیت app
argocd app get peikarband

# Sync دستی
argocd app sync peikarband --force

# بررسی diff
argocd app diff peikarband

---

📚 منابع اضافی

• Woodpecker CI Documentation
• Harbor Documentation
• ArgoCD Documentation
• Kubernetes Best Practices

---

🔐 Security Checklist

• تمام secrets در Kubernetes ایجاد شده‌اند
• Robot account در Harbor محدود است
• SSL certificates نصب شده‌اند
• Network policies فعال هستند
• Pod security contexts تنظیم شده‌اند
• Resource limits تعریف شده‌اند
• Vulnerability scanning فعال است
• Backup استراتژی تعریف شده است

---

نسخه: 1.0.0
تاریخ: 2025-12-26
نویسنده: Peikarband DevOps Team