Add custom fields + warranty plugin, rework settings into two-pane shell
Feature work from the 2026-07 session: Settings IA - Replace the flat 27-card settings hub with a persistent two-pane shell (SettingsLayout.vue): grouped, searchable left rail + content pane. - Nest all settings/* routes under the shell via router post-processing; shared nav catalog in settingsNav.js. Group by asset class (PCs, Printers, Equipment, Network) so per-type settings stop scattering. Custom fields (core) - customfields + customfieldvalues tables (migration 7d14), CRUD API at /api/customfields, per-asset value get/save. - Settings management page + reusable CustomFieldsSection (detail) and CustomFieldsInputs (form) wired into all four asset types. Warranty (new plugin) - plugins/warranty: warranties + warrantyassets (migration 7d15), derived coverage status, provider abstraction (manual now; Dell/Lenovo/HP stubs). - API CRUD + per-asset panel + report buckets; WarrantyPanel on all four detail pages; Warranties management page; Warranty report + Reports card. - Seed warranty.* permissions. Printer drivers - printerdrivers table (migration 7d13) linked to printer models; drivers now surface on the matching printer's detail page. Other - PCDetail rebalanced (Network + Status + Warranty + custom fields on the right). - Rename PCs list "Features" column to "Remote Access"; fix badge hover underline. - Drop equipment islocationonly field. - Centralize asset-type label/route maps into utils/assetTypes.js. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
This commit is contained in:
cproudlock
180
docs/DEPLOY-WINDOWS-IIS.md
Normal file
180
docs/DEPLOY-WINDOWS-IIS.md
Normal file
@@ -0,0 +1,180 @@
|
||||
# Deploy shopdb-flask to Windows IIS (MySQL 5.6)
|
||||
|
||||
Runbook for standing up a single-site instance on the production Windows Server
|
||||
that already runs the classic ASP shopdb, using IIS + HttpPlatformHandler +
|
||||
waitress, against the existing MySQL 5.6. This is the test-instance path; keep
|
||||
developing on the Linux dev box and redeploy as needed.
|
||||
|
||||
The Docker path in `DEPLOY.md` does NOT apply on Windows (gunicorn is Linux
|
||||
only, and there is no MySQL container here). This file replaces it for IIS.
|
||||
|
||||
Notation: `APP_ROOT` = the deploy folder, e.g. `C:\shopdb-flask`. The IIS site
|
||||
physical path must be `APP_ROOT` (where `wsgi.py` lives).
|
||||
|
||||
## 0. Prerequisites on the box
|
||||
|
||||
- Python 3.12 (same minor as dev). `py -3.12 --version` to confirm.
|
||||
- IIS with the **HttpPlatformHandler** module:
|
||||
https://www.iis.net/downloads/microsoft/httpplatformhandler
|
||||
- **URL Rewrite** module (only for the optional real-client-IP rule).
|
||||
- Network access to the MySQL 5.6 server.
|
||||
- If the box is air-gapped, you cannot `pip install` live. On the dev box run
|
||||
`pip download -r requirements.txt waitress -d wheels\` (on a matching
|
||||
Windows/Python target, or use `--platform` wheels), copy `wheels\` over, and
|
||||
install with `pip install --no-index --find-links wheels\ ...`.
|
||||
|
||||
## 1. Copy the code
|
||||
|
||||
Copy the repo to `APP_ROOT`, INCLUDING `frontend/dist` (the built SPA the API
|
||||
serves). Build it on dev first if stale:
|
||||
|
||||
```bash
|
||||
# on the dev box
|
||||
cd frontend && npm run build # produces frontend/dist
|
||||
```
|
||||
|
||||
Ship `frontend/dist` with the code (Node is not needed on the prod box).
|
||||
|
||||
## 2. Python venv + dependencies
|
||||
|
||||
```powershell
|
||||
cd C:\shopdb-flask
|
||||
py -3.12 -m venv venv
|
||||
venv\Scripts\python -m pip install --upgrade pip
|
||||
venv\Scripts\pip install -r requirements.txt
|
||||
venv\Scripts\pip install waitress
|
||||
```
|
||||
|
||||
The DB driver is `pymysql` (pure Python) so no C compiler / MySQL client libs
|
||||
are needed. `waitress` is the WSGI server (installed separately, same as the
|
||||
Docker image installs gunicorn separately).
|
||||
|
||||
## 3. Prepare MySQL 5.6 (the utf8mb4 gotcha)
|
||||
|
||||
MySQL 5.6 defaults cannot index utf8mb4 VARCHAR(255) columns (767-byte prefix
|
||||
limit) and often defaults the server charset to latin1. The schema is utf8mb4,
|
||||
so the server needs Barracuda + large-prefix, made durable in `my.ini` under
|
||||
`[mysqld]`, then restart the MySQL service:
|
||||
|
||||
```ini
|
||||
[mysqld]
|
||||
innodb_file_per_table = 1
|
||||
innodb_file_format = Barracuda
|
||||
innodb_large_prefix = 1
|
||||
```
|
||||
|
||||
Then create the database as utf8mb4 and a least-privilege app user:
|
||||
|
||||
```sql
|
||||
CREATE DATABASE shopdb_flask CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci;
|
||||
CREATE USER 'shopdb'@'%' IDENTIFIED BY 'CHANGE_ME';
|
||||
GRANT ALL PRIVILEGES ON shopdb_flask.* TO 'shopdb'@'%';
|
||||
FLUSH PRIVILEGES;
|
||||
```
|
||||
|
||||
Without the `[mysqld]` flags, `flask db upgrade` fails with error 1071
|
||||
("Specified key was too long"). The migration chain emits `ROW_FORMAT=DYNAMIC`
|
||||
per table (see `migrations/env.py`), which fits the 3072-byte prefix those
|
||||
flags unlock.
|
||||
|
||||
## 4. Configure secrets and connection (.env)
|
||||
|
||||
Create `APP_ROOT\.env` (loaded by `wsgi.py` via `load_dotenv()`). Keep secrets
|
||||
here, not in `web.config`. Lock the file's ACLs to the IIS app-pool identity +
|
||||
administrators.
|
||||
|
||||
```
|
||||
FLASK_ENV=production
|
||||
SECRET_KEY=<64+ random chars>
|
||||
JWT_SECRET_KEY=<another 64+ random chars>
|
||||
DATABASE_URL=mysql+pymysql://shopdb:CHANGE_ME@<mysql-host>:3306/shopdb_flask?charset=utf8mb4
|
||||
CORS_ORIGINS=https://<the site's own hostname>
|
||||
```
|
||||
|
||||
`ProductionConfig.validate()` refuses to boot if any of `SECRET_KEY`,
|
||||
`JWT_SECRET_KEY`, `DATABASE_URL`, `CORS_ORIGINS` is missing or left at a dev
|
||||
default. `CORS_ORIGINS` is the browser origin users hit (the IIS binding).
|
||||
|
||||
Generate a key: `venv\Scripts\python -c "import secrets;print(secrets.token_urlsafe(64))"`.
|
||||
|
||||
## 5. Initialize schema, data, plugins, admin
|
||||
|
||||
Run from `APP_ROOT` with the venv active and `.env` present:
|
||||
|
||||
```powershell
|
||||
$env:FLASK_APP="shopdb"
|
||||
venv\Scripts\flask db upgrade
|
||||
venv\Scripts\flask seed reference-data
|
||||
|
||||
# Enable the plugins this site tracks (registry lives in the gitignored
|
||||
# instance/plugins.json, so a fresh box starts with none enabled):
|
||||
venv\Scripts\flask plugin list
|
||||
venv\Scripts\flask plugin install computers
|
||||
venv\Scripts\flask plugin install equipment
|
||||
venv\Scripts\flask plugin install network
|
||||
venv\Scripts\flask plugin install notifications
|
||||
venv\Scripts\flask plugin install printers
|
||||
venv\Scripts\flask plugin install usb
|
||||
venv\Scripts\flask plugin install knowledgebase
|
||||
venv\Scripts\flask plugin install slides
|
||||
venv\Scripts\flask plugin install employees
|
||||
|
||||
# First admin (password is generated and printed once):
|
||||
venv\Scripts\flask seed admin --username admin --email admin@yourfacility.example.com
|
||||
```
|
||||
|
||||
(Alternatively copy the dev box's `instance/plugins.json` to `APP_ROOT\instance\`
|
||||
to reproduce the exact enabled set, then just run `flask plugin upgrade-all`.)
|
||||
|
||||
## 6. Create the IIS site + web.config
|
||||
|
||||
1. In IIS Manager, add a new **Site** (separate from the classic ASP site):
|
||||
- Physical path: `APP_ROOT`
|
||||
- Binding: a free port or a dedicated hostname (e.g. `https` 443 with the
|
||||
facility cert, or `http` on a test port like 8081 to start).
|
||||
- App pool: No Managed Code, and an identity that can read `APP_ROOT`.
|
||||
2. Copy `deploy\windows\web.config` to `APP_ROOT\web.config` and edit the paths
|
||||
(`C:\shopdb-flask` -> your `APP_ROOT`). It launches
|
||||
`waitress-serve --port=%HTTP_PLATFORM_PORT% wsgi:app` and sets
|
||||
`FLASK_ENV=production` + `PYTHONPATH`.
|
||||
3. Create `APP_ROOT\logs` for the HttpPlatform stdout log.
|
||||
4. Recycle the app pool / restart the site.
|
||||
|
||||
TLS terminates at the IIS binding. The optional URL Rewrite rule in the
|
||||
web.config sets `X-Forwarded-For` to the real client IP (HttpPlatformHandler
|
||||
otherwise forwards from loopback, so audit logs and the kiosk visitor-location
|
||||
feature would see 127.0.0.1). Drop that block if URL Rewrite is not installed.
|
||||
|
||||
## 7. Smoke test
|
||||
|
||||
```powershell
|
||||
# SPA loads:
|
||||
curl.exe -k https://<host>/ # returns index.html
|
||||
# API rejects an empty login with a validation error (health signal):
|
||||
curl.exe -k -X POST https://<host>/api/auth/login -H "Content-Type: application/json" -d "{}"
|
||||
# expect JSON containing VALIDATION_ERROR
|
||||
```
|
||||
|
||||
Then log in through the browser as the admin from step 5 and confirm the
|
||||
dashboard renders.
|
||||
|
||||
## 8. Redeploying as dev advances
|
||||
|
||||
Because this is a test instance you keep iterating on:
|
||||
|
||||
1. Pull/copy new code to `APP_ROOT` (rebuild `frontend/dist` on dev if the UI
|
||||
changed).
|
||||
2. `venv\Scripts\pip install -r requirements.txt` (if deps changed).
|
||||
3. `venv\Scripts\flask db upgrade` (if new migrations).
|
||||
4. Recycle the app pool.
|
||||
|
||||
## Troubleshooting
|
||||
|
||||
| Symptom | Cause / fix |
|
||||
|---|---|
|
||||
| Site 502 / process won't start | Check `APP_ROOT\logs\httpplatform*`. Usually a bad `processPath`, missing waitress, or `wsgi:app` not importable (set `PYTHONPATH`). |
|
||||
| Boots but SQL echoes / debug on | `FLASK_ENV` not `production` (web.config env var or `.env`). |
|
||||
| `flask db upgrade` error 1071 | MySQL 5.6 `[mysqld]` flags in step 3 not applied / server not restarted. |
|
||||
| ConfigError on boot | A required var (SECRET_KEY / JWT_SECRET_KEY / DATABASE_URL / CORS_ORIGINS) missing or left at a dev default in `.env`. |
|
||||
| Login works, CORS errors in browser | `CORS_ORIGINS` does not match the exact origin (scheme + host + port) the browser used. |
|
||||
| Audit logs show 127.0.0.1 | Expected without the URL Rewrite X-Forwarded-For rule (step 6). |
|
||||
@@ -59,6 +59,14 @@ docker compose exec api flask db upgrade
|
||||
|
||||
This applies the baseline migration (creates all tables) and any subsequent migrations. Re-running is idempotent.
|
||||
|
||||
**Charset:** the schema is utf8mb4 (`utf8mb4_unicode_ci`). The docker-compose `db` service sets `--character-set-server=utf8mb4`, so the auto-created `shopdb_flask` database is utf8mb4. If you point at an external MySQL instead of the bundled container, create the database as utf8mb4 first, or it inherits the server default (often latin1) and the schema silently drifts:
|
||||
|
||||
```sql
|
||||
CREATE DATABASE shopdb_flask CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci;
|
||||
```
|
||||
|
||||
`DATABASE_URL` must keep `?charset=utf8mb4` so the connection matches. On MySQL older than 5.7 also enable `innodb_large_prefix=ON` + `innodb_file_format=Barracuda`, or the utf8mb4 indexes exceed the 767-byte prefix limit (error 1071). MySQL 5.7+ and 8.0 need no extra config.
|
||||
|
||||
## Step 4: Seed reference data
|
||||
|
||||
```bash
|
||||
|
||||
@@ -21,7 +21,12 @@ The codebase today is single-tenant per deployment. There is no `siteid` column,
|
||||
|
||||
Each site:
|
||||
|
||||
- Owns its database (own credentials, own backup policy, own retention)
|
||||
- Owns its database (own credentials, own backup policy, own retention). The
|
||||
database charset is part of the contract: it must be **utf8mb4**
|
||||
(`utf8mb4_unicode_ci`). The migration chain creates every table utf8mb4, and
|
||||
the connection pins `?charset=utf8mb4`. A site that creates the database with
|
||||
a different default charset (older MySQL defaults to latin1) gets a schema
|
||||
that silently diverges from every other site. See `docs/DEPLOY.md`.
|
||||
- Picks its own enabled plugins
|
||||
- Configures its own JWT secret, CORS allowlist, Zabbix integration, Active Directory binding
|
||||
- Deploys at its own cadence
|
||||
|
||||
Reference in New Issue
Block a user