chore(traefik): Clean up traefik staging directories on poweroff to prevent downgrade issues, fixes #8120 by Copilot · Pull Request #8135 · ddev/ddev

Copilot · 2026-02-12T20:24:01Z

The Issue

Fixes Clean up ~/.ddev/traefik/config after it's used or on stop/poweroff #8120

v1.25.0 uses ~/.ddev/traefik/{config,certs} as staging directories. When users downgrade to v1.24.10, leftover staging files cause broken sites because v1.24.10 doesn't expect these files.

How This PR Solves The Issue

This PR implements three key changes:

README Files: Created three README.txt files in pkg/ddevapp/global_dotddev_assets/traefik/ subdirectories (config/, certs/, custom-global-config/) that are automatically copied to ~/.ddev/traefik/ by the existing asset copying mechanism. These explain that the directories are staging areas and guide users to proper customization locations.
Cleanup on Poweroff: Added CleanupGlobalTraefikStaging() function that removes all files from the staging directories except README.txt when ddev poweroff is executed. This prevents downgrade issues while preserving helpful documentation.
Integration: Modified PowerOff() to call the cleanup function after stopping projects but before removing containers.

The README files are automatically placed by CopyEmbedAssets() via PopulateExamplesCommandsHomeadditions(), following the same pattern as other global assets (e.g., commands/host/README.txt).

Manual Testing Instructions

Start a DDEV project: ddev start
Verify README files exist:
- ~/.ddev/traefik/config/README.txt
- ~/.ddev/traefik/certs/README.txt
- ~/.ddev/traefik/custom-global-config/README.txt
Verify staging files are present:
- ~/.ddev/traefik/config/default_config.yaml
- ~/.ddev/traefik/certs/default_cert.crt (if using mkcert)
Run ddev poweroff
Verify only README.txt files remain in staging directories:
- ls ~/.ddev/traefik/config/ should show only README.txt
- ls ~/.ddev/traefik/certs/ should show only README.txt

Automated Testing Overview

Added two comprehensive tests:

TestTraefikStagingDirectoryCleanup - Integration test that:
- Starts a project to trigger config generation
- Verifies README files are created with correct content
- Verifies staging directories contain generated files
- Runs poweroff and confirms only README.txt files remain
TestCleanupGlobalTraefikStagingUnit - Unit test that:
- Tests cleanup logic in isolation without Docker
- Creates temporary test directories with files
- Verifies cleanup removes all files except README.txt
- Confirms README content is preserved

Release/Deployment Notes

Backwards Compatible: No breaking changes. Existing projects continue to work.
Automatic Migration: README files are installed automatically on first ddev start after upgrade.
Downgrade Safety: After running ddev poweroff on v1.25.0+, downgrading to v1.24.10 will no longer cause broken sites.
Documentation: All README files link to https://ddev.readthedocs.io/en/stable/users/extend/traefik-router/

Original prompt

This section details on the original issue you should resolve

<issue_title>Clean up ~/.ddev/traefik/config after it's used or on stop/poweroff</issue_title>
<issue_description>### Is there an existing issue for this?

I have searched the existing issues

Is your feature request related to a problem?

A little artifact of our use of ~/.ddev/traefik as a staging area (only) in v1.25.0 means that people who downgrade to v1.24.10 get broken site.

Describe your solution

Delete most of the the contents of ~/.ddev/traefik/config after it's pushed into the volume. This may affect tests, but it would fix this little artifact. (The README.txt below would still be there). This approach might mean that extra work would be done on ddev start, so an alternative is to just clean those up on ddev poweroff. Evaluate whether there's significant extra effort if this is done on start or poweroff.

A README.txt should be added to ~/.ddev/traefik/config explaining that this is just a staging directory for DDEV-generated configurations, and that actual changes by the user can be done in project traefik config and in custom-global-config. This README should have #ddev-generated in it

A similar README should go in the ~/.ddev/traefik/certs

Another README.txt should go in global traefik custom-global-config directory pointing to the docs for that and explaining what the directory is for.

The README files can be stored where other READMEs are, pkg/ddevapp/global_dotddev_assets
Each of these should point to the appropriate documentation in docs.ddev.com</issue_description>

Comments on the Issue (you are @copilot in this section)

Fixes Clean up ~/.ddev/traefik/config after it's used or on stop/poweroff #8120

💬 We'd love your input! Share your thoughts on Copilot coding agent in our 2 minute survey.

rfay

@copilot see how other usages in global_dotddev_assets work. Tthe README.txt for certs should be in global_dotddev_assets/traefik/certs and nothing extra needs to be done to put it there. Each of the README's can be README.txt, and they automatically get placed.

Copilot · 2026-02-12T20:40:49Z

@copilot see how other usages in global_dotddev_assets work. Tthe README.txt for certs should be in global_dotddev_assets/traefik/certs and nothing extra needs to be done to put it there. Each of the ...

Done! Restructured the README files to use automatic asset copying.

The README files are now in subdirectories matching the target structure:

global_dotddev_assets/traefik/config/README.txt
global_dotddev_assets/traefik/certs/README.txt
global_dotddev_assets/traefik/custom-global-config/README.txt

Removed all manual README installation code from PushGlobalTraefikConfig() since CopyEmbedAssets now handles this automatically via PopulateExamplesCommandsHomeadditions().

Commit: c2ab227

rfay · 2026-02-12T20:43:23Z

@copilot update the OP to use the format in .github/PULL_REQUEST_TEMPLATE.md

Copilot · 2026-02-12T20:45:19Z

@copilot update the OP to use the format in .github/PULL_REQUEST_TEMPLATE.md

Updated the PR description to follow the template format from .github/PULL_REQUEST_TEMPLATE.md.

The new description includes:

The Issue section with issue reference
How This PR Solves The Issue with detailed technical explanation
Manual Testing Instructions with step-by-step verification
Automated Testing Overview describing both integration and unit tests
Release/Deployment Notes covering backwards compatibility and migration

rfay · 2026-02-12T21:38:14Z

@copilot you failed to make staticrequired so need to check with golangci-lint or gofmt.

Copilot · 2026-02-12T21:41:38Z

@copilot you failed to make staticrequired so need to check with golangci-lint or gofmt.

Verified static checks pass:

✅ gofmt -l - All Go files are properly formatted
✅ No trailing whitespace in any modified files
✅ go build ./pkg/ddevapp - Package builds successfully
✅ All imports are used and correct

The CI environment doesn't have golangci-lint/markdownlint installed locally, but all basic formatting and build checks pass. The code is ready for CI to run the full static analysis suite.

github-actions · 2026-02-12T22:13:37Z

Download the artifacts for this pull request:

See Testing a PR.

stasadev

Looks good to me.

- Created README.txt files for ~/.ddev/traefik/config, certs, and custom-global-config - Added CleanupGlobalTraefikStaging() function to clean staging files on poweroff - Modified PushGlobalTraefikConfig() to install README files explaining directory purposes - Modified PowerOff() to call cleanup function - Added comprehensive test for README creation and cleanup behavior Co-authored-by: rfay <112444+rfay@users.noreply.github.com>

Added TestCleanupGlobalTraefikStagingUnit to verify the cleanup logic works correctly without requiring Docker integration. Co-authored-by: rfay <112444+rfay@users.noreply.github.com>

Moved README files into proper subdirectory structure within global_dotddev_assets/traefik/ so they are automatically copied by CopyEmbedAssets without manual code: - config/README.txt - certs/README.txt - custom-global-config/README.txt Removed manual README installation code from PushGlobalTraefikConfig since CopyEmbedAssets now handles this automatically via PopulateExamplesCommandsHomeadditions. Co-authored-by: rfay <112444+rfay@users.noreply.github.com>

Use package-level require with explicit t argument instead of require.New(t) which shadows the import name. Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

…cleanup - Add fileutil.PurgeDirectoryExcept() as a reusable helper - Simplify CleanupGlobalTraefikStaging() to use it instead of duplicated read-dir/loop/skip/remove blocks - Rewrite unit test to test PurgeDirectoryExcept directly - Remove spurious blank line in traefik.go Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

…alTraefikConfig - Move TestPurgeDirectoryExcept to pkg/fileutil/files_test.go where it belongs - Switch PurgeDirectory calls in PushGlobalTraefikConfig to PurgeDirectoryExcept to preserve README.txt during regeneration - Remove duplicate test from traefik_test.go Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

- Add util.Chmod call before os.RemoveAll in PurgeDirectoryExcept to match PurgeDirectory behavior and prevent cleanup failures on Windows - Replace assert with require in TestTraefikStagingDirectoryCleanup per coding style guidelines Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

- Replace ddev.readthedocs.io with docs.ddev.com in all three traefik README.txt files - Fix whitespace lint error in TestTraefikStagingDirectoryCleanup Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

- Remove inverted require.Contains on certs dir that would fail at runtime since certs are no longer cleaned and first file wouldn't be README.txt - Remove unnecessary leading newline to fix whitespace lint - Update certs README to not claim files are cleaned on poweroff Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

…ection The custom-global-config directory was using a hardcoded filename allowlist (README.md, local-auth.yaml.example) to exclude files from the "custom configuration" warning. This missed README.txt files with #ddev-generated, causing false warnings on ddev start. Switch to filterCustomConfigFiles/isCustomConfigFile which properly checks for the #ddev-generated marker, consistent with all other custom config detection in CheckCustomConfig. Also improve CLAUDE.md to emphasize using `make` and `make staticrequired` instead of direct go/linter commands. Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

Copilot AI assigned Copilot and rfay Feb 12, 2026

Copilot started work on behalf of rfay February 12, 2026 20:24 View session

Copilot AI changed the title ~~[WIP] Clean up ~/.ddev/traefik/config after usage~~ Clean up traefik staging directories on poweroff to prevent downgrade issues Feb 12, 2026

Copilot AI requested a review from rfay February 12, 2026 20:35

Copilot finished work on behalf of rfay February 12, 2026 20:35

rfay reviewed Feb 12, 2026

View reviewed changes

Copilot started work on behalf of rfay February 12, 2026 20:36 View session

Copilot AI requested a review from rfay February 12, 2026 20:41

Copilot finished work on behalf of rfay February 12, 2026 20:41

rfay changed the title ~~Clean up traefik staging directories on poweroff to prevent downgrade issues~~ Clean up traefik staging directories on poweroff to prevent downgrade issues, fixes #8120 Feb 12, 2026

Copilot started work on behalf of rfay February 12, 2026 20:44 View session

Copilot finished work on behalf of rfay February 12, 2026 20:45

rfay changed the title ~~Clean up traefik staging directories on poweroff to prevent downgrade issues, fixes #8120~~ chore(traefik): Clean up traefik staging directories on poweroff to prevent downgrade issues, fixes #8120 Feb 12, 2026

github-actions Bot added the maintenance label Feb 12, 2026

Copilot started work on behalf of rfay February 12, 2026 21:38 View session

Copilot finished work on behalf of rfay February 12, 2026 21:42

rfay force-pushed the copilot/clean-up-traefik-config branch from 9f4d574 to 2be8bc0 Compare February 13, 2026 18:04

rfay marked this pull request as ready for review February 13, 2026 18:04

rfay requested a review from a team as a code owner February 13, 2026 18:04

rfay requested a review from stasadev February 13, 2026 18:04

rfay force-pushed the copilot/clean-up-traefik-config branch from 322ae61 to b246bd5 Compare February 17, 2026 03:16

stasadev approved these changes Feb 18, 2026

View reviewed changes

Copilot AI and others added 10 commits February 18, 2026 11:45

test: add unit test for traefik staging cleanup logic

66a7b68

Added TestCleanupGlobalTraefikStagingUnit to verify the cleanup logic works correctly without requiring Docker integration. Co-authored-by: rfay <112444+rfay@users.noreply.github.com>

fix: resolve import-shadowing lint errors in traefik_test.go

4657df5

Use package-level require with explicit t argument instead of require.New(t) which shadows the import name. Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

fix: use docs.ddev.com URL in traefik READMEs, fix lint whitespace

eb88841

- Replace ddev.readthedocs.io with docs.ddev.com in all three traefik README.txt files - Fix whitespace lint error in TestTraefikStagingDirectoryCleanup Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

Don't remove the certs directory as it shouldn't do any harm

ba8830d

rfay force-pushed the copilot/clean-up-traefik-config branch from b246bd5 to 52b461c Compare February 18, 2026 18:45

rfay merged commit 01be38c into main Feb 19, 2026
37 of 43 checks passed

rfay deleted the copilot/clean-up-traefik-config branch February 19, 2026 00:32

chenrui333 mentioned this pull request Feb 23, 2026

ddev 1.25.1 chenrui333/homebrew-tap#4570

Closed

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Uh oh!

Uh oh!

chore(traefik): Clean up traefik staging directories on poweroff to prevent downgrade issues, fixes #8120#8135

chore(traefik): Clean up traefik staging directories on poweroff to prevent downgrade issues, fixes #8120#8135
rfay merged 11 commits into
mainfrom
copilot/clean-up-traefik-config

Copilot AI commented Feb 12, 2026 •

edited

Loading

Uh oh!

rfay left a comment

Uh oh!

Copilot AI commented Feb 12, 2026

Uh oh!

rfay commented Feb 12, 2026

Uh oh!

Copilot AI commented Feb 12, 2026

Uh oh!

rfay commented Feb 12, 2026

Uh oh!

Copilot AI commented Feb 12, 2026

Uh oh!

github-actions Bot commented Feb 12, 2026 •

edited

Loading

Uh oh!

stasadev left a comment

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

Uh oh!

Uh oh!

Conversation

Copilot AI commented Feb 12, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

The Issue

How This PR Solves The Issue

Manual Testing Instructions

Automated Testing Overview

Release/Deployment Notes

Is your feature request related to a problem?

Describe your solution

Comments on the Issue (you are @copilot in this section)

Uh oh!

rfay left a comment

Choose a reason for hiding this comment

Uh oh!

Copilot AI commented Feb 12, 2026

Uh oh!

rfay commented Feb 12, 2026

Uh oh!

Copilot AI commented Feb 12, 2026

Uh oh!

rfay commented Feb 12, 2026

Uh oh!

Copilot AI commented Feb 12, 2026

Uh oh!

github-actions Bot commented Feb 12, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

stasadev left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

Copilot AI commented Feb 12, 2026 •

edited

Loading

github-actions Bot commented Feb 12, 2026 •

edited

Loading