peikarband/docs/deployment/PRODUCTION_DEPLOYMENT.md

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

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

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

1. [پیش‌نیازها](#پیش‌نیازها)
2. [تنظیمات Harbor Registry](#تنظیمات-harbor-registry)
3. [تنظیمات Kubernetes](#تنظیمات-kubernetes)
4. [تنظیمات ArgoCD](#تنظیمات-argocd)
5. [تنظیمات Woodpecker CI](#تنظیمات-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

```bash
# با 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

```bash
# از طریق 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

```bash
# لاگین از 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

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

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

```bash
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

```bash
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

```bash
# 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

```bash
# استفاده از 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
```

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

```bash
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

```bash
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

```bash
# 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

```bash
# لاگین به 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

```bash
# Production
kubectl apply -f argocd/application.yaml

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

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

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

```bash
# تنظیم 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

```bash
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:

```bash
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

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

---

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

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

```bash
# کلون پروژه
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

```bash
# لاگین به 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

```bash
# 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

```bash
# 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

```bash
# 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

```bash
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`:

```yaml
monitoring:
  serviceMonitor:
    enabled: true
    interval: 30s
```

### 3. دسترسی به Grafana

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

# Default credentials
Username: admin
Password: prom-operator
```

### 4. مشاهده Logs

```bash
# 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

```bash
# بررسی 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

```bash
# بررسی 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

```bash
# بررسی 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 کار نمی‌کند

```bash
# بررسی 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

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

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

# بررسی diff
argocd app diff peikarband
```

---

## 📚 منابع اضافی

- [Woodpecker CI Documentation](https://woodpecker-ci.org/docs)
- [Harbor Documentation](https://goharbor.io/docs)
- [ArgoCD Documentation](https://argo-cd.readthedocs.io)
- [Kubernetes Best Practices](https://kubernetes.io/docs/concepts/configuration/overview/)

---

## 🔐 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