> ## Documentation Index
> Fetch the complete documentation index at: https://docs.minimus.io/llms.txt
> Use this file to discover all available pages before exploring further.
# Image Creator
> Create your own private image by customizing a standard Minimus image
Customize Minimus standard images using [Creator](https://images.minimus.io/creator) to meet your team's exact needs. Minimus private images can help you simplify Dockerfiles, install private certificate bundles, and more to reduce overhead for dev teams and streamline processes.
Minimus maintains a private image as any standard Minimus image with daily builds and package updates, to keep the private image fresh and free of vulnerabilities (whenever patches and updates are available).
## Creating a private image
Select any image from your Minimus subscription to begin. Only images listed in [your Minimus subscription](https://images.minimus.io/manage/subscription) will be shown.
You can add any number of packages to your starter image. All packages maintained in the Minimus package repository are available, including the Minimus Cryptographic Module for FIPS images.
The recommended process is as follows:
1. Review the SBOM of your starter image - expand the folder **starter image packages** in the right preview panel.
Packages included in the latest production version are marked and listed. Generally, other image lines of the starter image are already using other versions of these same packages.
2. Search the list of available add-on packages by name, description or version. For Python and PHP packages, you can select `auto` packages for Minimus to automatically pair versions and ensure package version compatibility. [Learn more](#auto-versioning-python-and-php-packages)
3. Select packages to add them.
For a FIPS-validated starter image, select FIPS-validated packages whenever available. Note that some packages are FIPS-neutral and are not offered in a FIPS-validated format. \
\
[Please contact our support team with any questions.](https://support.minimus.io/support/home) We're happy to walk you through the process.
4. Review the added packages in the right preview panel under the folder **added packages**.
5. In the right-panel preview, fine-tune your selection and remove packages, as needed.
The final number of packages added will depend on the package dependencies. Dependencies are detected at the build stage and will be listed in the private image SBOM.\
\
A maximum of 100 added packages are allowed.
You can add custom env variables (short for environment variables) to pass configuration settings into the container at runtime without hardcoding them in the image. These may include ports, credentials, modes, etc.
* Avoid duplicate keys as they will cause the build to fail. This is to protect against overrides that can interfere with the starter image configurations.
* You can add key-value pairs. Key-only variables (also, empty environment variables) are not accepted.
* Once you make your updates, your custom env variables are shown in the right preview panel, where you can review them and remove them if needed.
You can upload a new file bundle or add an existing file bundle from the file repository. File bundles are used to include public keys for internal PKIs (Public Key Infrastructure certificates), override default configuration files, and more.
* Once you add your file bundles, they will be shown in the right preview panel for review.
* [Learn more about managing your file bundles](/advanced-tooling/file-bundles)
The next step is to give your private image a name and optionally, provide a description. Your organization's tenant ID will be prepended to the image name to clearly indicate that it is private to your organization. Your image will also be marked with the label **private image**.
The image name must be 2–40 characters long and begin and end with a lowercase letter. Only lowercase letters, numbers, and hyphens are accepted.
Read the testing recommendations then save your image.
The following build & testing notes appear in the Minimus console:
* Your private image will only include image lines that build successfully. Image lines that run into package conflicts will be skipped to keep your private image error-free.
* Minimus recommends testing your private image thoroughly to ensure its functionality. Testing the image is needed to confirm that added packages and other changes did not introduce conflicts or other unexpected errors.
* Private images built from FIPS-validated starter images or using the FIPS module package add-on may not be FIPS compliant. Testing is required to confirm that the end result does not conflict with FIPS OpenSSL modules.
While the image is being built, its card will be shown in the Image Creator gallery with a status label - **in progress**. The build generally takes under 15 minutes, depending on the components.
When the image is ready, it will appear with the label **created** and will show a timestamp of when it was first created. Click the button **view image** to dive into the image card.
Testing your private image for functionality is the next step. Minimus standard images undergo strict unit testing as described in our [architecture article](/introduction/architecture). Since testing is particular to the exact components of the image, Minimus is not able to cover all testing requirements for private images.
## Package compatibility in private images
### Auto-versioning packages for Ruby, Python & PHP
Pairing the right package version with the image version can potentially get tricky. To save you the trouble, Minimus offers auto-versioning packages. Auto-versioning packages automatically detect and install a package version compatible with each of the starter image lines during the build of the private image.
Minimus currently offers Ruby, Python, and PHP auto-versioning packages. All auto-versioning package names end with the suffix `-auto` and their description has a fixed format:
```json General format theme={null}
Universal package for {package name} - automatically detects and installs a compatible version
```
```json Example theme={null}
Universal package for PHP XML extension - automatically detects and installs a compatible version
```
Examples of auto-versioning package names:
* PHP package names: `php-curl-auto`, `php-openssl-auto`, `php-zip-auto`
* Python package names: `py3-rsa-auto`, `py3-babel-auto`, `py3-extras-auto`
* Ruby package names: `ruby-securerandom-auto`, `ruby-swd-auto`, `ruby-timeout-auto`
Each package family appears together as a group to help users select the relevant version or the auto-package.
### Auto-version logic
The general logic of the auto-version packages is as follows:
1. If there is no conflict with the starter image, the auto package will select the `latest` package version for all private image lines. The `latest` version will progress as new package versions are released.
2. If the package is a dependency of another popular package, it will not offer an auto-version since it is not expected to be added directly. For example, `php-posix-config` is considered a dependency of `php-posix-auto`. Therefore there is no `php-posix-config-auto` option.
3. If a version of the package is already in use, the entire package family will be blocked. The package version used by the starter image's `latest` line will be indicated.
4. If the auto-package is selected but a compatible version is not found, Minimus Creator will skip it. The SBOM will still show the auto-package but not any specific version, to indicate that the package was skipped.
For example, the PHP Imagick extension only has versions for `php-8.4-imagick` or higher. If it is added to a PHP starter image, image line 8.5 will be built with the matching version `php-8.5-imagick`, and image line 8.4 will be built with the matching version `php-8.4-imagick`.
Image lines 8.3 and 8.2 will skip the package and their SBOM will only show the `php-imagick-auto` package without any specific version to indicate that the package was skipped.
### Handling package version conflicts
Minimus will attempt to build a private image for the newest version of each image line. If a particular image line runs into version conflicts with added packages, Minimus will skip it. The final private image will only include image lines that build successfully without errors.
To avoid broken builds, Minimus handles potential package version conflicts in private images automatically: Minimus will attempt to build a private image for every maintained image line of the starter image and skip image lines that don't build successfully.
### Mutable tags
Mutable tags (aka floating tags) refer to tags like `latest` that reference a different image over time. The version tagged as `latest` in the private image might not be the same as the starter image, as a consequence of the private image skipping image lines due to conflicts. The general rule is the most advanced version available is tagged as `latest`.
For example, the `latest` tag may refer to version `8.3` for a private image and version `8.4` for the starter image. This would happen if the private image skipped `8.4` due to compatibility issues. In this case, the mutable tag `8` would also refer to different image lines, and so forth.
## Managing private images
### Viewing your private images
To view a gallery of all your private images, go to [Image Creator](https://images.minimus.io/creator). Here you can create a new private image and edit and manage your existing private images.
Private images are also easy to identify in the image gallery:
* Private images are labeled as private images
* Private images always have a name that begins with the tenant ID, for example, `53/image-name`.
### Editing a private image
You can update the added packages and env variables for your private images. The starter image and image name are fixed and cannot be changed. Once updated, the private image will be rebuilt.
To edit a private image, go to [Image Creator](https://images.minimus.io/creator) and select **Edit** in the image menu.
### Deleting a private image
Private images are all about experimentation. Easily remove outdated or unhelpful private images from your Minimus console.
To delete a private image, go to [Image Creator](https://images.minimus.io/creator) and select **Delete** in the image menu.
## Troubleshooting failed builds
To view the build status for your private image, go to [Image Creator](https://images.minimus.io/creator). The image card will show the build status on the bottom left. If there were errors, click the status to view more details.
Creator reports build errors with a granularity level of the image line. If only some lines failed, the build status will be shown as **some lines created**. Expand the error message to view more specific details.
If all image lines failed, the build status will be shown as **image build failed**. Expand the error message to view more specific details per line.
Whatever the cause of the error, the status message will show the **trace ID** so you can [contact our team for assistance](https://support.minimus.io/support/home). The private image build may fail due to conflicts or incompatible components or another issue. Our team is at your service to help resolve the issues.
## Actions for private images
Minimus fully supports actions for private images created by Creator. [Learn more about actions](/remediate/actions)