Repository files navigation

ch is a command-line interface for using Docker containers as development environment. It enables users to setup a complexcontainer configuration once (saved in~/.ch.yaml on macOS/Linux) and the easily access the environment with a few commands.

This was designed to generalize how we develop C++ code in CSCI 104 to be portable enough to usewhichever Docker container you choose. Of course, this project would not be possible without the referenceofdocker/cli for examples of how to use the Docker Engine API.

2023-05-13 Update

This project This was built before I knew anything aboutNix ornix-shell. I've realized those tools are far superior for addressing this problem where a specific compiler and debugging tools are required.

You can follow the installation instructions below to installch or seethecsci104/docker repositoryinstructions and automated setup scripts for a C++ baseddevelopment environment.

Please make sure that your machine meets the requirements for Docker:

• Windows host requirements

• Mac host requirements

If you are using macOS or Linux operating system, you can skip this section.If you are running Windows, you must install the Windows Subsystem for Linux 2 (WSL2) before installing Docker.

Follow the instructions below to install WSL2 on your machine:Windows Subsystem for Linux Installation Guide

Install Docker Desktop fromthe site.

Run the following commands below to download and run the install script for your operating system.

The install script just downloads the latest release from this repository, unpacks, and adds thech binary to your path.

If you run macOS or a Linux OS, follow this section to install thech binary.

Option 1: (recommended for macOS/Linux) use homebrew

brew tap camerondurham/tapbrew install camerondurham/tap/ch

Option 2: run a bash script

Run in your preferred Terminal to download and run the install script for Unix:

 bash<(curl -s https://raw.githubusercontent.com/camerondurham/ch/main/scripts/install-ch.sh)

You can check out the source codehere.

Depending on your default shell (usuallybash orzsh), you will have to source your~/.bashrc or~/.zshrc to addch to yourPATH.

If you use Windows, follow this section to install thech binary.

Run PowerShell as Admin and execute this command to download and run the install script for Windows:

Set-ExecutionPolicy Bypass-ScopeProcess-Force; [System.Net.ServicePointManager]::SecurityProtocol= [System.Net.ServicePointManager]::SecurityProtocol-bor3072; iex ((New-Object System.Net.WebClient).DownloadString('https://raw.githubusercontent.com/camerondurham/ch/main/scripts/install-ch.ps1'))

You can check out the source codehere.

You may need to restart your machine or log out soch is added to yourPath.

Seecommands documentation or theexample commands for how to create your firstenvironment.

Wherecsci104-work is your homework folder in the current directory. Alternatively, you can provide the absolute pathto wherever your homework is on your machine.

This environment is based on this repository:csci104/docker

1. usech create to create and save the environment settings

   ch create csci104 \    --image usccsci104/docker:20.04 \    --volume csci104-work:/work  \    --security-opt seccomp:unconfined \    --cap-add SYS_PTRACE \    --shell /bin/bash

2. start the environment with a terminal session

   ch shell csci104 --force-start

The commands here assumecsci350-work is your homework folder in the current directory. Alternatively, you can provide the absolute pathto wherever your homework is on your machine. For Windows, your volume command should look like--volume "C:\Users\user\path\to\csci350:/xv6_docker", on macOS your command should look like--volume /Users/username/path/to/csci350:/xv6_docker.

This environment is based on the this repository:camerondurham/cs350-docker

1. find the absolute path to yourcsci350 directory where you keep your homework (seeFilepaths in terminal wiki from csci104/docker if you are having issues)

   1. (macOS/Linux) navigate to your directory in the terminal and runpwd, the output should be something like/Users/username/path/to/csci350
   2. (Windows Powershell) navigate to the directory in Powershell and runGet-Location, you will want the output likeC:\Users\Username\path\to\csci350

2. usech create to create and save the environment settings, replacingPATH_TO_YOUR_WORKDIR with the path from step 1.

   ch create csci350 \    --image camerondurham/cs350-docker:v1 \    --volume PATH_TO_YOUR_WORKDIR:/xv6_docker \    --security-opt seccomp:unconfined \    --port 7776:22 \    --port 7777:7777 \    --port 25000:25000 \    --cap-add SYS_PTRACE \    --shell /bin/bash \    --privileged \    --platform linux/amd64

3. start the environment with a terminal session

   ch shell csci350 --force-start

What's the use case for this tool? Good question! This tool is designed to make it easier to use a specific, isolated development environment. For classessuch asCSCI 104 (Data Structures and Algorithms) and CSCI 350 (Operating Systems) at USC, the legacy way of writing code in the class was using a large VM image inside Virtual Box,or if you're lucky, VMWare. A more efficient and arguably smoother workflow involves setting using a Docker container with the class's compilers anddevelopment tools installed.ch offers a consistent interface to configure and access these environments. See below for the commands to createenvironments for these classes.

create docker environment, specify Dockerfile to build or image to pull

Usage:  ch create ENVIRONMENT_NAME {--file DOCKERFILE|--image DOCKER_IMAGE} [--volume PATH_TO_DIRECTORY] [--shell SHELL_CMD] [[--cap-add cap1] ...] [[--security-opt secopt1] ...] [flags]Flags:      --cap-add stringArray        special capacity to add to Docker Container (syscalls)      --context string             context to build Dockerfile (default ".")  -f, --file string                path to Dockerfile, should be relative to context flag  -h, --help                       help for create  -i, --image string               image name to pull from DockerHub  -p, --port stringArray           bind host port(s) to container      --privileged                 run container as privileged (full root/admin access)      --replace                    replace environment if it already exists      --security-opt stringArray   security options      --shell string               default shell to use when logging into environment (default "/bin/sh")      --version                    version for create  -v, --volume stringArray         volume to mount to the working directory      --platform                   platform for image (e.g. linux/amd64, default is local platform)

list all saved configs

Usage:  ch list [ENVIRONMENT_NAME]

delete an environment from your.ch.yaml config file

Usage:  ch delete ENVIRONMENT_NAME [flags]

start docker container in background and save container ID to config file

Usage:  ch start ENVIRONMENT_NAME

run docker shell in docker environment

Usage:  ch shell ENVIRONMENT_NAME [flags]Flags:  -f, --force-start   autostart the environment if not running

stop running container/environment

Usage:  ch stop ENVIRONMENT_NAME

list all running environments

Usage:  ch running

update your Docker image to the latest version or rebuild the container

Usage:  ch update [ENVIRONMENT_NAME] [flags]

check if you are running the latest version ofch and print install commands if an upgrade is available

Usage:  ch upgrade

# create environmentch create ENVIRONMENT_NAME {--file DOCKERFILE|--image DOCKER_IMAGE} [--volume PATH_TO_DIRECTORY] [--shell SHELL_CMD] [--port HOST:CONTAINER] [--security-opt SECURITY_OPT]# create an environment with a non-dockerhub imagech create al2 --image public.ecr.aws/amazonlinux/amazonlinux:2 --shell /bin/bash --volume ./project/files# create a csci104 docker imagech create csci104 --image usccsci104/docker --shell /bin/bash --volume ./project/files/# start container - essentially docker run -d IMAGEch start cs104# get shell into environment - essentially docker exec -it CONTAINER_NAMEch shell cs104# stop containerch stop cs104# update docker image for environmentch update csci104# list all environmentsch list# list all running environmentsch running