Skip to content
Trailer.devDocumentation

Search is only available in production builds. Try building and previewing the site to test it out locally.

Create Image Page

The Create Image form with the secondary sidebar, showing General settings, Build host, and the Image configuration tabs.

The Create Image page builds the container image that workspaces deploy from. The form is split into sections, navigable from the secondary sidebar. The same form is reused for editing on the Image Details page and for saving an image as a template.

A submit-mode button lets you choose Save or Save as template when creating.

General settings

Section titled “General settings”
  • Name: the descriptive name Trailer uses for the image.
  • Description: optional free text.

Build host

Section titled “Build host”

Select the host that builds the image. You can only pick a host where you have permission to create images. If the image is not pushed to a registry, the built image stays only on that host.

See Hosts for managing hosts.

Image configuration

Section titled “Image configuration”

A tab group selects how the image is produced:

  • Generate Dockerfile (default): Trailer generates a Dockerfile from a base image plus the packages, environments, and services you select.
  • Pull an image: use an existing image from Docker Hub or another registry, no build step.
  • Write Dockerfile: author a Dockerfile by hand in the editor.

Generate Dockerfile

Section titled “Generate Dockerfile”

Pick a Workspace base image (defaults to ubuntu:24.04). Advanced settings expose:

  • Image name: the resulting Docker reference. Auto-derived from the image name until you edit it.
  • Pull base image: force-pull the base image before building even if it is present locally.
  • Squash final image: squash the build into a single layer to reduce size. Seeded from the build host default. Turn it off only on storage-constrained hosts.
  • Push after build: push to the registry implied by the image name after a successful build.
  • Enabled: only enabled images can back workspaces.

Pull an image

Section titled “Pull an image”

Select the image to pull. Advanced settings expose Push after build and Enabled.

Write Dockerfile

Section titled “Write Dockerfile”

Write the Dockerfile in the editor. The same advanced settings as Generate Dockerfile apply.

Python packages and environments

Section titled “Python packages and environments”

Shown only for Generate Dockerfile. Define named conda environments and choose conda and pypi packages for each. Trailer resolves and installs them into the image. These environments can later be targeted by startup commands.

Services

Section titled “Services”

Shown for generated and hand-written Dockerfiles (not for pulled images). Adds pre-configured services and the optional Virtual Desktop. See the dedicated section below.

User configuration

Section titled “User configuration”

Shown for non-pulled images, except Windows VDI. Configures the workspace container user: optional uid, user name, gid, and group name (uid/gid range 0 to 65535).

Startup applications

Section titled “Startup applications”

Shown for non-pulled images. Define one or more commands to run when a workspace built from this image starts. Each command can be bound to one of your defined environments, so it runs with that environment’s packages on its path.

  • One command: it runs as the workspace’s main process.
  • Multiple commands: Trailer runs them all at once and keeps them running. If one exits it is restarted automatically, and the output of every command is merged into the workspace logs.

Defining startup here is the recommended way to control boot behavior. Prefer it over the per-workspace startup override, which replaces all of this at once. See the startup note on Create Workspace.

Files

Section titled “Files”

Shown for non-pulled images. Attach files that should be present in the image. Each file entry has a source and a destination path inside the image:

  • From archive: pick a file already uploaded to Trailer.
  • Upload: upload a new file (max 5 MB each).
  • External URL: reference a URL.

Up to 99 files per image. The Path in image field sets where the file lands. For Windows VDI images this field becomes Path on C: drive. See Files.

Files are placed into the image with the same file-add step a Dockerfile uses on a Docker build host, so the usual behaviors apply:

  • An uploaded file is copied to the destination. If it is a tar archive (including gzip, bzip2, or xz), it is unpacked into the destination directory instead of copied as a single file.
  • An external URL is fetched when the image builds. A plain file URL is downloaded to the destination as-is; it is not unpacked, even if it is an archive.
  • A Git repository URL is cloned into the destination. This requires a build host running the modern Docker build engine; on older engines URL downloads and archive unpacking still work, but Git sources do not.

Permissions

Section titled “Permissions”

When creating, you can grant other users view, modify, and delete access to the image. On the Image Details page permissions are managed in their own section. See Permissions and access control for the full model.

Virtual Desktop (VDI) options

Section titled “Virtual Desktop (VDI) options”

The Services section can turn the image into a Virtual Desktop image. Toggle Virtual Desktop, then configure it.

The Operating system dropdown drives everything else. Linux options are Alpine, Arch, Debian, Enterprise Linux, Fedora, and Ubuntu. Selecting Windows switches the form into Windows VDI mode.

Linux VDI

Section titled “Linux VDI”
  • Desktop environment: i3, KDE, MATE, or Xfce. Only the environments valid for the chosen OS are offered.
  • Keyboard layout and System language.
  • Desktop applications: GUI apps installed into the desktop (for example Firefox, GIMP, Blender, VS Code). Selecting more than one forces Virtual Desktop on.
  • General applications: package-manager apps such as Code Server, FFmpeg, Jupyter Lab, and Nginx. These do not require a desktop.

Windows VDI

Section titled “Windows VDI”

Selecting Windows replaces the Desktop environment dropdown with a Windows edition dropdown and shows username and password fields. Desktop apps, general apps, and the image-level user configuration do not apply to Windows images.

  • Windows edition: Windows 11 Pro, 11 LTSC, 11 Enterprise, 10 Pro, 10 LTSC, 10 Enterprise, Windows Server 2025, or Windows Server 2022.
  • Username: the local administrator account name.
  • Password: the local administrator password. On edit, an already-set password shows a hint and is preserved if left blank.
  • Keyboard layout and System language.

Selecting services applies a server-side prefill to the rest of the form (for example the base image), so the form briefly disables saving until that prefill returns.

Section titled “Related Pages”