exec

README

exec

Ephemeral container execution orchestrating Apptainer with the container setup pipeline.

Architecture

options.go   Options struct with defaults
run.go       Main Run() execution function

Key Types

Options:

• BaseImage - Base container image path
• Overlays - Overlay paths/names
• WritableImg - Allow writing to .img overlay
• EnvSettings - Environment variables
• BindPaths - Bind mounts
• Fakeroot - Use fakeroot
• ApptainerFlags - Additional flags
• HideOutput - Suppress output
• HidePrompt - Hide environment notes
• PassThruStdin - Forward stdin to container
• Command - Command to execute
• ApptainerBin - Path to apptainer binary

Usage

Basic Execution

import "github.com/Justype/condatainer/internal/exec"

ctx := context.Background()
opts := exec.Options{
    BaseImage: "/path/to/base.sif",
    Overlays:  []string{"cellranger/9.0.1"},
    Command:   []string{"cellranger", "--version"},
}

if err := exec.Run(ctx, opts); err != nil {
    // Handle error
}

Interactive Shell

opts := exec.Options{
    Overlays:    []string{"python/3.11", "env.img"},
    WritableImg: true,
    Command:     []string{"bash"},
}

exec.Run(ctx, opts)

With Environment and Binds

opts := exec.Options{
    Overlays:    []string{"app/1.0"},
    EnvSettings: []string{"DEBUG=1", "WORKERS=8"},
    BindPaths:   []string{"/data:/mnt/data", "/scratch"},
    Command:     []string{"python", "train.py"},
}

exec.Run(ctx, opts)

Execution Flow

1. Apply defaults - Fill in missing configuration
2. Initialize Apptainer - Set binary path
3. Container setup - Call container.Setup() for:
   • Overlay resolution and ordering
   • Environment collection
   • Bind path deduplication
   • GPU detection
4. Auto-enable fakeroot - If writable .img overlay
5. Debug output - Print configuration if debug mode
6. Print environment - Show overlay environments (if interactive and not hidden)
7. Acquire file locks - Hold shared locks on all .sqf overlays and the base .sif for the duration of execution. .img overlays are skipped — Apptainer flocks them itself and our lock would conflict. Prevents concurrent remove or build --update from deleting .sqf/.sif files in use.
8. Inject proxy env - If an active SOCKS5 proxy is found via proxy.FindActiveProxy(), prepend http_proxy/https_proxy/all_proxy (and uppercase variants) to the container environment so tools inside the container use the tunnel.
9. Execute - Call apptainer.Exec() with processed configuration
10. Release locks - All file locks released after apptainer.Exec() returns

Environment Display

When running interactively, displays environment variables from overlays:

Overlay envs:
  CELLRANGER_ROOT: /ext3/cnt/cellranger/9.0.1
  PATH: /ext3/cnt/cellranger/9.0.1/bin:$PATH

Can be hidden with HidePrompt: true.

Defaults

Missing fields are filled from config:

• BaseImage → config.GetBaseImage()
• ApptainerBin → config.Global.ApptainerBin
• Fakeroot → false (auto-enabled if needed)

Stdin Forwarding

When PassThruStdin: true, forwards stdin to the container for interactive scripts:

opts := exec.Options{
    Command:       []string{"bash", "script.sh"},
    PassThruStdin: true,
}

Used by build system for interactive build scripts.

Integration

Used by:

• cmd/run.go - Direct command execution
• cmd/exec.go - Alias to run
• internal/build - Build script execution

Documentation

Index

• func CreateCondaOverlay(ctx context.Context, opts *overlay.CreateOptions, pkgs []string, ...) error
• func DescribeInitialCondaPackages(pkgs []string) string
• func InitCondaEnv(ctx context.Context, imgPath string, pkgs []string, fakeroot bool, io IO) error
• func InstallPackages(ctx context.Context, imgPath string, pkgs []string, fakeroot bool, io IO) error
• func RemovePackages(ctx context.Context, imgPath string, pkgs []string, fakeroot bool, io IO) error
• func ResolveInitialCondaPackages(pkgs []string) []string
• func Run(ctx context.Context, options Options, ioStreams IO) error
• func RunPostInstall(ctx context.Context, imgPath, postCmd string, fakeroot bool, io IO) error
• func RunPrepared(ctx context.Context, plan *Plan, ioStreams IO) error
• func WithIO(ctx context.Context, ioStreams IO) context.Context
• type Diagnostic
• type IO
  • func IOFromContext(ctx context.Context) IO
  • func (ioStreams IO) IsZero() bool
• type Options
• type Plan
  • func Prepare(ctx context.Context, options Options) (*Plan, error)
  • func (p *Plan) Close()

Functions

func CreateCondaOverlay

func CreateCondaOverlay(ctx context.Context, opts *overlay.CreateOptions, pkgs []string, postInstallCmd string, fakeroot bool, io IO) error

CreateCondaOverlay creates a new user-owned ext3 overlay at opts.Path, initializes a conda environment with pkgs using mm-create, then moves and allocates the final file. This mirrors the `condatainer overlay create -- <pkgs>` flow.

postInstallCmd is run inside the overlay after conda init (empty = skip). fakeroot should be false for normal user-owned overlays.

func DescribeInitialCondaPackages

func DescribeInitialCondaPackages(pkgs []string) string

DescribeInitialCondaPackages returns user-facing text for the resolved initial package list.

func InitCondaEnv

func InitCondaEnv(ctx context.Context, imgPath string, pkgs []string, fakeroot bool, io IO) error

InitCondaEnv creates a new conda environment inside imgPath using mm-create, then cleans the micromamba package cache to reduce overlay size. Use for initial environment creation on a fresh overlay. For adding packages to an existing environment, use InstallPackages.

func InstallPackages

func InstallPackages(ctx context.Context, imgPath string, pkgs []string, fakeroot bool, io IO) error

InstallPackages installs additional conda packages into an existing base environment inside imgPath using mm-install (respects overlay's .condarc channels).

func RemovePackages

func RemovePackages(ctx context.Context, imgPath string, pkgs []string, fakeroot bool, io IO) error

RemovePackages removes conda packages from the base environment inside imgPath.

func ResolveInitialCondaPackages

func ResolveInitialCondaPackages(pkgs []string) []string

ResolveInitialCondaPackages returns the package list used to initialize a fresh conda overlay. An empty list gets a tiny package so mm-create creates the environment instead of receiving no specs.

func Run

func Run(ctx context.Context, options Options, ioStreams IO) error

Run executes a command inside a configured Apptainer container. It is silent by default; callers that want terminal or web output must pass explicit IO writers.

func RunPostInstall

func RunPostInstall(ctx context.Context, imgPath, postCmd string, fakeroot bool, io IO) error

RunPostInstall runs an arbitrary command inside imgPath after package installation.

func RunPrepared

func RunPrepared(ctx context.Context, plan *Plan, ioStreams IO) error

RunPrepared executes a prepared plan with caller-owned IO streams.

func WithIO

func WithIO(ctx context.Context, ioStreams IO) context.Context

WithIO returns a context carrying caller-owned process streams.

Types

type Diagnostic

type Diagnostic struct {
	Level   string
	Message string
}

Diagnostic is a non-fatal execution message returned to presentation layers.

type IO

type IO struct {
	Stdin  io.Reader
	Stdout io.Writer
	Stderr io.Writer
}

IO contains caller-owned process streams. Nil streams are silent/no input.

func IOFromContext

func IOFromContext(ctx context.Context) IO

IOFromContext returns caller-owned process streams from ctx, if present.

func (IO) IsZero

func (ioStreams IO) IsZero() bool

IsZero reports whether no streams are set.

type Options

type Options struct {
	Overlays       []string
	Command        []string
	EnvSettings    []string
	BindPaths      []string
	ApptainerFlags []string // Flags to pass directly to apptainer (e.g., --home=/path, --nv)
	Fakeroot       bool
	WritableImg    bool
	HidePrompt     bool

	BaseImage    string
	ApptainerBin string

	// PassThruStdin is retained for callers that track whether stdin is expected.
	// Actual stdin is owned by IO.Stdin so internal execution never assumes a terminal.
	PassThruStdin bool
}

Options configures how CondaTainer executes a command inside an Apptainer container.

type Plan

type Plan struct {
	Options      Options
	Setup        *container.SetupResult
	Fakeroot     bool
	EnvList      []string
	Diagnostics  []Diagnostic
	ExecOptions  *apptainer.ExecOptions
	OverlayLocks []*overlay.Lock
}

Plan is a prepared container execution. Call Close if RunPrepared is not used.

func Prepare

func Prepare(ctx context.Context, options Options) (*Plan, error)

Prepare resolves and validates container execution inputs without printing.

func (*Plan) Close

func (p *Plan) Close()

Close releases resources acquired during Prepare.