Container image requirements
Every container image used for a Citrix SecurSpaces™ workspace must meet the requirements on this page. An image that does not meet them may fail to start, or start without the Cloud IDE working.
At minimum, an image must provide:
- An SSH client.
- Git and Git LFS.
- A user named
developerwith UID 1000.
The rest of this page states the full requirements. To add an image to a project once it meets them, see Container images. To build one, see Workspace images.
Core packages
Required on all distributions, for compatibility with the platform and with the IDE server that runs inside the workspace.
| Package | Purpose |
|---|---|
glibc >= 2.28 |
C standard library required by the IDE server. On Alpine, use musl with gcompat instead. |
libstdc++ >= 3.4.25 |
C++ standard library |
libgcc |
GCC runtime |
bash |
Default shell required by the IDE server |
curl or wget
|
Downloads the server and external dependencies |
git |
Source control integration and workspace initialization |
git-lfs |
Handling of large files and binary assets |
openssh-client / openssh-clients
|
SSH-based Git authentication and remote access |
User account
The image must be provisioned with this account and home directory. The values are not configurable. The
workspace container runs as UID 1000, and the persistent volume is mounted at /home/developer, so an image
that uses a different user or home directory cannot write to it.
| Property | Value |
|---|---|
| User name | developer |
| Home directory | /home/developer |
| UID | 1000 |
| GID | 1000 |
| Login shell | /bin/bash |
End the Dockerfile with USER 1000 and WORKDIR /home/developer so the workspace starts as the right user
in the right directory.
How the platform checks an image
When an administrator adds an image, or adds a tag to an existing image, SecurSpaces tests it before anyone can use it. It starts a temporary ghost workspace from the image and runs a check inside it. The image is marked ready only if the check passes.
The check tests four things, all by running the command or looking the user up inside the container:
| Checked | Failure message |
|---|---|
ssh is on the PATH
|
SSH is not present on the image |
git is on the PATH
|
Git is not present on the image |
git-lfs is on the PATH
|
Git-lfs is not present on the image |
A user named developer exists |
User(ID 1000) could not be accessed: the user developer is not present on the image |
If any fail, the image is flagged The image is not compatible with our workspace infrastructure, followed by The following requirements are not met: and the specific failures. The image cannot be used until it is rebuilt and re-added.
Important:
The check covers those four items only. Everything else on this page — the UID and GID, the home directory, the login shell, the startup script directory, the architecture, and the
glibcversion — is still required, but an image can pass the check and fail later at runtime. Passing is a floor, not a certification.
Read the result
The compatibility check appears in the image’s log as Checking image compatibility with our workspace infrastructure, in the Setting up the workspace phase. Open it from the image entry in Resources > Container Images.
The log also shows the ghost workspace pulling your image, so it is a useful place to confirm the image was found and how large it is.
Distribution-specific packages
Ubuntu and Debian
Ubuntu 20.04 or later, or Debian 11 or later, is recommended for glibc compatibility.
| Package | Purpose |
|---|---|
tar |
Unpacks the server bundle |
ca-certificates |
Secure HTTPS connections when downloading extensions |
Red Hat Enterprise Linux
RHEL 8.x and 9.x meet the core requirements.
| Package | Purpose |
|---|---|
tar |
Unpacks the server bundle |
CentOS Stream and RHEL-compatible distributions
CentOS Stream 8 and 9, Rocky Linux 8 and 9, and AlmaLinux 8 and 9 meet the core requirements.
CentOS 7 does not meet the requirements, because it ships with glibc 2.17.
| Package | Purpose |
|---|---|
tar |
Unpacks the server bundle |
Alpine Linux 3.16 or later
| Package | Purpose |
|---|---|
musl >= 1.2.3 |
Native C standard library for Alpine |
gcompat |
Provides the glibc compatibility layer |
Note:
Alpine uses
muslrather thanglibc. Core features work through compatibility layers, but Ubuntu and RHEL-based images give the most stable experience with the IDE server.
Architecture
SecurSpaces runs on linux/amd64 (x86_64). Workspace images must be built for that architecture. Other
architectures, including ARM, are not supported.
Troubleshooting
GLIBC_2.xx not found when the terminal starts
The Cloud IDE opens but the terminal fails immediately, with a message similar to:
The terminal process failed to launch: A native exception occurred during launch
(/lib/x86_64-linux-gnu/libc.so.6: version `GLIBC_2.34' not found
(required by /strong/strong-ide/node_modules/node-pty/build/Release/pty.node)).
<!--NeedCopy-->
The image is based on a distribution whose glibc is older than the IDE server requires. CentOS 7 is the
usual cause, at glibc 2.17. Rebuild on a newer base — Ubuntu 20.04 or later, Debian 11 or later, or RHEL 8
or later — or contact Citrix support to ask whether your distribution can be supported.
The image is flagged as not compatible
The image was added but is not usable, and shows The image is not compatible with our workspace infrastructure.
One of the four checked requirements is missing. The message lists which. In practice it is nearly always a
base image that was never intended for interactive development — an application image such as a database or
a dashboard has no reason to carry git, git-lfs, or an SSH client, and often has no developer user.
Add the missing packages and the user, rebuild, and add the image again. See How the platform checks an image, and Build your first base image for a working starting point.
The workspace starts but files written during the build are missing
Anything written to /home/developer in the Dockerfile is hidden once the persistent volume mounts over it.
Install to a system directory instead, or write the files from a startup script. See
Understanding persistence.
Related information
- Workspace images — building an image
- Container images — adding one to a project
- What persists in a SecurSpaces Workspace
- strong-network/images on GitHub and strongnetwork on Docker Hub — example and prebuilt images