> ## Documentation Index > Fetch the complete documentation index at: https://docs.scitix.ai/llms.txt > Use this file to discover all available pages before exploring further. # Build Custom Images > Build custom images in Siverse and configure image names, versions, build resources, dependencies, Dockerfiles, and build methods. Custom images let you maintain your own runtime environments. When preset images do not meet your requirements for framework versions, system dependencies, Python packages, or toolchains, you can create custom images based on existing images, Dockerfiles, third-party image registries, or previously built images. After a custom image is built, you can select it for development environments, training jobs, and inference services. ## Image Naming and URLs Custom images are typically distinguished by name, version, and commit ID. An image URL consists of the image registry address, project name, image name, version, and commit ID: ```text theme={null} //:- ``` | Field | Description | | - | - | | `harbor_url` | The image registry address, generated by the platform based on the region and cluster. | | `project_name` | The image registry project, typically generated by the platform based on the tenant or project ownership. | | `name` | The image name. Use lowercase letters, numbers, hyphens, or underscores, and choose a name that indicates the framework, purpose, or project. | | `version` | The image version, used to manage different versions of the same image. | | `commit_id` | The image tag or commit identifier, used to distinguish iterations that share the same name and version. | You can have multiple tagged versions under the same name and version. When creating a development environment, training job, or inference service, you typically select an image by name and version. If multiple tags exist for the same version, use the image URL selected and displayed on the current page. > [!TIP] > > For images used in production training or inference, or shared across a team, use a dedicated version number or commit ID to identify the source. Avoid relying only on `latest` for reproduction or rollback. When possible, record the image digest, code commit, and key dependency versions within the team to make issues easier to trace. ## Create Custom Images Building an image consumes instance resources. Before creating an image, confirm that build resources are available in the current region and cluster, and check image registry storage usage. If you plan to use the image across multiple clusters, configure image synchronization after creating or building it. > [!TIP] > > * Before building, identify the image's purpose, framework version, dependency versions, and target runtime cluster. For GPU workloads, also confirm that the instance hardware, CUDA version, framework version, and base image are compatible. > * Use trusted sources when working with third-party or private image registries. > * If registry credentials are required, grant only the minimum permissions needed to pull or import the image. ### 1. Go to the Create Page 1. Go to **Images > Custom**. 2. On the **Available Images** tab, click **Create**. ### 2. Configure the Settings #### Basic Information | Configuration Item | Description | | - | - | | Region | Select the region where the image will be built. | | Cluster | Select the cluster where the image will be built. | | Shared Project Groups | Configure the image's visibility scope. To share it with other Project Groups, click **Add Project Group**. If you do not add a Project Group, access is generally granted according to the default scope of the Project Group to which the user who starts the build belongs. | | Name | The image name. Use lowercase letters, numbers, hyphens, or underscores, and choose a name that indicates the framework, purpose, or project. | | Version | The image version, used to manage multiple versions of the same image. Use a stable, sortable version number and avoid spaces, slashes, or special characters. | | Commit ID | The image tag or code commit identifier, used to distinguish iterations that share the same name and version. Use the first few characters of the code repository's commit ID to make the source easier to trace. | | Image Type | The image category, such as `pytorch`, `base`, `python`, or `LLM`, used to classify and manage images. | | Labels | Used to search for and categorize images. | | Description | Describe the image source, purpose, framework version, dependencies, or usage restrictions. | #### Runtime Information | Configuration Item | Description | | - | - | | Resource Type | Select the billing type for resources used by the build task, such as **Reserved**, **On-demand**, or **Spot**. | | Instance | When using **Reserved**, select a resource pool. | | Instance Type and Quantity | **GPU** and **CPU** are supported. Select the instance specifications for the build task from the instance list, and configure **Count Per Node**. When selecting instances, pay particular attention to **Remaining Quota** and **Pool Available**. | | Resource Priority | Configure the scheduling priority after selecting instances. Instances are sorted from highest to lowest priority, and those listed first are used preferentially during scheduling. | #### Build Configuration First, select a build method, then enter the corresponding build configuration. Do not put long-lived keys in Dockerfiles, regular build arguments, or installation commands. Even if you later delete a file or command, sensitive content may remain in image layers, build history, or logs. **Based on an Existing Image** Use this method to add dependencies to a preset image or an existing custom image. | Configuration Item | Description | | - | - | | Base Image | Select a **Preset** or **Custom** image to use as the base image. | | Dependencies | Add system and Python dependencies in one of the following ways:
  • Add system packages in `apt`, such as `vim`.
  • Add Python 3 dependencies and versions in `pip3`.
  • Upload `apt.txt` and `pip.txt` files to import dependencies in batches.
| `apt.txt` and `pip.txt` are text files with one dependency per line. The dependency installation method must match the base image. **apt** is generally used for Ubuntu system dependencies, and **yum** is generally used for CentOS system dependencies. **pip2** and **pip3** are used for Python 2 and Python 3 dependencies, respectively. * Example `apt.txt`: ```text theme={null} python3=3.8.2-0ubuntu2 python3-pip=20.0.2-5ubuntu1.11 curl=7.68.0-1ubuntu2.25 wget=1.20.3-1ubuntu2.1 ``` * Example `pip.txt`: ```text theme={null} requests==2.31.0 flask==2.3.3 ``` **Based on a Dockerfile** Use this method to define the complete build logic in a Dockerfile. After selecting it, enter the Dockerfile contents and build arguments. Build arguments pass variables to the build process for use in the Dockerfile. To install **apt** or **pip** dependencies, you can: * Write the installation commands directly in the Dockerfile. * Add dependencies under Dependencies or upload `apt.txt` and `pip.txt`. After the platform returns the corresponding installation commands, copy them to the appropriate locations in the Dockerfile. Example: ```dockerfile theme={null} FROM ubuntu:18.04 RUN apt-get update && apt-get install -y --no-install-recommends \ python3-pip \ vim && \ apt-get clean && \ rm -rf /var/lib/apt/lists/* RUN pip3 install \ numpy==1.19.5 \ scipy==1.5.4 RUN ln -sf /usr/share/zoneinfo/Asia/Shanghai /etc/localtime ``` Copying content to a shared directory during the build is not currently supported. If the build depends on large files, private code, or model files, first decide whether to include them in the image or mount them from a Volume when the workload runs. **From a Third-Party Image Registry** When you select **Download from Third-Party Image Registry**, enter the external image address and confirm that the platform can access it. Use this method to copy images from public or cloud-provider image registries to the platform image registry for centralized use. If the external image requires authentication, confirm that the registry address, version, and authentication information are correct. Prefer an account or credential with the minimum required permissions. If the import fails, first check source registry authentication, network access, and errors writing to the target registry. **Import an Existing Image** When you select **Import Existing Image**, enter the address of a previously built image and confirm that it includes the dependencies and startup tools required by the workload. Use this method to import an image that was not built on the platform but is already available in an image registry. The platform writes the image contents to the target registry and adds a selectable image version to the custom image list. Wait for the image transfer and write to complete. Before the import finishes, the target cluster might not be able to select the image for development environments, training jobs, or inference services. ### 3. Submit the Build After configuring the settings, click **Create** to submit the build task. After submission, you can check the build status and logs in **Image Build Task List**. When the build succeeds, the image appears in **Available Images**. ## Save an Image from a Development Environment You can also save a development environment as a custom image. This is useful when you have installed software and debugged dependencies in a development environment and want to preserve the current container file system as a reusable image. ### 1. Confirm What to Save Before saving an image, confirm that the dependencies, tools, and configuration you want to reuse have been written to the container file system. Saving an image does not back up mounted Volumes or process memory. Code, models, data, and training results that exist only on mounted Volumes remain in their original storage; mount that storage again when you use the image later. Before saving, remove credentials, temporary tokens, and other sensitive content that should not be included in the image. For environments that require long-term maintenance, keep a Dockerfile or dependency list as well instead of relying only on a one-time save. ### 2. Submit the Image Save Keep the development environment running. Use the **Save Image** entry on the development environment page, enter the image name, version, and build information, and submit the request. The development environment might be temporarily unavailable while the image is being saved. We recommend saving when no interactive work is in progress. Do not stop, delete, or reschedule the source environment, or make extensive dependency changes at the same time. For the specific entry and steps, see [Use a JupyterLab Development Environment](/siverse/development/use-jupyterlab-development-environment.md) or [Use a VSCS Development Environment](/siverse/development/use-vscode-server-development-environment.md). ### 3. Verify the Save Result After submitting, confirm that the build succeeded in **Image Build Task List**. If saving fails, review the build logs and first check the container size, build resources, dependency files, and source environment status. After a successful save, verify key dependencies in a new development environment or a small workload rather than checking them only in the original environment. ## View Build Results After submitting a build task, check its status in **Image Build Task List**. If a build fails, first review the errors in the build logs, then use the scheduling information to determine whether the cause is dependency installation, the Dockerfile, image pulling, resource scheduling, or synchronization settings. | Action | Description | | - | - | | Build Logs | View the image build logs. If the build fails, use the logs to locate issues with dependency installation, the Dockerfile, image pulling, or command execution. | | Build Configuration | View the build task configuration, including the base image, Dockerfile, dependencies, build arguments, and resource settings. | | Update Configuration | Modify the build task configuration. Before updating, confirm that the image is not being built; wait until the build succeeds, fails, or stops. Updates generally have the following effects:
  • **Name**, **Version**, **Build Region**, and **Build Cluster** usually cannot be changed.
  • Changing build-related fields such as the build method, base image, Dockerfile, build arguments, dependencies, synchronization settings, commit ID, instance settings, or resource pool may trigger a rebuild.
  • Changing only metadata such as the description, image type, framework version, Python / CUDA / NCCL versions, chip type, labels, or Project Groups usually does not require a rebuild.
  • Images created by saving a development environment or synchronizing an image registry may allow metadata updates only.
| | View Image | Open the image generated by the completed build. The image might not be available to view if the build has not succeeded. | | Clone | Create a new build task based on the current task configuration. This is useful for reusing the base image, dependencies, and build arguments. | | Stop | Stop an ongoing build task. The image will no longer be built after the task stops. Whether an image is already available depends on the current build result. Stopping the build does not necessarily undo images already created or external changes. | | Delete | Delete a build task record that is no longer needed. Before deleting it, confirm that you no longer need to view its build logs or configuration. | ## Frequently Asked Questions > **What should I do if a build task stays queued for a long time?** > > Check the build resources, resource pool availability, remaining user quota, and scheduling information. If the build is waiting for resources, do not repeatedly submit tasks with the same name and version. > **What should I check first when a build fails?** > > First review the errors in **Build Logs**, then use the scheduling information to identify the failure stage. Common causes include dependency installation failures, an incorrect Dockerfile path, a failure to pull the base image, command execution errors, or insufficient build resources. > **What should I do if apt or pip installation fails?** > > Check the package name, version, installation source, and compatibility with the base environment. To pin dependency versions, declare them in the Dockerfile or a dependency file to avoid pulling incompatible versions during the build. > **What should I do if the Dockerfile cannot find a file?** > > Check the build inputs, working directory, and file reference paths. Files referenced by the Dockerfile must be in the current build context. > **What should I do if importing an external image fails?** > > Check the source registry address, authentication information, network access, and target registry errors. Grant private registry credentials only the minimum permissions needed to pull or import images. > **What should I do if I cannot find the image in the target workload after a successful build?** > > Return to **Available Images** and confirm that the image's region, target cluster URL, shared Project Groups, and filters are as expected. For cross-cluster use, also confirm that image synchronization has completed. If you need to submit the issue to the technical support team, provide the image name and version, region and cluster, build task ID, failure stage, and redacted error logs. Do not send repository account credentials, passwords, or tokens. ## Next Steps * [Manage Custom Images](/siverse/images/manage-custom-images.md) This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.