How to Update an Existing Container Image
Overview
This article focuses on the platform workflow to update an existing container image so teams can reuse a consistent, preconfigured toolchain across workspaces. For day‑to‑day software persistence management, refer to the How to Maintain Persistent Changes in Your Workspace.
Why persistency matters
Container images define the baseline configuration of a development environment. Users create workspaces from an image as a blueprint, which helps prevent environment drift and speeds up onboarding.
Context: persistence and startup scripts
In SDS, only data in /home/developer is persistent by default. Changes outside that directory (for example OS-level package installations) do not persist across workspace restarts.
The best practice is to keep shared tooling (e.g. across a team, a project, etc.) in a workspace base image, so teams get a consistent toolchain across workspaces. Use startup scripts only for individual customization, e.g. user-specific.
For details about workspaces’ persistence model and how to make subsequent installations persistent, refer to How to Maintain Persistent Changes in Your Workspace.
Manage container images (Resources → Container images)
Permission:
To add a workspace image, you need Security::Manage permission.
Images are imported from a registry (public or private). Private registries require credentials; public registries do not.
View container images
The Container images panel (under Resources → Container images) displays the images available in the selected scope (project, organization, or platform). You can search for images or filter those currently used in workspaces.
Add a container image
To add an image:
- Go to Resources → Container Images for your project.
- You can add container images at the project, organization, or platform scope (depending on your permissions)
- Select Add New Image.
- Provide the image details (name, image URL, latest tag). Optionally, add private registry credentials and asset information.
Warning:
For image requirements (SSH, Git/Git LFS, developer user), see the Container Images documentation.
(Optional) Sample images
If you want examples of workspace images, Citrix maintains a public repository of Dockerfiles and scripts you can adapt: https://github.com/strong-network/images
Make an environment persistent for your team
There are two common ways to standardize tooling for a team:
Option 1: Create a new workspace image (where supported)
In product deployments, SDS can transform a start-up script into a new workspace image automatically whenever needed. Feature availability can differ between environments.
Option 2: Start from an existing image and standardize configuration with startup scripts
Use this option when you want a reliable baseline and only need to apply configuration or smaller installations at workspace startup. Startup scripts can run pre-start or post-start depending on whether the workspace must wait for them.
Points of consideration
- Only
/home/developeris persistent between workspace restarts. Plan installations accordingly (image, user-space tooling, or startup script). - Image prerequisites: verify SSH, GIT, GIT LFS, and developer UID 1000 before sharing an image broadly.
- Governance: consider restricting allowed registries and configuring private registries centrally (Image URL Constraints and Create Image Registry).
References
- Maintain persistent changes in your workspace
- Container Images
- Create a Workspace
- Resource Settings (Image URL Constraints, Create Image Registry)
- Sample images repository
FAQ
-
Why did my installed tools disappear after a restart?
Only
/home/developeris persistent. Anything installed elsewhere must be baked into the image or re-applied at startup. -
What is the fastest way to onboard a team?
Provide a workspace image that includes the shared toolchain and keep only dynamic configuration in startup scripts.
-
When should I use post-start?
Use post-start for heavy work so the workspace becomes available quickly while setup continues in the background.