# 🔄 Docker: Restart vs Recreate - Когда что использовать?

## 🎯 Быстрая шпаргалка

```bash
# 🟢 RESTART - Легкий перезапуск (контейнер остается тот же)
docker compose restart service_name

# 🟡 RECREATE - Пересоздание (новый контейнер с новой конфигурацией)
docker compose up -d --force-recreate service_name

# 🔴 REBUILD - Полная пересборка (новый образ + новый контейнер)
docker compose up -d --build service_name
```

---

## 📋 Когда использовать RESTART

### ✅ **`docker compose restart`** подходит для:

1. **Изменения в коде приложения** (если есть volume mapping)
   ```bash
   # Изменили Python код в ./api/ (который примонтирован как volume)
   docker compose restart remote_access_api
   ```

2. **Изменения в конфигурационных файлах** (примонтированных как volumes)
   ```bash
   # Изменили nginx/mc.exbytestudios.com.conf
   docker compose restart nginx
   
   # Изменили SQL скрипты (НО только до первого запуска postgres!)
   docker compose restart postgres
   ```

3. **Применение изменений в runtime** (логи, temporary files)
   ```bash
   # Очистить кеш, перечитать конфиги без пересоздания
   docker compose restart guacamole
   ```

4. **Быстрые тесты** (проверить что сервис поднимается)
   ```bash
   docker compose restart remote_access_api
   ```

### ⚠️ **НЕ РАБОТАЕТ для:**
- ❌ Изменений в `environment` секции `docker-compose.yml`
- ❌ Изменений в `command`, `entrypoint`
- ❌ Изменений в `ports`, `networks`, `depends_on`
- ❌ Изменений в `.env` файле (переменные окружения)
- ❌ Обновления Docker образа

---

## 📋 Когда использовать RECREATE

### ✅ **`docker compose up -d --force-recreate`** нужен для:

1. **Изменения переменных окружения** (.env или docker-compose.yml)
   ```bash
   # Добавили POSTGRES_PASSWORD в docker-compose.yml
   # Изменили SYSTEM_ADMIN_PASSWORD в .env
   docker compose up -d --force-recreate remote_access_api
   ```

2. **Изменения портов, сетей, volumes**
   ```bash
   # Изменили ports: "8443:8443" → "9443:8443"
   docker compose up -d --force-recreate nginx
   ```

3. **Изменения команд запуска** (command, entrypoint)
   ```bash
   # Изменили command: в docker-compose.yml
   docker compose up -d --force-recreate service_name
   ```

4. **Изменения depends_on, healthcheck**
   ```bash
   # Добавили новый depends_on: redis
   docker compose up -d --force-recreate remote_access_api
   ```

5. **После изменений в docker-compose.yml структуре**
   ```bash
   # Любые изменения в services секции
   docker compose up -d --force-recreate
   ```

### ⚠️ **НЕ РАБОТАЕТ для:**
- ❌ Обновления базового Docker образа (нужен rebuild)
- ❌ Изменений в Dockerfile (нужен rebuild)

---

## 📋 Когда использовать REBUILD

### ✅ **`docker compose up -d --build`** нужен для:

1. **Изменения Dockerfile**
   ```bash
   # Изменили api/Dockerfile
   docker compose up -d --build remote_access_api
   ```

2. **Обновление базового образа**
   ```bash
   # Обновили FROM python:3.11 → python:3.12
   docker compose up -d --build remote_access_api
   ```

3. **Установка новых зависимостей**
   ```bash
   # Изменили requirements.txt
   docker compose up -d --build remote_access_api
   ```

4. **Изменения в build context**
   ```bash
   # Добавили новые файлы которые COPY в Dockerfile
   docker compose up -d --build remote_access_api
   ```

---

## 🎯 Практические примеры

### **Сценарий 1: Изменил код Python в примонтированной папке**

```bash
# ✅ RESTART достаточно (если есть volume mapping)
docker compose restart remote_access_api

# ИЛИ для FastAPI с auto-reload (вообще ничего не нужно!)
# Просто сохрани файл - uvicorn перезагрузится сам
```

---

### **Сценарий 2: Изменил .env файл (добавил POSTGRES_PASSWORD)**

```bash
# ❌ RESTART НЕ СРАБОТАЕТ
docker compose restart remote_access_api

# ✅ RECREATE нужен обязательно!
docker compose up -d --force-recreate remote_access_api
```

---

### **Сценарий 3: Изменил requirements.txt**

```bash
# ❌ RESTART НЕ СРАБОТАЕТ
docker compose restart remote_access_api

# ❌ RECREATE НЕ СРАБОТАЕТ
docker compose up -d --force-recreate remote_access_api

# ✅ REBUILD обязателен!
docker compose up -d --build remote_access_api
```

---

### **Сценарий 4: Изменил порт в docker-compose.yml**

```bash
# Было: "8443:8443"
# Стало: "9443:8443"

# ❌ RESTART НЕ СРАБОТАЕТ
docker compose restart nginx

# ✅ RECREATE нужен!
docker compose up -d --force-recreate nginx
```

---

### **Сценарий 5: Изменил nginx конфиг (volume-mounted)**

```bash
# Изменили nginx/mc.exbytestudios.com.conf

# ✅ RESTART достаточно (файл примонтирован как volume)
docker compose restart nginx
```

---

### **Сценарий 6: Добавил новый сервис в docker-compose.yml**

```bash
# Добавили services: redis_cache

# ✅ UP создаст новый сервис
docker compose up -d

# НЕ нужен recreate для существующих сервисов
```

---

## 🔍 Как узнать что изменилось?

### **Проверить разницу в конфигурации:**

```bash
# Показать текущую конфигурацию (реальную, после подстановки .env)
docker compose config

# Показать только один сервис
docker compose config remote_access_api

# Проверить переменные окружения в контейнере
docker compose exec remote_access_api printenv

# Проверить что docker compose "видит" из .env
docker compose config | grep POSTGRES_PASSWORD
```

---

## 📊 Таблица: Что требует какого действия

| Что изменилось | Restart | Recreate | Rebuild |
|----------------|---------|----------|---------|
| **Python код (с volume)** | ✅ | ✅ | ✅ |
| **Переменные .env** | ❌ | ✅ | ✅ |
| **docker-compose.yml environment** | ❌ | ✅ | ✅ |
| **docker-compose.yml ports** | ❌ | ✅ | ✅ |
| **docker-compose.yml networks** | ❌ | ✅ | ✅ |
| **docker-compose.yml command** | ❌ | ✅ | ✅ |
| **Nginx config (volume)** | ✅ | ✅ | ✅ |
| **SQL скрипты (volume)** | ✅* | ✅* | ✅* |
| **Dockerfile** | ❌ | ❌ | ✅ |
| **requirements.txt** | ❌ | ❌ | ✅ |
| **Base image (FROM)** | ❌ | ❌ | ✅ |

*\*SQL скрипты применяются только при первом создании БД*

---

## 🚨 Частые ошибки

### **Ошибка 1: Изменил .env, сделал restart - не работает**

```bash
# ❌ НЕПРАВИЛЬНО
nano .env
docker compose restart remote_access_api

# ✅ ПРАВИЛЬНО
nano .env
docker compose up -d --force-recreate remote_access_api
```

---

### **Ошибка 2: Изменил requirements.txt, сделал recreate - не работает**

```bash
# ❌ НЕПРАВИЛЬНО
nano api/requirements.txt
docker compose up -d --force-recreate remote_access_api

# ✅ ПРАВИЛЬНО
nano api/requirements.txt
docker compose up -d --build remote_access_api
```

---

### **Ошибка 3: Хочу применить SQL скрипт к существующей БД**

```bash
# ❌ НЕПРАВИЛЬНО - SQL скрипты выполняются только при ПЕРВОМ создании БД
docker compose restart postgres

# ✅ ПРАВИЛЬНО - Применить вручную
docker compose exec -T postgres psql -U mc_db_user -d mc_db < 004-add-os-field.sql

# ИЛИ удалить volume и пересоздать БД (⚠️ ПОТЕРЯ ДАННЫХ!)
docker compose down -v postgres
docker compose up -d postgres
```

---

## 💡 Лучшие практики

### **1. После изменения .env - всегда recreate:**
```bash
nano .env
docker compose up -d --force-recreate
```

### **2. После git pull - проверь что изменилось:**
```bash
git pull
git diff HEAD~1 docker-compose.yml
git diff HEAD~1 .env

# Если изменился docker-compose.yml или .env:
docker compose up -d --force-recreate

# Если изменился Dockerfile или requirements.txt:
docker compose up -d --build
```

### **3. Проверь что переменные загрузились:**
```bash
docker compose up -d --force-recreate remote_access_api
docker compose exec remote_access_api printenv | grep POSTGRES
```

### **4. Используй docker compose logs для отладки:**
```bash
docker compose logs -f remote_access_api
```

---

## 🎯 Золотое правило

> **Если сомневаешься - используй `up -d --force-recreate`**
> 
> Это безопасно и гарантирует применение всех изменений в конфигурации.
> 
> ```bash
> docker compose up -d --force-recreate service_name
> ```

---

## 📚 Команды для копирования

```bash
# Самые частые случаи:

# Изменил .env
docker compose up -d --force-recreate

# Изменил код (с volume) - FastAPI с auto-reload
# Ничего не делай - перезагрузится сам

# Изменил Dockerfile или requirements.txt
docker compose up -d --build

# Изменил nginx config
docker compose restart nginx

# Изменил docker-compose.yml структуру
docker compose up -d --force-recreate

# Проверить переменные в контейнере
docker compose exec service_name printenv

# Проверить что docker compose "видит"
docker compose config | grep VARIABLE_NAME

# Посмотреть логи
docker compose logs -f service_name
```

---

## 🆘 Troubleshooting

### Проблема: Изменения не применяются даже после recreate

**Причина:** Docker кеширует образы.

**Решение:**
```bash
# Принудительно пересобрать без кеша
docker compose build --no-cache service_name
docker compose up -d --force-recreate service_name
```

---

### Проблема: Не уверен что контейнер использует новую конфигурацию

**Решение:**
```bash
# Удалить и создать заново
docker compose down service_name
docker compose up -d service_name
```

---

## 📖 Связанные документы

- `docker-compose.yml` - основная конфигурация
- `.env` / `production.env` - переменные окружения
- `Действительноважно.md` - критичные настройки