diff --git a/.dockerignore b/.dockerignore new file mode 100644 index 00000000..bb9e77d6 --- /dev/null +++ b/.dockerignore @@ -0,0 +1,6 @@ +* +!environment.yml +!conda-lock.yml +!**/*.py +!**/*.ipynb +!**/*.sh diff --git a/Dockerfile b/Dockerfile new file mode 100644 index 00000000..28c5e931 --- /dev/null +++ b/Dockerfile @@ -0,0 +1,11 @@ +FROM mambaorg/micromamba:1.5.8 + +WORKDIR /model + +COPY --chown=$MAMBA_USER:$MAMBA_USER . . + +RUN micromamba create --name claymodel --yes --file conda-lock.yml \ + && micromamba clean --all --yes + +ENTRYPOINT ["/usr/local/bin/_entrypoint.sh"] +CMD ["jupyter-lab", "--ip", "0.0.0.0", "--port", "8888", "--allow-root"] diff --git a/README.md b/README.md index 1e2d52d1..2810301a 100644 --- a/README.md +++ b/README.md @@ -95,3 +95,52 @@ python -m http.server --directory _build/html ``` There is a GitHub Action on `./github/workflows/deploy-docs.yml` that builds the site and pushes it to GitHub Pages. + +## Docker + +In order to avoid installing dependencies directly onto the machine, a Dockerized version of the Clay model has been provided. To run it using [docker compose](https://docs.docker.com/compose/) run the following command from the repo root: +```bash +docker-compose up # using the --build flag to force a rebuild, if necessary +``` + +Alternatively, you can build and run the Docker image using docker directly with: +```bash +docker build . -t claymodel --platform linux/amd64 # build image +docker run --rm -it -v $(pwd):/model -p 8888:8888 -e ENV_NAME=claymodel --platform linux/amd64 claymodel:latest # run container +``` + +In both cases, the default command will be run, which instantiates a [jupyter-lab](https://jupyterlab.readthedocs.io/en/stable/getting_started/starting.html) instance, from which the documentation notebooks can be run. The jupyter notebook will be accssible on the exposed port (`8888`). +### Note: accessing the jupyter-lab instance in the browser requires an authentication token that can be found in the container logs. Look for the following lines: +```bash +model-claymodel-1 | +model-claymodel-1 | To access the server, open this file in a browser: +model-claymodel-1 | file:///home/mambauser/.local/share/jupyter/runtime/jpserver-1-open.html +model-claymodel-1 | Or copy and paste one of these URLs: +model-claymodel-1 | http://3a2045c995b0:8888/lab?token=587bc427e6a84b14bae0f4783567e792cfb3b95e6131f569 +model-claymodel-1 | http://127.0.0.1:8888/lab?token=587bc427e6a84b14bae0f4783567e792cfb3b95e6131f569 +``` + +Additionally the project root will be mounted as volume to the running container so any modifications made to the code base locally will be immediately reflected within the docker container. + +### Custom commands: + +This default command can be overridden with a custom command: +```bash +docker-compose run claymodel {custom command} +``` +or using docker directly: +```bash +docker run --rm -it -v $(pwd):/model -p 8888:8888 -e ENV_NAME=claymodel --platform linux/amd64 claymodel:latest {custom command} +``` + +For example, the `bash` command can be used to access an interactive bash session within the running docker container, with the `micromamba` environment already activated: +```bash +# with docker-compose +docker-compose run claymodel bash +(claymodel) mambauser@f04261284e87:/model$ +``` +```bash +# with straight docker +docker run --rm -it -v $(pwd):/model -p 8888:8888 -e ENV_NAME=claymodel --platform linux/amd64 claymodel:latest bash +(claymodel) mambauser@f04261284e87:/model$ +``` diff --git a/docker-compose.yml b/docker-compose.yml new file mode 100644 index 00000000..a717878f --- /dev/null +++ b/docker-compose.yml @@ -0,0 +1,10 @@ +version: '3.8' + +services: + claymodel: + image: claymodel + platform: linux/amd64 # Specify the target platform for run + ports: + - "8888:8888" # Expose port 8888 on the host and bind it to port 8888 in the container + environment: + - ENV_NAME=claymodel # Ensure the claymodel conda environment is activated