94 lines
4.3 KiB
Markdown
94 lines
4.3 KiB
Markdown
# 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 |
|