Environment Preparation¶
Applies to: All subscriptions
Purpose¶
Get every environment provisioned, installed and verified — so that no later stage is diagnosing an infrastructure problem while trying to test a business one.
Audience¶
Infrastructure engineers and the implementation engineer.
Prerequisites¶
- Technical Prerequisites signed off
- Environment Requirements satisfied
- Sandbox provider credentials issued
- Database and server access for the installer
Steps¶
1. Confirm the environment plan¶
| Environment | Purpose | Provider credentials |
|---|---|---|
| Development or sandbox | Integration build, mapping development | Sandbox |
| Test | Business validation, training, upgrade rehearsal | Sandbox |
| Production | Live compliance | Production, applied at stage 10 |
Production credentials are not applied until go-live. Every earlier stage runs against sandbox.
2. Provision¶
Follow Environment Requirements. Raise firewall changes now — they frequently have the longest internal lead time of anything in this stage.
3. Install¶
Follow the Installation Guide in order: host, database, migrations, configuration, front end, proxy.
4. Verify¶
Complete Post-Installation Verification in full, including the deliberate-failure tier. A system that fails usefully is what makes every later stage diagnosable.
5. Prove the environments are separated¶
Do this by attempting a call, not by reading configuration:
| Check | Method |
|---|---|
| Non-production cannot reach production credentials | Run the provider connection test and confirm it reaches only the sandbox |
| Environments are distinguishable to a user | Hostnames and any environment labelling differ |
| Configuration is recorded per environment | Held, and differences are deliberate |
6. Establish monitoring early¶
Configure Monitoring and Health Checks now, in every environment. Monitoring added at go-live has never been tested; monitoring added at stage 1 has been proving itself for weeks.
7. Record the baseline¶
| Record | Why |
|---|---|
| Application version | The reference for every future upgrade |
| Migrations applied | There is no ledger; keep your own |
| Configuration snapshot | For comparison and recovery |
| Verification results | The baseline every future upgrade is verified against |
Validation¶
Gate: this stage is complete when every one of these passes.
| Check | Pass condition |
|---|---|
| Every environment installed | Each passes post-installation verification in full |
| Cross-tenant check performed | Blocked, verified with two identities |
| End-to-end document | One document from ingest to registration to print, in the sandbox |
| Failure paths verified | Each deliberate failure produced a specific, actionable message |
| Environments separated | Verified by attempting a call, not by inspection |
| Monitoring live | Configured and alerting; an alert has been fired |
| Backup and restore proven | A restore performed into a scratch environment |
| Baseline recorded | Version, migrations, configuration, verification results |
Rollback¶
| Situation | Action |
|---|---|
| Installation fails partway | Do not patch over it. Clear the database and reinstall — a half-installed environment produces confusing failures for weeks |
| Migrations half-applied | Restore and re-apply. Verify counts against storage metadata |
| Wrong configuration deployed | Restore the recorded snapshot |
| The environment is fundamentally wrong-sized | Re-provision now. Correcting it after data exists is far harder |
Nothing here is irreversible, provided no production provider credentials have been used. That single constraint is what keeps this stage fully recoverable.
Common mistakes¶
| Mistake | Consequence | Avoid by |
|---|---|---|
| Production credentials in a non-production environment | A test document permanently registered at the government | Verify separation by attempting a call |
| Verifying only that services started | Silent failures survive into later stages | Complete the full verification, including failure paths |
| Skipping the cross-tenant check | A data-exposure defect ships | It needs two identities; create the second one |
| Testing network paths from a laptop | The server has different access | Test from the application host |
| Omitting the PDF rendering dependencies | Everything works until someone prints | Render a test document |
| Leaving monitoring until go-live | Untested monitoring at the moment it matters | Configure it now |
| Not recording the baseline | Every future upgrade starts from guesswork | Record it before moving on |
| Half-installing and continuing | Weeks of confusing failures | Start clean |
Troubleshooting¶
| Symptom | Cause | Action |
|---|---|---|
| Application refuses to start, naming an object | A migration was not applied | Run it. See Migrations |
| HTTP 502 through the proxy | Port mismatch | Align proxy and service |
| Uploads never complete | Worker or queue | Check both; no error appears in the interface |
| Provider connection test fails | Credentials, network, or an untrusted proxy certificate | See GSP Configuration |
| Printing fails, everything else works | Rendering dependencies absent | Install them on the host |
| Firewall changes delayed | Raised late | Raise them at the start of the stage |