Publish curated ITWorx-ModelForge source from 990401737f96c8d46a9f7b0d84994516cadcb6a0
This commit is contained in:
Public Source Publisher committed
1 parent
7082ab955a
commit
848f0d8f8a
434 files changed
+67298
-4315
No files matched your search
+78
-15
@@ -1,9 +1,40 @@
|
||||
# Upgrading to the current ModelForge RC candidate
|
||||
# Upgrade boundaries — historical v1.2.3 procedure and current RC source
|
||||
|
||||
> RC schema note: the repository's temporary `1.2.1` version has **not** been released with
|
||||
> schema `20260830_0024`. Version selection/stamping is a separate pending release tranche. The
|
||||
> following preflight is the exact contract for rehearsing an existing stable v1.2.1/schema-0022
|
||||
> database before this candidate can be released; it must not be read as a READY announcement.
|
||||
> Status reconciled on 2026-09-23: no v1.2.3 Gitea Release object is published. The observed
|
||||
> production API is v1.2.3/schema `20260909_0032`; the current source line targets schema
|
||||
> `20260923_0037` and has not been production-qualified. The detailed commands below
|
||||
> retain the earlier v1.2.3/v1.2.2 schema-0024 and intermediate-RC instructions as historical
|
||||
> guidance; they are not an authorization to deploy current master or to claim migration-0037
|
||||
> recovery evidence. Use the current-state reconciliation and RC roadmap for the active candidate.
|
||||
|
||||
## Source and schema boundary
|
||||
|
||||
The schema numbers and commands in this section describe an earlier source snapshot. The current
|
||||
`1.3.0-rc.1` source targets `20260923_0037`, while the observed production database remains at
|
||||
`20260909_0032`. Rehearse that exact upgrade and recovery path before publishing the RC.
|
||||
|
||||
The previously documented v1.2.3 password hotfix was built from the v1.2.2 line and retains schema
|
||||
`20260830_0024`. The RC development branch containing this integration requires
|
||||
`20260908_0028`. A matching version string does not make these builds interchangeable:
|
||||
use the exact commit, image digests and reported schema contract.
|
||||
|
||||
For this RC source, the upgrade tool accepts schema 0021 through 0028 and targets 0028.
|
||||
In addition to the 0024 role boundary below, it applies migrations 0025 (configuration),
|
||||
0026 (project onboarding), 0027 (managed operator identities) and 0028 (platform secret slots).
|
||||
Back up and rehearse those migrations in the isolated RC environment before promotion;
|
||||
retain the external secret-slot root key for restore. Do not deploy the published schema-0024
|
||||
hotfix API against an RC database advanced to 0028. Rollback across that boundary requires
|
||||
restoring the matching verified database backup and application images.
|
||||
|
||||
The remaining release commands document the previously documented v1.2.3 hotfix. They are not an RC
|
||||
promotion instruction; use the separately maintained RC roadmap for its outstanding gates.
|
||||
|
||||
|
||||
v1.2.3 retains schema `20260830_0024` from v1.2.2 and adds operator password sign-in.
|
||||
An existing v1.2.2/schema-0024 installation needs no schema migration or runtime-worker update.
|
||||
Configure the password hash as described in [INSTALLATION.md](INSTALLATION.md), retain the
|
||||
bootstrap key, and deploy the verified API and web images. Earlier schema sources still require
|
||||
the provisioning and migration procedure below. Publication alone does not promote production.
|
||||
|
||||
## Required v1.2.1/schema-0022 role provisioning before migration 0024
|
||||
|
||||
@@ -19,7 +50,16 @@ application migration must not mint or retain an administrator credential.
|
||||
`modelforge` migration/schema owner, and NOINHERIT `modelforge_runtime` API role. Set
|
||||
`MODELFORGE_POSTGRES_ADMIN_USER` to a new retained name such as `modelforge_admin`; set the three
|
||||
password variables and both owner/runtime SQLAlchemy URLs documented in `CONFIGURATION.md`.
|
||||
3. Recreate only the PostgreSQL container so those values are in its environment. It may report
|
||||
3. Determine whether the existing `modelforge` role is PostgreSQL's protected bootstrap
|
||||
superuser before changing anything:
|
||||
|
||||
```sql
|
||||
select oid, rolsuper, oid = 10 as protected_bootstrap
|
||||
from pg_roles where rolname = 'modelforge';
|
||||
```
|
||||
|
||||
If `protected_bootstrap` is false, recreate only the PostgreSQL container so the new values are
|
||||
in its environment. It may report
|
||||
unhealthy until the new admin role exists; that is expected during this bounded downtime. While
|
||||
still connecting with the existing v1.2.1 `modelforge` bootstrap superuser, run:
|
||||
|
||||
@@ -29,11 +69,34 @@ application migration must not mint or retain an administrator credential.
|
||||
< deploy/postgres/provision-existing-1.2.1.sql
|
||||
```
|
||||
|
||||
The script first creates the retained administrator, then preserves the existing `modelforge`
|
||||
Compose exposes the five `MODELFORGE_*` provisioning variables to this bounded `psql` process;
|
||||
no value is printed. The script first refuses a protected OID-10 owner before any mutation,
|
||||
otherwise creates the retained administrator and preserves the existing `modelforge`
|
||||
role OID/table ownership while demoting it to a non-superuser, creates the distinct non-owner
|
||||
runtime role, and purges stale memberships that would still permit `SET ROLE`. Passwords are
|
||||
read from process environment; none is in the SQL file.
|
||||
4. Run only the one-shot migration service. Its environment contains
|
||||
4. If `protected_bootstrap` is true, do **not** edit `pg_authid`. PostgreSQL intentionally prevents
|
||||
demotion of OID 10. Use this recoverable cluster migration instead:
|
||||
|
||||
1. Keep the verified ModelForge backup and create a second PostgreSQL custom-format logical dump
|
||||
with `--no-owner --no-privileges --serializable-deferrable`; prove `pg_restore --list` can
|
||||
read it and record its SHA-256.
|
||||
2. Stop all application writers. Preserve the old PostgreSQL volume unchanged as the rollback
|
||||
source. Bind `postgres-data` to a new, empty, explicitly named volume in a deployment-local
|
||||
Compose override.
|
||||
3. Start PostgreSQL with `MODELFORGE_POSTGRES_ADMIN_USER` as the cluster bootstrap user. The
|
||||
committed init script creates the non-superuser `modelforge` owner and NOINHERIT
|
||||
`modelforge_runtime` role.
|
||||
4. Restore the logical dump into the empty `modelforge` database while directly authenticated as
|
||||
`modelforge`, using `pg_restore --no-owner --no-privileges --exit-on-error
|
||||
--single-transaction`. Verify the source schema revision and authoritative row counts before
|
||||
migration.
|
||||
5. Continue with the one-shot migration below. Retain the old volume until the new deployment,
|
||||
state fingerprint and recovery point have passed the operator's rollback-retention window.
|
||||
|
||||
This is the expected path for older installations originally initialized with
|
||||
`POSTGRES_USER=modelforge`; it is not an exceptional permission bypass.
|
||||
5. Run only the one-shot migration service. Its environment contains
|
||||
`MODELFORGE_MIGRATION_DATABASE_URL` but not the runtime/admin URL:
|
||||
|
||||
```bash
|
||||
@@ -44,7 +107,7 @@ application migration must not mint or retain an administrator credential.
|
||||
directly authenticated non-superuser owner, `modelforge_runtime` is NOINHERIT/non-admin, and
|
||||
neither application role has an explicit role membership.
|
||||
The refusal explicitly says to run this v1.2.1-to-schema-0024 provisioning step.
|
||||
5. Start the API only after Alembic reaches 0024. Production startup checks live catalog truth:
|
||||
6. Start the API only after Alembic reaches 0024. Production startup checks live catalog truth:
|
||||
runtime role/ownership/admin flags, table/schema/database privileges, canonical function
|
||||
owner/SECURITY DEFINER/fixed search path/grants and exact body digest, PUBLIC execution, four
|
||||
exact origin-mode protection-trigger shapes, role memberships, and every unexpected executable
|
||||
@@ -53,7 +116,7 @@ application migration must not mint or retain an administrator credential.
|
||||
The live PostgreSQL privilege/function exercise is a managed-runner release gate. SQLite exercises
|
||||
only the defense-in-depth application Engine hooks and is never production proof.
|
||||
|
||||
Supported direct schema sources for this unreleased candidate are `20260827_0021`,
|
||||
Supported direct schema sources for v1.2.3 are `20260827_0021`,
|
||||
`20260828_0022`, and `20260830_0023`; the target is `20260830_0024`. Older releases require an
|
||||
intermediate upgrade to v1.0.0.
|
||||
|
||||
@@ -122,16 +185,16 @@ claimed. Record the measured downtime for your deployment.
|
||||
python scripts/upgrade.py --database-url postgresql+psycopg://user:pass@host:5432/modelforge --apply
|
||||
```
|
||||
|
||||
For the current candidate this reports `schema migrated: <source> -> 20260830_0024`. Runtime
|
||||
For v1.2.3 this reports `schema migrated: <source> -> 20260830_0024`. Runtime
|
||||
compatibility begins only after the scope validation, audit-chain checkpoint and PostgreSQL role
|
||||
boundary reach `0024`.
|
||||
|
||||
## 5. Start the new version
|
||||
|
||||
```bash
|
||||
MODELFORGE_VERSION=1.2.1 \
|
||||
MODELFORGE_API_IMAGE=modelforge-api:1.2.1 \
|
||||
MODELFORGE_WEB_IMAGE=modelforge-web:1.2.1 \
|
||||
MODELFORGE_VERSION=1.2.3 \
|
||||
MODELFORGE_API_IMAGE=modelforge-api:1.2.3 \
|
||||
MODELFORGE_WEB_IMAGE=modelforge-web:1.2.3 \
|
||||
docker compose -f docker-compose.yml -f docker-compose.production.yml up -d --no-build api web
|
||||
```
|
||||
|
||||
@@ -143,7 +206,7 @@ alternative for development or rehearsal only: pass `MODELFORGE_COMMIT`, `MODELF
|
||||
## 6. Verify
|
||||
|
||||
```bash
|
||||
curl -s http://127.0.0.1:8000/api/v1/version # expect 1.2.1 and your commit
|
||||
curl -s http://127.0.0.1:8000/api/v1/version # expect 1.2.3 and your commit
|
||||
curl -s http://127.0.0.1:8000/api/v1/health/ready
|
||||
```
|
||||
|
||||
|
||||
Reference in new issue
Block a user