Skip to content
LabPod LabPod LabPod Docs

How to create a global template

Global templates are visible to every user. Only the root admin can create, edit, enable, disable, import, export, or delete them.

Built-in template README previews support Markdown tables and fenced code blocks. Use fenced code for commands so operators can read and copy multi-line instructions without the preview merging them into one paragraph.

Create a template from an existing image

Section titled “Create a template from an existing image”

Admin Templates page with the template list and editor

  1. Open /admin/templates.
  2. Click New template.
  3. Enter Name and Image. Use a fully qualified image reference with an explicit registry host, such as docker.io/library/python:3.11, ghcr.io/org/image:tag, or nvcr.io/.... LabPod rejects unqualified names such as python:3.11.
  4. Set Type, Default CPU, Default memory, and GPU defaults.
  5. Add ports or launcher definitions.
    • Prefer Import launcher for common apps.
    • Use a manual port only for one-off apps.
  6. Keep Disabled checked until the image exists in the shared image store.
  7. Save the template.
  8. Open /admin/images, pull the image into the shared store, then return to the template.
  9. Uncheck Disabled and save.

Enabled global templates appear in every user’s create-workspace screen.

Import a template bundle

Section titled “Import a template bundle”

Use import when another LabPod server or user exported a .tar bundle.

  1. Open /admin/templates.
  2. Click Import.
  3. Upload the .tar bundle, or paste a bundle URL if the bundle is hosted somewhere the LabPod server can fetch.
  4. Review the preview: image, ports, README, Dockerfile, and context files.
  5. Commit the import.
  6. If the bundle contains a Dockerfile, build it before enabling the template.
  7. If the template or registry requires terms acceptance, open /admin/compliance and accept the pending item.

Imported Dockerfile contexts are preserved by LabPod so the bundle can be rebuilt and re-exported later.

For automation or offline handoff, a root admin can import a host-local bundle with the CLI:

Terminal window
sudo labpod admin template import ./template.tar --global
sudo labpod admin template import ./template.tar --owner alice
Terminal window
# Run these as root
labpod admin template import ./template.tar --global
labpod admin template import ./template.tar --owner alice

CLI imports are created disabled so an admin can review them before users create workspaces. Use the web UI for Dockerfile-backed bundles; the CLI intentionally does not orchestrate image builds.

Build a Dockerfile-backed template

Section titled “Build a Dockerfile-backed template”

Templates created from bundles or built-in managed templates can carry a Dockerfile. The build is template-keyed: LabPod resolves the build context and output tag from the template row.

Every external image used by FROM, Dockerfile # syntax=..., COPY --from=..., or RUN --mount=from=... must include an explicit registry host and pass the registry allowlist. Bare localhost/... references are treated as local rootless-store images; localhost:<port>/... is a registry and must be allowed like any other host.

  1. Open /admin/templates.
  2. Select the template.
  3. Click Build.
  4. Watch the build on /admin/images.
  5. After it succeeds, verify the image is available in the shared store.
  6. Enable the template and save.

Do not run ad-hoc host builds unless you intentionally want to bypass LabPod’s build history and bundle round-trip metadata.

Add or edit launchers

Section titled “Add or edit launchers”

Launchers make apps appear in the workspace Apps section.

Workspace Apps section showing the launchers users see after a template is configured

  1. Open /admin/launchers to create reusable launcher definitions.
  2. Open /admin/templates.
  3. Select a template and click Import launcher in the ports section.
  4. Pick the catalog launcher and save.

Catalog imports are snapshots. Editing /admin/launchers later does not update existing templates; re-import or edit the template port when you need a template to change.

Enable gated templates

Section titled “Enable gated templates”

Some templates or registries require EULA or terms acceptance.

  1. Open /admin/compliance.
  2. Review pending template EULAs and registry terms.
  3. Accept only after your organization is allowed to use that software or registry.
  4. Return to /admin/templates and enable the template if needed.

Accepting a template EULA from the compliance page also enables that template.

Disable instead of delete

Section titled “Disable instead of delete”

Disable a template when you want to stop new workspaces from using it while preserving existing workspace records. Delete only when no workspaces depend on it.