# Deployment Guide — Temp Spec Management System V4

This guide describes how to deploy the system with Docker Compose and lists the configuration changes introduced in V4.

## Release Highlights
- Local MySQL account store with self‑registration and admin CRUD tools.
- Notification inputs accept semicolon‑separated email lists stored in the database.
- New `DEFAULT_NOTIFICATION_EMAILS` environment variable for scheduled reminders.
- Database tables renamed with `tst_` prefix; `User` adds `name`; passwords are hashed.
- LDAP dependencies removed from code and configuration.

## Table of Contents
1. Environment requirements
2. Deployment steps
3. Important environment variables
4. Upgrade considerations
5. Operations checklist
6. Troubleshooting

## 1) Environment Requirements
- Docker 20.10 or newer
- Docker Compose 2.0 or newer
- Reachable MySQL 8.0 (or equivalent) database
- SMTP server (ports 25, 465, or 587)
- At least 10 GB free disk space

Default exposed ports:
- 12010 — Flask web service
- 12011 — ONLYOFFICE Document Server
- 12012 — Redis (restrict if not needed externally)
- 12013 — Nginx reverse proxy (if enabled)

## 2) Deployment Steps
1. Clone the repository
   ```bash
   git clone <repository-url>
   cd TEMP_spec_system_noad
   ```
2. Configure environment variables
   Edit the `.env` in the project root and set database, SMTP, ONLYOFFICE, and optional notification values.
3. Review `.env` values
   - `DATABASE_URL` e.g. `mysql+pymysql://user:pass@host:port/dbname`
   - `DEFAULT_NOTIFICATION_EMAILS` optional fallback recipients (semicolon‑separated)
   - SMTP settings (server, port, TLS/SSL toggle, credentials)
   - ONLYOFFICE URLs and JWT secret (if the service runs elsewhere)
4. Start the stack
   ```bash
   docker-compose up -d --build
   ```
5. Initialize the database (destructive — drops and recreates tables)
   ```bash
   docker-compose exec app python init_db.py
   ```
6. Sign in
   Use the seeded `egg / 123` account (name: 念萱, role: Viewer), then promote an account to Admin and create additional users.

Optional: if Docker Hub rate limits or requires auth on your host, set a mirror for the Python base image before building. For example:
```bash
set PY_BASE=mirror.gcr.io/library/python:3.10-slim   # Windows PowerShell
docker-compose up -d --build
```

## 3) Important Environment Variables
| Variable | Description |
|----------|-------------|
| `DATABASE_URL` | SQLAlchemy connection string |
| `DEFAULT_NOTIFICATION_EMAILS` | Optional default recipients for scheduled reminders |
| `SMTP_*` | Mail server configuration |
| `ONLYOFFICE_URL` / `ONLYOFFICE_INTERNAL_URL` | Document server endpoints |
| `ONLYOFFICE_JWT_SECRET` | JWT shared secret for document editing |
| `SECRET_KEY` | Flask secret key |
| `REDIS_URL` | Redis connection string used by caching and scheduling |

## 4) Upgrade Considerations
1. `init_db.py` truncates data; replace with migrations in production environments.
2. Migrating from LDAP requires importing user records into `tst_user`, supplying `name`, and setting passwords.
3. Replace any old LDAP‑driven notification lists with explicit email addresses.
4. Remove legacy `LDAP_*` variables from deployment manifests and set `DEFAULT_NOTIFICATION_EMAILS` if needed.

## 5) Operations Checklist
- Verify APScheduler jobs run successfully (check logs for `Running scheduled task`).
- Back up the MySQL database and the `uploads/` and `static/generated/` directories.
- Monitor CPU, memory, disk usage, and container health within existing monitoring tools.
- Enforce HTTPS via Nginx, apply strong password policies, and restrict Redis/ONLYOFFICE exposure.

## 6) Troubleshooting
| Issue | Possible cause | Suggested action |
|-------|----------------|------------------|
| Docker build 401 on base image | Registry rate limit or auth needed | Run `docker login` in Docker Desktop/CLI; retry later due to rate limiting; or set `PY_BASE=mirror.gcr.io/library/python:3.10-slim` and rebuild |
| Cannot log in | Bad credentials or disabled account | Reset the password via the admin console |
| Emails not delivered | Wrong SMTP settings or recipients | Review `.env` values and mail server logs |
| Scheduler not running | Redis or APScheduler misconfigured | Inspect container logs and Redis connectivity |
| ONLYOFFICE fails to load | Document server unavailable | Confirm the container is healthy and URLs are correct |