---
title: 'Post-Deploy Tasks: Placement and Execution | Shopware Community Hub'
description: >-
Learn how to distinguish post-deploy work from build-time tasks, choose the
right execution pattern, and troubleshoot failures by phase so that follow-up
work…
canonical_url: 'https://hub.shopware.com/learn/unit/post-deploy-tasks-placement-and-execution'
---
# Post-Deploy Tasks: Placement and Execution
- Distinguish post-deploy work from build-time tasks and decide where a task belongs.
- Choose the appropriate execution pattern for post-deploy tasks, from hooks to interactive commands and automation.
- Apply post-deploy tasks such as migrations, cache handling, and indexing in the correct phase.
- Troubleshoot issues by identifying the correct phase before investigating details.
# Post-Deploy Tasks: Placement and Execution
After a deployment finishes, the application is not always ready for normal use.
Shopware projects often still need follow-up work such as migrations, cache warm-up, indexing, or project-specific console commands. If that work is missing or fails, the deployment may be technically finished while the shop is still not in a healthy state.
In this learning unit, you learn what counts as post-deploy work, how to choose the right execution pattern, and how to troubleshoot failures.
The key question is always the same: does this task belong after deployment at all, or should it already happen during the build?
## What Counts as Post-Deploy Work
Post-deploy tasks are actions that run against the deployed application or its live data after a build has already been applied.
That boundary matters because not every operational task belongs here:
- Post-deploy work happens after the application is available in its target environment.
- Build work happens earlier while the artifact is still being created.
Typical sequencing after a successful deploy looks like this:
```mermaid
flowchart TD
D[Deploy successful] --> M[Run required migrations]
M --> C[Clear or warm caches]
C --> I[Run indexing or queue follow-up]
I --> V[Verify application health]
```
This distinction is critical: not every operational task belongs to post-deploy. Misplacing tasks here is a common source of deployment issues.
In real Shopware projects, common post-deploy tasks include:
| Task | Why it belongs here |
|-----------------------------------|----------------------------------------------------------------------------|
| `bin/console` migrations | They act on the target database state after the new code is in place. |
| Cache clear or warm-up | They refresh runtime state after code or configuration changes. |
| Indexer or queue follow-up | They help rebuild derived data after larger imports or structural changes. |
| Project-specific console commands | Some projects need explicit follow-up commands after deployment. |
One of the most common mistakes is placing theme or storefront compilation in post-deploy.
In most setups, this belongs to the build phase, not after deployment. Only treat it as post-deploy work when your project explicitly requires it and your team understands the trade-offs.
**Rule of thumb:** First, decide whether a task belongs after deployment at all and only then decide how to run it.
## Choose the Right Execution Pattern
Once you have decided that a task belongs after deployment, the next step is to choose how to execute it.
In practice, there are two main cases:
- The task is part of every rollout and should happen the same way each time.
- The task is a one-off action for maintenance, verification, or debugging.
Use the following patterns accordingly:
| Pattern | Use it for | Why it fits |
|----------------------------|----------------------------------------------------------------------------------------|-----------------------------------------------------------------------------|
| Deploy or post-deploy hook | Repeatable tasks that belong to the normal rollout | Keeps every deployment consistent. |
| `sw-paas exec --new` | Interactive debugging or one-off `bin/console` work in an existing application context | Good when you need direct, short-lived access. |
| `sw-paas command create` | Longer-running or asynchronous commands | Better for automation and non-interactive jobs. |
| UI command execution | Browser-based access to the same application context | Useful when you need the same mental model without working in the terminal. |
The default working directory for many command executions is `/var/www/html`. Adjust paths if your project layout differs.
Hooks should be safe to repeat. If a deployment retries, duplicate migrations or destructive commands such as `setup:install` must not run twice.
Prefer Shopware's intended migration and maintenance commands.
That makes the practical decision easier: Use hooks for repeatable rollout behavior, and use direct command execution for exceptions, checks, or troubleshooting.
## Examples in Real Shopware Projects
The exact commands vary by project, but the decision pattern stays the same.
These examples show how post-deploy decisions apply in real projects.
### Shopware Version Updates
Shopware version updates are a good example of coordinated post-deploy work. A typical high-level flow is:
1. Create a snapshot.
2. Update the Composer dependencies in a branch.
3. Run `bin/console system:update:prepare`.
4. Deploy the updated application.
5. Run `bin/console system:update:finish`.
The important lesson is not the exact command order alone. It is that some project changes need explicit follow-up work after deployment so that database state and application state stay consistent.
For exact ordering, flags, and version-specific details, follow the official [Update Shopware](https://developer.shopware.com/docs/products/paas/shopware/guides/update-shopware.html) guide.
### OpenSearch After Enabling the Service
OpenSearch is the search engine service that can power product and storefront search on Native PaaS.
It is a useful example here because it shows the difference between infrastructure being available and application data actually being ready to use. Enabling the service in `application.yaml` and deploying the application does not backfill the index automatically.
After deployment, you still need to trigger indexing, for example with `bin/console dal:refresh:index --use-queue`, so that search reflects the current catalog.
For changes that always require specific indexes to be rebuilt, do not rely only on a manual reminder after deployment. In Shopware projects, migrations can register required indexing work. When `bin/console system:update:finish` runs as part of the normal update or post-deploy flow, that registered work can then be triggered as part of completing the deployed change.
This pattern is useful when indexing is not optional but part of making the deployment complete. A manual `dal:refresh:index --use-queue` command is still useful for explicit maintenance or recovery, but required indexing should be part of a repeatable deployment process whenever possible.
This is a good reminder that a successful deployment does not automatically complete every application-specific follow-up task.
## Troubleshooting Post-Deploy Problems
When something goes wrong, always start by asking: in which phase did this happen?
That question keeps you from troubleshooting everything at once and reconnects this unit to the deployment model from the previous lesson.
Use this order:
1. **Check the build log.**
Start here if you are not sure the artifact was created successfully. Typical issues are Composer authentication, missing extensions, or asset build failures.
2. **Check the deploy log.**
Move here when the artifact exists, but deployment or follow-up tasks fail. Typical examples are migration exceptions or plugin boot problems.
3. **Check runtime observability.**
Use this step when deployment finished but the application still behaves badly. In the next course, you will use Grafana and logs for symptoms such as PHP fatals, OOM events, or HTTP failures.
4. **Revisit rollback last.**
Only think about rollback after you understand the failure phase. As explained in the previous learning unit, rollback means redeploying a known-good build.
This sequence keeps post-deploy troubleshooting grounded in the same mental model as the previous unit: first identify the phase, then investigate the likely cause inside that phase.
## Check Your Understanding
Use these questions to check the two core rules from this learning unit: what really counts as post-deploy work, and why repeatable tasks must be safe to run more than once.
Which task most clearly belongs to post-deploy work?
Installing Composer dependencies while the image is being built
Running database migrations against the deployed application's target database
Packaging storefront assets into the build artifact before deployment
Why should post-deploy hooks be idempotent?
Because a deployment should always recreate the whole database from scratch
Because the same deployment step may run again during retries, and duplicate destructive work must be avoided
Because idempotent hooks automatically replace rollback
## Summary
In this learning unit, you learned:
- Post-deploy work happens after deployment and must be separated from build-time tasks.
- Not every task belongs to post-deploy, so correct placement is the first decision.
- Different execution patterns fit different situations, from automated hooks to interactive commands.
- Troubleshooting starts by identifying the correct phase before investigating details.
With this understanding, you can handle post-deploy work more deliberately, choose the right execution pattern for each task, and investigate failures without confusing them with earlier build or deployment issues.