migrating-dockerfiles-to-chainguard

To convert a Dockerfile to use Chainguard images you should follow these steps:

1. Clarify instructions with the user
2. Convert the Dockerfile
   1. Modify FROM statements to use Chainguard images.
   2. Migrate any uses of other OS package managers to apk
   3. Adjust users and permissions where required.
3. Test the conversion
   1. Build the image
   2. Run the image
   3. Troubleshoot any failures

Clarify Instructions

If you're asked to convert a Dockerfile to Chainguard, before doing anything else, you should clarify the following with the user:

1. What is the Chainguard organization name? Each Chainguard customer has their own organization and it will be referred to generically as ORGANIZATION in these instructions.
2. Is FIPS required? Chainguard offers FIPS compliant images that have the suffix -fips. For instance: python-fips.
3. Should images be pulled directly from cgr.dev? Or, if images are hosted/proxied from another repository, what is that repository?
4. Should you test the conversion?
   1. Should you try and build the image to validate the conversion worked?
   2. Should you try and run the image to validate the conversion worked?

Store these answers under ~/.claude/chainguard-preferences.md and try and reuse this file across subsequent asks to migrate Dockerfiles.

Backup the Dockerfile

You should backup the old Dockerfile by prepending old. to it. For instance, Dockerfile -> old.Dockerfile.

Then you can modify the original file directly.

Converting FROM statements

You should replace images defined in FROM lines with the equivalent Chainguard image.

Always use the mapping-container-images-to-chainguard skill if it is available.

You should try to match to actively maintained tags when converting Dockerfiles.

You should prefer -dev tags as they have more utilities in them and they are less likely to cause issues. One known exception is chainguard-base which has no -dev variant. You should always use the latest tag for chainguard-base.