Update a Service
An existing Service keeps its own saved Compose definition. Changes to Coolify's one-click template catalog affect newly created Services; Coolify does not merge those changes into a Service you already deployed.
Updating can require more than changing an image tag. Review upstream release notes for new environment variables, removed components, Compose changes, migrations, and compatibility requirements before changing production.
Clone the Service or create another instance of the same one-click template, then test the target version there. Cloning copies configuration, not volume contents, bind-mounted files, database records, or external-service data. Restore representative data separately when the update includes a state migration.
Choose the update path
| Current configuration | Update path |
|---|---|
| Image uses a pinned version tag | Change the tag and any required Compose settings deliberately. |
Image uses a mutable tag such as latest | Use Pull Latest Images & Restart only when pulling the current image behind that tag is intentional. |
| New release changes services, variables, mounts, commands, or migrations | Compare the complete upstream or one-click template and merge every required change into Source Compose. |
Prepare the update
- Identify the exact current and target versions for every component being changed.
- Read the upstream changelog and migration guide for each version between them.
- Check for added or removed environment variables, components, volumes, ports, commands, health checks, and proxy requirements.
- Save a copy of Source Compose and record the current domains, environment variables, storage, scheduled tasks, and component settings.
- Back up every stateful component with a method you have tested restoring.
- Prepare a separate Service for the trial update and restore representative data when compatibility depends on existing state.
Do not rely on a Docker volume as the only backup. A failed migration can change data inside a volume while leaving the volume itself intact.
Apply the update
Change the version deliberately
- Open Configuration > General > Edit Compose File.
- Change the required image tag in Source Compose.
- Apply every accompanying Compose or configuration change required by the upstream release.
- Select Save.
- Review the reparsed component cards, Environment Variables, Persistent Storages, and Show Deployable Compose.
- Fill new required variables and confirm that removed references are no longer needed.
- Deploy the trial Service and follow its deployment output.
Saving Compose reparses referenced environment variables. Review the resulting Environment Variables page rather than assuming that a newly added reference has the correct production value.
Verify the trial update
Confirm that:
- every required component remains running and healthy
- component logs show the expected application versions
- migrations and initialization steps completed successfully
- public domains reach the intended components
- database, cache, queue, worker, and internal API connections succeed
- existing persistent data is present and writable
- scheduled tasks and background jobs complete normally
- logs contain no repeated compatibility, permission, or startup errors
Exercise the workflows that matter to the application, not only its landing page. Keep the production Service unchanged until the trial update and restore procedure are verified.
Update production
- Schedule maintenance when the update can interrupt traffic or modify persistent state.
- Create a fresh production backup and confirm its completion.
- Apply the Compose and environment changes already tested in the trial Service.
- Deploy or use the verified image-pull action.
- Follow the deployment output and repeat the trial verification checks against production.
Do not delete the backups, previous Compose definition, or recorded image versions immediately after deployment. Keep them for the recovery period required by your application and data-retention policy.
Roll back safely
If the release changed only container images and did not perform an incompatible data migration, restore the previous Compose definition and pinned image tags, then deploy again.
If the update changed database schemas, files, or other persistent state, changing the image tag back might not restore compatibility. Follow the upstream downgrade procedure or restore the verified pre-update backup into the matching previous application version.
Use Service troubleshooting when a deployment, component, connection, or domain fails during verification.