init_guac

2025-11-25 09:58:37 +03:00
parent 68c8f0e80d
commit 9d5bdd57a7
57 changed files with 18272 additions and 0 deletions
--- a/guacamole_test_11_26/docs/DOCKER_RESTART_GUIDE.md
+++ b/guacamole_test_11_26/docs/DOCKER_RESTART_GUIDE.md
@ -0,0 +1,403 @@
+# 🔄 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` - критичные настройки
+