peikarband/docs/BASE_IMAGE.md

# Base Image Management

## چرا Base Image؟

Base image شامل تمام dependencies سنگین است که:
- ✅ فقط یک بار build می‌شود
- ✅ هر بار که کد تغییر می‌کند، دوباره download نمی‌شود
- ✅ Build time را از 8-10 دقیقه به 3-4 دقیقه کاهش می‌دهد
- ✅ قابل استفاده مجدد در چند پروژه

## محتویات Base Image

Base image شامل موارد زیر است:

```dockerfile
FROM python:3.11-slim

# Build Tools
- gcc, g++, make
- curl, ca-certificates
- git, unzip

# Runtime
- Python 3.11
- Node.js 20.x
- npm (latest)
- bun (latest)
```

## ساخت Base Image

### روش 1: Local (توصیه می‌شود برای اولین بار)

```bash
# Run the helper script
./build-base-local.sh
```

این script:
1. از شما username/password Harbor می‌خواهد
2. به registry login می‌کند
3. Base image را build می‌کند
4. به Harbor push می‌کند

**زمان:** ~8-10 دقیقه (اولین بار)

### روش 2: در Woodpecker CI

```bash
# Trigger pipeline manually in Woodpecker UI
# یا از طریق git:
git commit --allow-empty -m "build: rebuild base image"
git push
```

Base image فقط در این حالت‌ها rebuild می‌شود:
- `docker/Dockerfile.base` تغییر کرد
- `.woodpecker.yml` تغییر کرد
- Manual trigger

## استفاده از Base Image

Dockerfile به صورت خودکار از base image استفاده می‌کند:

```dockerfile
ARG BASE_IMAGE=hub.peikarband.ir/peikarband/base:latest
FROM ${BASE_IMAGE} AS builder
```

## مدیریت Versions

### Tags:

1. **`latest`**: آخرین نسخه (default)
2. **`python3.11-node20`**: نسخه specific

### تغییر Version:

اگر می‌خواهید Python یا Node.js version تغییر کند:

1. Edit `docker/Dockerfile.base`:
   ```dockerfile
   ARG PYTHON_VERSION=3.12  # تغییر
   ARG NODE_VERSION=22      # تغییر
   ```

2. Build base image:
   ```bash
   ./build-base-local.sh
   ```

3. Update app Dockerfile:
   ```dockerfile
   ARG BASE_IMAGE=hub.peikarband.ir/peikarband/base:python3.12-node22
   ```

## Troubleshooting

### مشکل: Base image not found

```bash
# Build locally:
./build-base-local.sh

# یا check if exists:
docker pull hub.peikarband.ir/peikarband/base:latest
```

### مشکل: Build fails in CI

```bash
# Check Woodpecker secrets:
- HARBOR_USERNAME
- HARBOR_PASSWORD

# Test locally:
docker login hub.peikarband.ir
```

### مشکل: Base image outdated

```bash
# Force rebuild:
git commit --allow-empty -m "build: rebuild base image"
git push

# یا locally:
./build-base-local.sh
```

## Build Times

| Scenario | With Base | Without Base |
|----------|-----------|--------------|
| First build | 10 min | 10 min |
| Code change only | 3 min ✅ | 10 min ❌ |
| Dependency change | 3 min ✅ | 10 min ❌ |
| Base change | 13 min | 10 min |

## Best Practices

1. **Build base image locally اولین بار**
   ```bash
   ./build-base-local.sh
   ```

2. **فقط وقتی dependencies تغییر کرد rebuild کنید**
   - Python packages
   - Node.js version
   - System tools

3. **از versioned tags استفاده کنید در production**
   ```dockerfile
   ARG BASE_IMAGE=hub.peikarband.ir/peikarband/base:python3.11-node20
   ```

4. **Base image را در Harbor نگه دارید**
   - Private registry
   - Version control
   - Team access

## مثال: Workflow کامل

```bash
# 1. Clone project
git clone <repo>
cd peikarband

# 2. Build base image (فقط یک بار)
./build-base-local.sh
# ⏱️  ~8-10 دقیقه

# 3. Build app (بعدها)
make docker-build
# ⏱️  ~3 دقیقه ✅

# 4. تغییر کد
vim peikarband/src/...

# 5. Build again (سریع!)
make docker-build
# ⏱️  ~3 دقیقه ✅ (dependencies از cache)
```

## خلاصه

✅ **مزایا:**
- Build سریع‌تر (3 دقیقه vs 10 دقیقه)
- بهینه‌سازی cache
- قابل استفاده مجدد

❌ **نیاز به:**
- Build اولیه (یک بار، 10 دقیقه)
- نگهداری در registry
- Rebuild وقتی dependencies تغییر کند

**نتیجه:** برای development و production **بسیار** مفید است! 🚀