Separate local development from installed infrastructure#
Ordinary consumer development runs through the application's Aspire AppHost. The isolated development composition starts the API, Web, local identity and declared supporting resources with known local registration. It should not require deploying the production Infrastructure bundle just to implement an application feature.
Shared development is a different explicit mode. It uses supplied authority, client, policy and endpoint inputs; it does not create a new shared identity provider or seed synthetic users into one. Select the mode deliberately and preserve the exact issuer, callbacks and TLS checks in either case.
Pin and verify the application baseline#
Before publishing, record the adopted Matrix packages, matching toolkit and application release identity. Ordinary builds consume published bytes. Coordinated candidate testing uses an explicitly isolated feed/cache and must not silently replace a published version with different bytes.
Run the application's verification gates and inspect the generated identity definition and deployment output. The identity definition is a request for registration, not authority to provision itself. Exported application scripts must never execute with infrastructure management credentials.
For the versioned Aspire recipe, publication is distinct from deployment:
aspire publish --environment Production -o aspire-output/release-reviewThis is the documented artifact-generation step, not a complete release script. Use the selected application's matching SDK/CLI and publication workflow. Build/push, artifact generation, identity apply and runtime startup are separate operations with their own inputs and results.
Inspect the production composition#
| Concern | Required result |
|---|---|
| Application services | Only the intended API, Web and explicitly required workers/jobs |
| Identity | Installed canonical HTTPS issuer, exact clients and callback contract |
| Ingress | Intended Web frontend only, with exact proxy trust and canonical host |
| API and data services | Private reachability through declared capability networks |
| Secrets | Runtime inputs separated from provisioning and migration credentials |
| Persistence | Explicit existing volumes and suitable protected Web key storage |
| Images | Reviewed immutable release references and recorded digests |
Development identity containers, fixture users and seed passwords must not become production defaults. Production application composition references the installed foundation rather than embedding another CA, identity service or ingress proxy. Preserve required backend network memberships when adding a frontend ingress attachment.
Validate final artifacts both as public placeholder-bearing configuration and with actual private values through a non-printing validation path. A placeholder-preserving export cannot sanitize secrets already embedded in source configuration. Keep provisioning credentials out of runtime environments, images and shared release artifacts.
Plan, deploy, verify and enable#
- Prepare the environment handoff. The operator supplies the exact target, trust, identity policy, resource allocations and protected credential references. Application owners supply approved release artifacts and migrations.
- Plan against immutable inputs. The trusted deployment toolkit binds the settings, release, toolkit and selected target into a reviewable plan. Inspect ownership, changes and blockers before activation.
- Coordinate the operation. Use an installation/deployment lock across runners. A local process lock alone cannot coordinate multiple release agents.
- Apply only the reviewed scope. Reconcile identity through approved tools, run application migrations with their bounded migration identity, and start only the intended application composition.
- Verify actual behavior. Check canonical HTTPS, issuer/audience, login/logout, permitted and denied operations, API connectivity and application interactivity. Health alone does not establish a complete user journey.
- Enable discovery. Make the application eligible in Portal only after the relevant acceptance has passed. Retain sanitized receipts and the previous compatible release.
A CLI-managed Compose project does not automatically become a Portainer-managed stack. Choose the installed ownership model and use its supported update path. Background workers can produce effects on first start, so their activation conditions must be part of the release plan.
After an uncertain remote write, inspect state and the operation journal before creating a new plan. Do not automatically repeat mutations, rotate credentials or infer rollback. Application image rollback must respect database compatibility. Foundation changes, application deployments and data migrations may require different recovery procedures even when one operator coordinates them.