Remote-Control-Center/guacamole_test_11_26/docs/DOCKER_RESTART_GUIDE.md

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

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

# 🟢 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)

   # Изменили Python код в ./api/ (который примонтирован как volume)
   docker compose restart remote_access_api
   

2. Изменения в конфигурационных файлах (примонтированных как volumes)

   # Изменили nginx/mc.exbytestudios.com.conf
   docker compose restart nginx
   
   # Изменили SQL скрипты (НО только до первого запуска postgres!)
   docker compose restart postgres
   

3. Применение изменений в runtime (логи, temporary files)

   # Очистить кеш, перечитать конфиги без пересоздания
   docker compose restart guacamole
   

4. Быстрые тесты (проверить что сервис поднимается)

   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)

   # Добавили POSTGRES_PASSWORD в docker-compose.yml
   # Изменили SYSTEM_ADMIN_PASSWORD в .env
   docker compose up -d --force-recreate remote_access_api
   

2. Изменения портов, сетей, volumes

   # Изменили ports: "8443:8443" → "9443:8443"
   docker compose up -d --force-recreate nginx
   

3. Изменения команд запуска (command, entrypoint)

   # Изменили command: в docker-compose.yml
   docker compose up -d --force-recreate service_name
   

4. Изменения depends_on, healthcheck

   # Добавили новый depends_on: redis
   docker compose up -d --force-recreate remote_access_api
   

5. После изменений в docker-compose.yml структуре

   # Любые изменения в services секции
   docker compose up -d --force-recreate
   

⚠️ НЕ РАБОТАЕТ для:

• ❌ Обновления базового Docker образа (нужен rebuild)
• ❌ Изменений в Dockerfile (нужен rebuild)

---

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

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

1. Изменения Dockerfile

   # Изменили api/Dockerfile
   docker compose up -d --build remote_access_api
   

2. Обновление базового образа

   # Обновили FROM python:3.11 → python:3.12
   docker compose up -d --build remote_access_api
   

3. Установка новых зависимостей

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

4. Изменения в build context

   # Добавили новые файлы которые COPY в Dockerfile
   docker compose up -d --build remote_access_api
   

---

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

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

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

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

---

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

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

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

---

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

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

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

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

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

---

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

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

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

---

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

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

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

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

---

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

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

# Показать текущую конфигурацию (реальную, после подстановки .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 - не работает

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

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

---

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

# ❌ НЕПРАВИЛЬНО
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 скрипт к существующей БД

# ❌ НЕПРАВИЛЬНО - 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:

nano .env
docker compose up -d --force-recreate

2. После git pull - проверь что изменилось:

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. Проверь что переменные загрузились:

docker compose up -d --force-recreate remote_access_api
docker compose exec remote_access_api printenv | grep POSTGRES

4. Используй docker compose logs для отладки:

docker compose logs -f remote_access_api

---

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

Если сомневаешься - используй up -d --force-recreate

Это безопасно и гарантирует применение всех изменений в конфигурации.

docker compose up -d --force-recreate service_name

---

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

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

# Изменил .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 кеширует образы.

Решение:

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

---

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

Решение:

# Удалить и создать заново
docker compose down service_name
docker compose up -d service_name

---

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

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