znt/readme.txt.md

# 📦 Полное руководство: Установка ZenTao в Docker-контейнер (Ubuntu 22.04 + Nginx + PHP 8.1 + MariaDB)

> ⚠️ **Внимание**: Все пароли и настройки в этом руководстве предназначены **только для локальной разработки/тестирования**. Для продакшена используйте сложные пароли, SSL, разделение сервисов и другие меры безопасности.

---

## 🗂 Структура итоговой системы

```
🐳 Docker-контейнер "zentao-stack"
├── 🐧 Ubuntu 22.04 LTS
├── 🌐 Nginx 1.18 (порт 80 внутри → 8080 на хосте)
├── 🐘 PHP 8.1-FPM + расширения для ZenTao
├── 🐬 MariaDB 10.6 (порт 3306 внутри → 3307 на хосте)
├── 📦 ZenTao (из репозитория https://gitlab.com/mzhoot/znt.git)
└── 🔧 Git, curl, wget и другие утилиты
```

---

## 🚀 Шаг 1: Подготовка на хосте (ваш компьютер)

### 1.1. Создайте рабочую папку
```bash
mkdir -p ~/Документы/zdocker/zentao
cd ~/Документы/zdocker/zentao
```

### 1.2. Настройте права Docker (опционально, чтобы не вводить `sudo`)
```bash
# Добавить текущего пользователя в группу docker
sudo usermod -aG docker $USER
# Применить изменения (или перезайдите в систему)
newgrp docker
# Проверка: должно работать без sudo
docker --version
```

---

## 🐳 Шаг 2: Запуск базового контейнера

### 2.1. Скачайте образ Ubuntu 22.04
```bash
docker pull ubuntu:22.04
```

### 2.2. Запустите контейнер с пробросом портов
```bash
docker run -it --name zentao-stack \
  -p 8080:80 \
  -p 3307:3306 \
  ubuntu:22.04 bash
```

> ✅ Вы окажетесь внутри контейнера: `root@<container_id>:/#`

---

## ⚙️ Шаг 3: Установка системных пакетов (внутри контейнера)

```bash
# Обновление индексов пакетов
apt update

# Установка базовых утилит
apt install -y curl wget git unzip nano vim net-tools
```

---

## 🐬 Шаг 4: Установка и настройка MariaDB

### 4.1. Установка сервера
```bash
DEBIAN_FRONTEND=noninteractive apt install -y mariadb-server
```

### 4.2. Запуск службы
```bash
service mariadb start
```

### 4.3. Настройка пароля для root
```bash
mysql -e "ALTER USER 'root'@'localhost' IDENTIFIED BY '1234'; FLUSH PRIVILEGES;"
```

### 4.4. Создание базы и пользователя для ZenTao
```bash
mysql -u root -p1234 -e "
  CREATE DATABASE IF NOT EXISTS zentao CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci;
  GRANT ALL PRIVILEGES ON zentao.* TO 'zentao'@'localhost' IDENTIFIED BY 'zentao_pass123';
  FLUSH PRIVILEGES;
"
```

📝 **Сохраните эти данные** — они понадобятся при веб-установке:

| Параметр | Значение |
|----------|----------|
| Хост БД | `localhost` |
| Порт | `3306` |
| Имя БД | `zentao` |
| Пользователь | `zentao` |
| Пароль | `zentao_pass123` |
| Префикс таблиц | `zt_` (по умолчанию) |

---

## 🌐 Шаг 5: Установка и настройка Nginx

### 5.1. Установка
```bash
apt install -y nginx
```

### 5.2. Запуск
```bash
service nginx start
```

### 5.3. Проверка (должно вернуть `200 OK`)
```bash
curl -I http://localhost
```

---

## 🐘 Шаг 6: Установка PHP 8.1 и расширений для ZenTao

### 6.1. Установка PHP-FPM и модулей
```bash
apt install -y php8.1-fpm php8.1-mysql php8.1-mbstring php8.1-gd \
  php8.1-curl php8.1-zip php8.1-xml php8.1-intl php8.1-bcmath \
  php8.1-opcache php8.1-cli php8.1-imagick
```

### 6.2. Настройка параметров PHP для ZenTao
```bash
cat > /etc/php/8.1/fpm/conf.d/99-zentao.ini << 'EOF'
upload_max_filesize = 50M
post_max_size = 50M
memory_limit = 256M
max_execution_time = 120
date.timezone = Europe/Moscow
opcache.enable = 1
opcache.memory_consumption = 128
display_errors = Off
EOF
```

### 6.3. Запуск PHP-FPM
```bash
service php8.1-fpm start
```

---

## 🔗 Шаг 7: Настройка Nginx для работы с PHP

### 7.1. Перезапись конфигурации виртуального хоста
```bash
cat > /etc/nginx/sites-available/default << 'EOF'
server {
    listen 80;
    server_name localhost;
    root /var/www/html/www;
    index index.php index.html index.htm;

    location / {
        try_files $uri $uri/ /index.php?$query_string;
    }

    location ~ \.php$ {
        include snippets/fastcgi-php.conf;
        fastcgi_pass unix:/run/php/php8.1-fpm.sock;
        fastcgi_param SCRIPT_FILENAME $document_root$fastcgi_script_name;
    }

    location ~ /\.ht {
        deny all;
    }
}
EOF
```

### 7.2. Проверка и перезагрузка Nginx
```bash
nginx -t && service nginx reload
```

---

## 📦 Шаг 8: Установка ZenTao из Git-репозитория

### 8.1. Подготовка веб-корня
```bash
cd /var/www/html
rm -rf ./* ./.??* 2>/dev/null || true
```

### 8.2. Клонирование репозитория
```bash
git clone https://gitlab.com/mzhoot/znt.git .
```

### 8.3. Настройка прав доступа
```bash
# Владелец веб-сервера
chown -R www-www-data /var/www/html

# Стандартные права
find /var/www/html -type d -exec chmod 755 {} \;
find /var/www/html -type f -exec chmod 644 {} \;

# Папки с правами на запись (кэш, конфиги, загрузки)
chmod -R 775 /var/www/html/www/data /var/www/html/tmp /var/www/html/config 2>/dev/null || true
```

### 8.4. Активация установщика
```bash
# Переименование установщика (файл по умолчанию имеет расширение .tmp)
mv /var/www/html/www/install.php.tmp /var/www/html/www/install.php
# (Опционально) скрипт обновления
mv /var/www/html/www/upgrade.php.tmp /var/www/html/www/upgrade.php 2>/dev/null || true
```

---

## 🧪 Шаг 9: Финальная проверка

### 9.1. Проверка обработки PHP
```bash
echo "<?php echo 'PHP_OK';" > /var/www/html/www/test.php
curl http://localhost/test.php
# Ожидаемый вывод: PHP_OK
rm /var/www/html/www/test.php
```

### 9.2. Проверка редиректа на установщик
```bash
curl -I http://localhost/
# Ожидаем: 302 Found + location: install.php
```

### 9.3. Проверка подключения к БД
```bash
mysql -u zentao -pzentao_pass123 -e "SELECT 'DB OK' AS status;" zentao
```

---

## 🔁 Шаг 10: Настройка автозапуска служб (опционально, но удобно)

```bash
# Добавьте в ~/.bashrc внутри контейнера:
cat >> ~/.bashrc << 'EOF'

# Auto-start services for ZenTao stack
service mariadb start &>/dev/null
service nginx start &>/dev/null
service php8.1-fpm start &>/dev/null
EOF

# Применить изменения
source ~/.bashrc
```

Теперь при каждом входе в контейнер (`docker start -ai zentao-stack` или `docker exec -it zentao-stack bash`) службы запустятся автоматически.

---

## 🌐 Шаг 11: Завершение установки через веб-интерфейс

1. Откройте в браузере на хосте:  
   👉 **`http://localhost:8080`**

2. Пройдите шаги установщика:
   - ✅ Проверка окружения (все пункты должны быть зелёными)
   - 🗄 Настройка БД (введите данные из шага 4.4)
   - 👤 Создание администратора
   - 🌍 Выбор языка и региона

3. **После успешной установки удалите установщик** (требование безопасности):
   ```bash
   # Внутри контейнера:
   rm -f /var/www/html/www/install.php
   ```

---

## 💾 Шаг 12: Сохранение данных (критично!)

⚠️ **По умолчанию все данные хранятся внутри контейнера.** При удалении контейнера (`docker rm zentao-stack`) всё пропадёт.

### Вариант А: Сохранить образ контейнера (быстро, но негибко)
```bash
# На хосте, после настройки:
docker commit zentao-stack zentao-stack-saved
```

### Вариант Б: Использовать тома при запуске (рекомендуется)
```bash
# Удалите старый контейнер и запустите новый с томами:
docker run -it --name zentao-stack \
  -p 8080:80 -p 3307:3306 \
  -v zentao_files:/var/www/html \
  -v zentao_db:/var/lib/mysql \
  zentao-stack-saved bash
```

✅ Преимущества томов:
- Данные переживут удаление/пересоздание контейнера
- Легко делать бэкапы (`docker run --rm -v zentao_db:/db -v $(pwd):/backup alpine tar czf /backup/db.tar.gz -C /db .`)
- Можно подключить к другому контейнеру

---

## 🛠 Полезные команды для управления

| Задача | Команда (на хосте) |
|--------|-------------------|
| Остановить контейнер | `docker stop zentao-stack` |
| Запустить контейнер | `docker start -ai zentao-stack` |
| Подключиться к работающему | `docker exec -it zentao-stack bash` |
| Посмотреть логи Nginx | `docker exec zentao-stack tail -f /var/log/nginx/error.log` |
| Бэкап БД | `docker exec zentao-stack mysqldump -u root -p1234 zentao > backup.sql` |
| Обновить код ZenTao | `docker exec zentao-stack bash -c "cd /var/www/html && git pull"` |

---

## 🔐 Безопасность (для продакшена)

```bash
# 1. Смените пароли по умолчанию
mysql -u root -p1234 -e "ALTER USER 'zentao'@'localhost' IDENTIFIED BY 'СложныйПароль!';"

# 2. Отключите отображение ошибок PHP (уже сделано в 99-zentao.ini)
# display_errors = Off

# 3. Настройте HTTPS (самоподписанный сертификат для тестов)
openssl req -x509 -nodes -days 365 -newkey rsa:2048 \
  -keyout /etc/ssl/private/nginx-selfsigned.key \
  -out /etc/ssl/certs/nginx-selfsigned.crt \
  -subj "/C=RU/ST=Moscow/L=Moscow/O=Local/CN=localhost"

# 4. Обновите конфиг Nginx для HTTPS (добавьте listen 443 ssl + пути к сертификатам)
```

---

## 🧭 Возможные проблемы и решения

| Проблема | Решение |
|----------|---------|
| ❌ `502 Bad Gateway` | `service php8.1-fpm start` (PHP-FPM не запущен) |
| ❌ `403 Forbidden` | `chown -R www-www-data /var/www/html && chmod -R 755 /var/www/html` |
| ❌ Белый экран | Временно: `echo "display_errors=On" >> /etc/php/8.1/fpm/conf.d/99-debug.ini && service php8.1-fpm restart` |
| ❌ Не сохраняется конфиг | `chmod -R 775 /var/www/html/www/data /var/www/html/config` |
| ❌ Ошибка подключения к БД | Проверьте: хост `localhost`, порт `3306`, пользователь `zentao`, пароль `zentao_pass123` |
| ❌ Git не клонирует | Проверьте интернет: `ping gitlab.com` |

---

## ✅ Итог

После выполнения всех шагов у вас есть полностью рабочий стек:

```
🌐 Браузер → [хост:8080] → [контейнер:80] → Nginx → PHP-FPM → ZenTao
                                              ↓
                                         MariaDB (порт 3306)
```

**Доступ:**
- 🌍 Веб-интерфейс: `http://localhost:8080`
- 🗄 Управление БД с хоста: `mysql -h 127.0.0.1 -P 3307 -u zentao -pzentao_pass123 zentao`

---

> 💡 **Совет на будущее**: Для удобства управления несколькими сервисами рассмотрите переход на `docker-compose.yml` — это позволит запускать весь стек одной командой `docker compose up -d` и упростит масштабирование.

Если что-то пойдёт не так — напишите текст ошибки, помогу быстро разобраться. Удачи с использованием ZenTao! 🐳📊🚀