Commonsense Git, Docker, and Jupyter integrations.
Project description
gsmo
Commonsense Git, Docker, and Jupyter integrations.
- mount local Git clones into purpose-built Docker containers
- easily configure dependencies, set useful default Git configs, and mirror host user/group so that Git commits in container transparently exist on the host
- run scripts non-interactively, automatically Git-commit updated files
- run "remotely" against Git repositories, pushing changes upstream for static, serverless workflows
- easily boot a Jupyter server or Bash shell from a clone and its corresponding Docker image, for interactive work.
See gsmo.yml
for configuration options
Usage
Run notebooks non-interactively
gsmo
helps run notebooks and scripts in a reproducible fashion (inside Docker containers), and pass-through changes (Git commits) to the host machine:
Running:
gsmo run
in a project directory will:
- load configs (
gsmo.yml
) - build a Docker image
- run a container from that image
- run the project's
run.ipynb
notebook inside that container - Git-commit results
Run interactively
Jupyter Server
Build a Docker image from the current directory, configured by gsmo.yml
, and launch a Jupyter server with the current directory mounted (and various Git- and OS-level configs set, so that changes/commits transparently pass through to the host machine):
gsmo jupyter # or: gsmo j
- runs at a "random" but stable port (derived from a hash of the module name)
- easily configure Python/Linux environment using
gsmo.yml
Bash shell
Build a Docker image from the current directory, configured by gsmo.yml
, and launch a Bash shell with it mounted (and various Git- and OS-level configs set, so that changes/commits transparently pass through to the host machine):
gsmo sh
Module configuration:
gsmo.yml
When you run gsmo
in a directory, it will look for a gsmo.yml
file in the current directory with any of the following fields and build a corresponding Docker image:
General configs
(see gsmo -h
for full/authoritative list):
name
(str
; default: project directory's basename): module name; also used as repository for built Docker imagepip
(str
orList[str]
):pip
libraries to installapt
(str
orList[str]
):apt
libraries to installenv
(str
orList[str]
): environment variables to setenv_file
(str
): file with environment variablesgroup
(str
orList[str]
): OS groups to add to the user inside the container- paths are accepted, in which case the group that owns that path will be used
tag
(str
orList[str]
): additional Docker tags withinname
repositorymount
(str
orList[str]
): Docker mounts, in several convenient formats:<path>
: equivalent to<path>:/<path>
; easily pass local project subdirectories into Docker container, e.g.home/.bashrc
,etc/pip.conf
, etc.- standard Docker
<src>:<dst>
syntax is also supported - in all cases,
~
and env vars are expanded
image
(str
; default:runsascoded/gsmo:<gsmo version>
): base Docker image to build from;<gsmo version>
will be the pip version ofgsmo
that was installedroot
(bool
; defaultFalse
)- when set, run as
root
inside container - by default, host-machine uid+gid are used
- when set, run as
dst
(str
: default/src
): path inside container to mount current directory to
gsmo run
configs
These configs are passed into the Docker container / pertain to the running of a script or notebook inside the container (see non-interactive mode):
run
(str
; default:run.ipynb
): notebook to rundir
(str
; default: current directory): resolve paths (incl. mounts) relative to this directoryyaml
(str
orList[str]
): YAML string(s) with configuration settings for the module being runyaml_path
(str
orList[str]
): YAML file(s) with configuration settings for the module being runcommit
(str
orList[str]
; default:out
config dir): paths to Git commit after a run (in non-interactive mode)out
(str
; defaultnbs
): directory to write executed notebooks to
gsmo run -h
usage: gsmo [input] run [-h] [-b BRANCH] [--clone] [--commit COMMIT] [-C DIR] [-o OUT] [--push PUSH] [-x RUN] [-y YAML] [-Y YAML_PATH]
optional arguments:
-h, --help show this help message and exit
-b BRANCH, --branch BRANCH
Branch to clone, work in, and push results back to. Can also be passed as a trailing '@<branch>' slug on directory path or remote Git
repo URL. For local repositories, implies --clone
--clone Clone local directory into a temporary dir for duration of the run
--commit COMMIT Paths to `git add` and commit after running
-C DIR, --dir DIR Resolve paths (incl. mounts) relative to this directory (default: current directory)
-o OUT, --out OUT Path or directory to write output notebook to (relative to `--dir` directory; default: "nbs")
--push PUSH Push to this remote spec when done running
-x RUN, --run RUN, --execute RUN
Notebook to run (default: run.ipynb)
-y YAML, --yaml YAML YAML string(s) with configuration settings for the module being run
-Y YAML_PATH, --yaml-path YAML_PATH
YAML file(s) with configuration settings for the module being run
gsmo jupyter
configs
gsmo jupyter -h
usage: gsmo [input] jupyter [-h] [-d] [-D] [-O] [-s] [--dir DIR]
optional arguments:
-h, --help show this help message and exit
-d, --detach When booting into Jupyter server mode, detach the container
-D, --no-docker Run in the current shell instead of in Docker
-O, --no-open Skip opening Jupyter notebook server in browser
-s, --shell Open a /bin/bash shell in the container (instead of running a jupyter server)
--dir DIR Root dir for jupyter notebook server (default: --dst / `/src`
Dockerfile
When building the Docker image (in any of the above modes), if a Dockerfile
is present in the repository, it will be built and used as the base image (and any gsmo.yml
configs applied on top of it).
Project details
Release history Release notifications | RSS feed
Download files
Download the file for your platform. If you're not sure which to choose, learn more about installing packages.