CLI Reference

ispawn provides a command-line interface for building and managing Docker containers with multiple services.

ispawn

ispawn: Manage development environments as ‘spawns’.

A spawn combines a base Docker image with selected services (e.g., VSCode, RStudio, Jupyter) into a ready-to-run, containerized environment accessible via HTTPS.

This tool provides commands to: - Set up the ispawn environment (networking, proxy). - Build enriched ‘spawn images’ from a base image and services. - Run, list, stop, and remove ‘spawn runs’ (running instances). - Manage the underlying spawn images.

ispawn [OPTIONS] COMMAND [ARGS]...

Options

-f, --force

Force overwrite of existing configurations or resources.

-u, --user

Prioritize user-level configuration (~/.ispawn) over system-level configuration (/etc/ispawn).

build

Build a reusable ‘spawn image’ with specified services.

Constructs an enriched Docker image based on the provided base image, incorporating selected services and applying any global build customizations defined during ‘ispawn setup’. This image can then be used to quickly launch ‘spawn runs’.

ispawn build [OPTIONS]

Options

-b, --base <base>

Required The base Docker image tag to use for building (e.g., ‘ubuntu:22.04’).

-s, --service <services>

Specify services to include in the image. Can be used multiple times. Available: jupyterhub, vscode, jupyterlab, jupyter, rstudio. Defaults to rstudio and jupyterhub if none are specified.

Options:

jupyterhub | vscode | jupyterlab | jupyter | rstudio

image

Commands for managing ispawn ‘spawn images’.

ispawn image [OPTIONS] COMMAND [ARGS]...

list

List ispawn-related ‘spawn images’.

ispawn image list [OPTIONS]

remove

Remove one or more ispawn ‘spawn images’.

You can specify images by their ID or tag (e.g., ispawn-ubuntu:22.04 …).

ispawn image remove [OPTIONS] IMAGE_ID_OR_TAG

Options

--all

Remove all ispawn-related Docker images.

Arguments

IMAGE_ID_OR_TAG

Optional argument(s)

info

Display information about a specific spawn run.

ispawn info [OPTIONS] CONTAINER_NAME_OR_ID

Arguments

CONTAINER_NAME_OR_ID

Required argument

list

List running and stopped ispawn ‘spawn runs’ (containers).

ispawn list [OPTIONS]

remove

Remove one or more stopped ‘spawn runs’ (containers).

Specify spawn runs by the name given during ‘run’ or by container ID. Containers must be stopped first unless –force is used. Note: Internally, this operates on container names/IDs.

ispawn remove [OPTIONS] CONTAINER_NAME_OR_ID

Options

--all

Remove all stopped ispawn spawn runs containers.

Arguments

CONTAINER_NAME_OR_ID

Optional argument(s)

restart

Restart one or more stopped ‘spawn runs’ (containers).

Specify spawn runs by the name given during ‘run’ or by container ID.

ispawn restart [OPTIONS] CONTAINER_NAME_OR_ID

Options

-a, --all

Restart all ispawn spawn runs.

Arguments

CONTAINER_NAME_OR_ID

Optional argument(s)

run

Create and run a new ‘spawn run’ (a container instance).

Launches a container instance (a ‘spawn run’) based on the specified base image and services. If the corresponding ‘spawn image’ doesn’t exist, it can be built automatically using –build. Configures networking, volumes, and user access.

ispawn run [OPTIONS]

Options

-n, --name <name>

Required Unique name for the ‘spawn run’.

-b, --base <base>

Required Base Docker image tag for the spawn (e.g., ‘ubuntu:22.04’).

--build

Build the required ‘spawn image’ automatically if it doesn’t exist.

-s, --service <services>

Specify services to include in the spawn run. Can be used multiple times. Available: jupyterhub, vscode, jupyterlab, jupyter, rstudio. Defaults to vscode, rstudio, jupyter if none are specified.

Options:

jupyterhub | vscode | jupyterlab | jupyter | rstudio

-v, --volume <volumes>

Mount a host directory into the spawn run. Format: ‘host_path:container_path[:ro]’. Can be used multiple times.

-g, --group <group>

Restrict RStudio access to users belonging to this group within the spawn run. Defaults to the primary group of the specified user.

--user <user>

Username or UID to run the spawn run processes as. Defaults to the current user.

--no-sudo

Disable sudo privileges for the user inside the spawn run.

setup

Initialize the ispawn environment.

Sets up the necessary configurations, including the Traefik reverse proxy, Docker network, default volumes, and build customization settings. This command only needs to be run once unless configuration changes are needed.

ispawn setup [OPTIONS]

Options

-n, --name <name>

Namespace prefix for Docker objects (networks, volumes). Default: ‘ispawn’.

-m, --mode <mode>

Proxy mode: ‘local’ for development access only,’remote’ for external access. Default: ‘local’.

Options:

local | remote

-d, --domain <domain>

Base domain name for accessing services. Default: ‘ispawn.localhost’.

--install-mode <install_mode>

Installation scope: ‘user’ (~/.ispawn) or ‘system’ (/etc/ispawn).Default: ‘user’.

Options:

system | user

--subnet <subnet>

CIDR notation for the Docker network subnet. Default: ‘172.30.0.0/24’.

--user-in-namespace

If set, include the username in the container namespace (e.g., ‘username-containername’).

--cert-mode <cert_mode>

Certificate mode for ‘remote’ proxy mode: ‘letsencrypt’ for automatic certs or ‘provided’ for custom certs.

Options:

letsencrypt | provided

--cert-dir <cert_dir>

Directory containing ‘cert.pem’ and ‘key.pem’ when using ‘provided’ cert-mode.

--email <email>

Email address required for Let’s Encrypt certificate generation.

-v, --volume <volumes>

Define default volumes to mount in all containers. Format: ‘host_path:container_path[:ro]’. If only ‘host_path’ is given, it mounts to ‘/mnt/host_path_basename’.

--mount-point <mount_point>

Default base directory inside containers for volumes specified without a target path. Default: ‘/mnt’.

--dns <dns>

DNS servers to use within containers. Can be specified multiple times. Defaults: 8.8.8.8, 8.8.4.4.

--env-chunk-path <env_chunk_path>

Path to a file containing environment variables (one per line) toinject into built images.

--dockerfile-chunk-path <dockerfile_chunk_path>

Path to a file containing Dockerfile instructions to append duringimage builds.

--entrypoint-chunk-path <entrypoint_chunk_path>

Path to a script to prepend to the container’s entrypoint.

--home-prefix <home_prefix>

Prefix for user home directories inside the container. Default: ‘/home/’.

--timezone <timezone>

Timezone to set within containers (e.g., ‘America/New_York’). Default: ‘Europe/Paris’.

status

Show the current ispawn status.

Displays configuration, checks Traefik proxy status, and lists running/stopped ‘spawn runs’ (containers).

ispawn status [OPTIONS]

stop

Stop one or more running ‘spawn runs’ (containers).

Specify spawn runs by the name given during ‘run’ or by container ID. Note: Internally, this operates on container names/IDs.

ispawn stop [OPTIONS] CONTAINER_NAME_OR_ID

Options

--all

Stop all running ispawn spawn runs.

--remove

Remove the spawn run(s) associated container(s) after stopping.

Arguments

CONTAINER_NAME_OR_ID

Optional argument(s)