TEMP_spec_system_noad/DEPLOYMENT.md

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

   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

   docker-compose up -d --build
   

5. Initialize the database (destructive — drops and recreates tables)

   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:

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