Docs/212 rollout runbook - #229
Open
JanKolo04 wants to merge 2 commits into
Open
Conversation
A deployment procedure for warehousing and the ERP sync, written to be followed on a production install by someone who did not write the feature: - what actually changes on an existing install (and that code alone changes no behaviour until an admin enables the module), - pre-flight: backup, warehouse layout decisions, who owns stock, - deploy via compose rebuild or Admin → Updates, and why octane:reload matters, - migration verification, module + tab-access + default-warehouse configuration, - opening-stock load in dependency order, with a reconciliation query whose pass condition is zero rows, - ERP wiring: scope table, the sync order each step's codes depend on, dry-run first, and the poll/ack loop with suggested cadences, - a 10-step acceptance test with explicit pass conditions, - four rollback levels from "untick the module" to "drop the schema", noting what each one costs, - a gotcha table for the failures that actually happen. Every command and both SQL queries were run against the running stack, and all ten acceptance steps executed end to end: generation (2 drafts), posting (−86.52 kg / −1.6 kg), reconciliation (0 rows), cancellation (balances restored, ledger nets to zero over 4 movements), backlog → ack → backlog empty, and a repeated lot import converging (updated: 2 twice, global 2040.5 = warehouses 2040.5). Linked from docs/index.md, the admin guide's Warehouses chapter and the CHANGELOG. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
…epends on The procedure for putting OpenMES into a plant, end to end, for whoever runs the implementation: qualify and plan (the eight questions that change configuration), infrastructure and network, install, scoping the module set, master data in dependency order, people and access, shop-floor hardware, integrations, a two-week pilot on one line with explicit stop rules, go-live cutover, and handover with the tasks the plant then owns. Plus a go-live checklist, backup/restore, and a table of the failure modes that actually happen. Written against the real system, not from memory: the wizard's five steps, the three module presets, the roles that ship, the compose profiles (`connectivity`, `workers`), and the fact that the scheduler and a queue worker run inside the primary container so no host cron is needed. Two things the verification turned up: - **The restore command in the draft was wrong.** `psql -c "DROP DATABASE …; CREATE …"` runs both statements in one transaction block, which DROP DATABASE refuses. Fixed to separate `-c` flags, plus `ON_ERROR_STOP=1` so a half-restore fails loudly, a verification query, and a rehearse-into-a-scratch-database variant. Tested: dump → drop → create → restore reproduced every row count and all 231 migrations. - **`APP_TIMEZONE` never reached the containers.** `config/app.php` reads it, but `docker-compose.yml` did not pass it, so a Docker install was stuck on UTC and the runbook's "set the plant timezone" step was impossible to follow. Now passed to the app, Reverb, the connectivity daemons and the queue worker (default `UTC`, so existing installs are unchanged) and documented in `.env.example`. Verified live: `app.timezone=Europe/Warsaw`, `now()` returns local time. Suites green (2169 PHP, 25 frontend). Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
|
Important Review skippedAuto reviews are disabled on base/target branches other than the default branch. Please check the settings in the CodeRabbit UI or the ⚙️ Run configurationConfiguration used: defaults Review profile: CHILL Plan: Pro Plus Run ID: You can disable this status message by setting the Use the checkbox below for a quick retry:
Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out. Comment |
Collaborator
Author
|
@jakub-przepiora ready to review |
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
Two deployment runbooks, plus the one fix that makes one of them followable.
docs/implementation-runbook.md— end-to-end procedure for putting OpenMES into a plant: planning, infrastructure,install, module scoping, master data in dependency order, access, hardware, integrations, a two-week pilot with stop rules,
go-live, handover. Includes a go-live checklist, backup/restore and a failure-mode table.
docs/warehouse-erp-rollout.md— narrower runbook for rolling warehousing + ERP stock sync (API for integration #212) onto an existinginstall: opening-stock order, reconciliation query, 10-step acceptance test, four rollback levels.
APP_TIMEZONEnever reached the containers.config/app.phpreads it,docker-compose.ymldidn't pass it — so aDocker install was stuck on UTC and "set the plant timezone" was impossible. Now passed to the app, Reverb, the connectivity
daemons and the queue worker (default
UTC, so existing installs are unchanged) and documented in.env.example.Type of change
Related issue
Nothing to close. Supports the feature merged in #227 (discussion #212).
Testing
Every command in both runbooks was run against the live stack — which caught two errors in the drafts: the restore command
(
psql -c "DROP DATABASE …; CREATE …"runs in a transaction block, which DROP DATABASE refuses → separate-cflags +ON_ERROR_STOP=1, verified dump→drop→restore reproducing all row counts and 231 migrations) and the timezone gap above(verified after the fix:
app.timezone=Europe/Warsaw,now()local). Also ran the warehouse runbook's full 10-step acceptancetest end to end.
php artisan testpassesChecklist
.envsecrets committed$fillableupdated if new model columns addedcomposer auditclean