updates to digiserver app server
This commit is contained in:
@@ -0,0 +1,140 @@
|
||||
# 06 · Utilities & Services
|
||||
|
||||
All shared services live in `app/utils/`. This document details each module, its main functions, and how they fit together.
|
||||
|
||||
---
|
||||
|
||||
## Overview Table
|
||||
|
||||
| Module | Community | Responsibility | Key symbols |
|
||||
|---|---|---|---|
|
||||
| `logger.py` | C0 | DB-backed audit logging | `log_action()`, `get_recent_logs()`, `clear_old_logs()` |
|
||||
| `group_player_management.py` | C0 | Group/player stats (legacy) | `get_player_status_info()`, `assign_player_to_group()`, `get_online_players_count()` |
|
||||
| `caddy_manager.py` | C1 | HTTPS Caddyfile generation | `CaddyConfigGenerator`, `write_caddyfile()`, `reload_caddy()` |
|
||||
| `background_tasks.py` | C10 | Async task execution | `run_background_task()`, `background_player_deployment()` |
|
||||
| `ssh_deploy.py` | C10 | Remote player provisioning | `deploy_player_to_host()`, `test_ssh_connection()`, `generate_player_config()` |
|
||||
| `player_build.py` | C11 | Stage player source code | `build_player_files()`, `write_base_config()`, `load/save_build_settings()` |
|
||||
| `pptx_converter.py` | C12 | PPTX → PDF → PNG | `pptx_to_pdf_libreoffice()`, `validate_pptx_file()`, `cleanup_libreoffice_processes()` |
|
||||
| `uploads.py` | C9 | Upload progress + file ops | `get/set/clear_upload_progress()`, `save_uploaded_file()`, `process_video_file()` |
|
||||
| `portal_sso.py` | C4 | SSO auto-login | `init_portal_sso()`, `_get_or_create_user()` |
|
||||
| `script_name_fix.py` | C4 | WSGI sub-path middleware | `ScriptNameFix` |
|
||||
| `nginx_config_reader.py` | C7 | Legacy nginx status parsing | `NginxConfigReader`, `get_nginx_status()` |
|
||||
|
||||
---
|
||||
|
||||
## 1. `logger.py` — Audit Logging ⭐ God Node (116 edges)
|
||||
|
||||
The most-connected module in the system. Every meaningful action across all blueprints is recorded here.
|
||||
|
||||
| Function | Purpose |
|
||||
|---|---|
|
||||
| `log_action(level, message)` | Create + commit a `ServerLog` row |
|
||||
| `log_info(message)` / `log_warning(message)` / `log_error(message)` | Convenience wrappers |
|
||||
| `get_recent_logs(limit, level)` | Query recent logs (used by dashboard/admin) |
|
||||
| `clear_old_logs(days)` | Housekeeping |
|
||||
|
||||
**Usage pattern:** admin actions (`reset_user_password`, `upload_header_logo`, `delete_editing_user`, `delete_playlist`, login failures, etc.) all funnel through `log_action()`.
|
||||
|
||||
---
|
||||
|
||||
## 2. `background_tasks.py` — Async Execution
|
||||
|
||||
| Function | Purpose |
|
||||
|---|---|
|
||||
| `run_background_task(func, *args)` | Spawns a **daemon thread** with a Flask app context pushed, then runs `func` |
|
||||
| `background_player_deployment(...)` | Runs SSH deployment in background; updates `player.deployment_status` (`deploying → deployed|failed`) |
|
||||
|
||||
Used by `players.add_player` to avoid blocking the HTTP request during long remote installs.
|
||||
|
||||
---
|
||||
|
||||
## 3. `ssh_deploy.py` — Remote Player Provisioning ⭐ (heat 0.614)
|
||||
|
||||
The deployment engine. Full pipeline implemented by `deploy_player_to_host(...)`:
|
||||
|
||||
```mermaid
|
||||
flowchart TD
|
||||
A["deploy_player_to_host()"] --> B["test_ssh_connection() (sshpass)"]
|
||||
B --> C["mkdir remote dir"]
|
||||
C --> D{"staged code present?"}
|
||||
D -- yes --> E["rsync pre-staged code"]
|
||||
D -- no --> F["git clone / pull"]
|
||||
E --> G["write config/app_config.json"]
|
||||
F --> G
|
||||
G --> H["temp passwordless sudo"]
|
||||
H --> I["run install.sh"]
|
||||
I --> J["run start.sh"]
|
||||
J --> K["cleanup sudoers"]
|
||||
K --> L["return steps[]"]
|
||||
```
|
||||
|
||||
Other helpers:
|
||||
- `get_local_player_code_status()` — inspect staged code state.
|
||||
- `detect_server_ip()` / `parse_server_address()` — resolve the server address players should reach.
|
||||
- `generate_player_config()` / `generate_app_config()` — write player's `config/app_config.json` with `server_ip`, `port`, `screen_name`, `quickconnect_key`, `orientation`, `use_https`, `verify_ssl`.
|
||||
|
||||
---
|
||||
|
||||
## 4. `caddy_manager.py` — HTTPS Automation ⭐ God Node
|
||||
|
||||
`CaddyConfigGenerator` produces the Caddyfile for the reverse proxy and reloads Caddy without restart.
|
||||
|
||||
| Method | Purpose |
|
||||
|---|---|
|
||||
| `generate_caddyfile(config)` | Pick template by mode: **HTTP-only** (`:80`), **domain** (Let's Encrypt), or **IP** (internal CA self-signed). Includes `reverse_proxy digiserver-app:5000`, 2 GB body limit, gzip, security headers |
|
||||
| `write_caddyfile(content, path=/etc/caddy/Caddyfile)` | Write to disk |
|
||||
| `reload_caddy()` | POST to Caddy admin API `http://caddy:2019/load` |
|
||||
|
||||
Triggered from `admin.update_https_config` after saving `HTTPSConfig`.
|
||||
|
||||
---
|
||||
|
||||
## 5. `player_build.py` — Staging Player Code
|
||||
|
||||
| Function | Purpose |
|
||||
|---|---|
|
||||
| `build_player_files(dir, repo_url, branch)` | Clone or `fetch + reset` the player repository into `PLAYER_CODE_DIR` |
|
||||
| `write_base_config(...)` | Write `config/app_config.json` (blank screen / quickconnect) |
|
||||
| `load_build_settings()` / `save_build_settings()` | JSON at `instance/player_build.json` |
|
||||
| `get_player_server_settings` / `make_build_record` / `get_short_head` | Build metadata helpers |
|
||||
|
||||
---
|
||||
|
||||
## 6. `uploads.py` — Upload & Media Processing
|
||||
|
||||
| Function | Purpose |
|
||||
|---|---|
|
||||
| `get_upload_progress` / `set_upload_progress` / `clear_upload_progress` | In-memory per-file progress (for the upload page) |
|
||||
| `save_uploaded_file` | Save a multipart upload |
|
||||
| `process_video_file` | FFmpeg → H.264 main, 30 fps, ≤1080p, faststart |
|
||||
| `process_pdf_file` | PDF processing (stub — real logic in content.py) |
|
||||
| `get_file_size` / `delete_file` | FS helpers |
|
||||
|
||||
---
|
||||
|
||||
## 7. `pptx_converter.py` — LibreOffice Integration
|
||||
|
||||
| Function | Purpose |
|
||||
|---|---|
|
||||
| `pptx_to_pdf_libreoffice(pptx_path, output_dir)` | Headless LibreOffice → PDF (300 s timeout) |
|
||||
| `validate_pptx_file()` | Validate a file is a real PPTX |
|
||||
| `cleanup_libreoffice_processes()` | `pkill soffice` — clean hanging processes |
|
||||
|
||||
Used by the upload pipeline: **PPTX → PDF → PNG slides (Full HD)**.
|
||||
|
||||
---
|
||||
|
||||
## 8. `portal_sso.py` & `script_name_fix.py` — Gateway Integration
|
||||
|
||||
- **`portal_sso.py`** — `before_request` reads `X-Auth-Username`/`X-Auth-Role` from the umbrella nginx and auto-logs-in the local user (creating it on first arrival). See [04 · Application Core §11](04-application-core.md#11-portal-sso--apputilsportal_sso_py).
|
||||
- **`script_name_fix.py`** — WSGI middleware mapping `X-Script-Name` → `SCRIPT_NAME` so `url_for()` is correct behind a path-prefixed gateway.
|
||||
|
||||
---
|
||||
|
||||
## 9. `nginx_config_reader.py` — Legacy (informational)
|
||||
|
||||
`NginxConfigReader` parses an `nginx.conf` and reports `ssl_enabled`, ports, upstreams, `server_names`, `ssl_protocols`, `client_max_body_size`, `gzip`. **Legacy** — the current reverse proxy is Caddy; retained for reference and the old deployment stack.
|
||||
|
||||
---
|
||||
|
||||
> Next: [07 · Deployment](07-deployment.md)
|
||||
Reference in New Issue
Block a user