From 2d6131311cd01162cecd87fbaf2c941541ad3c89 Mon Sep 17 00:00:00 2001
From: Sean Murphy <sean@sdsc.ethz.ch>
Date: Wed, 24 Jan 2024 11:53:40 +0100
Subject: [PATCH] chore(cleanups): added content to readme, cleanups to
 flake.nix, pyproject.toml

---
 README.md      | 32 +++++++++++++++++++++++++++++++-
 flake.nix      |  3 ++-
 pyproject.toml | 10 +++-------
 3 files changed, 36 insertions(+), 9 deletions(-)

diff --git a/README.md b/README.md
index 991752e..fd147dc 100644
--- a/README.md
+++ b/README.md
@@ -1,2 +1,32 @@
 # nix-container-build-gha
-Demo repo - building nix container image with github action
+
+This is a simple testing repo I used to understand how to build python environments in github actions
+with nix. I wrote up my thoughts on this medium post.
+
+This is the public version of the repo which anyone can look through; I also maintain a private version 
+which is linked to some self hosted github runners - I don't want to link the public version to any such
+runners.
+
+There are comments in the code which give some pointers on how things work - feel free to look around.
+
+## The python application
+
+The python application was taken from [this repo](https://github.com/mitchellh/flask-nix-example) created by Mitchell Hashimoto - it is a simple flask application. 
+
+I have included a couple of unecessary dependencies in the `pyproject.toml` just to understand how these are
+handled (`torch` and `jupyter`). They are available in the resulting python environment but not used by the application.
+
+## Working locally
+
+This kind of assumes you have a sensible nix configuration and are comfortable using flakes.
+
+- `nix build` will build the application and put the content in the `result` directory
+- `nix build .#ociApplicationImage` will build a container image which runs the application - the resulting container image is a gzip'd tarball in the `result` directory which can be imported to docker using `docker load < result`
+- `nix build .#ociPackageImage` will build a container image which contains the python environment but launches bash; run python within bash and you can import the dependencies
+- `nix run` will run the application without building a container image
+
+## Using the github actions
+
+The github actions content was essentially copied from this repo.
+
+It requires a token to access a docker repository and push the resulting container image there. This repo uses the standard github runners but in the private variant, I was using a self-hosted runner (there are a couple of comments in the github action definition which highlight the small differences).
diff --git a/flake.nix b/flake.nix
index 9c72478..6357a41 100644
--- a/flake.nix
+++ b/flake.nix
@@ -92,15 +92,16 @@
           packages = [ pythonEnv ];
         };
 
-      # Build our package using `buildPythonPackage
       packages.x86_64-linux = {
         # default is built with `nix build`
         default = pythonPackage;
 
         # built with `nix build .#ociPackageImage`
+        # the result is a gzip'd tarball - it can be imported to docker with `docker load < result` 
         ociPackageImage = buildPackageImage;
 
         # built with `nix build .#ociApplicationImage`
+        # the result is a gzip'd tarball - it can be imported to docker with `docker load < result` 
         ociApplicationImage = buildApplicationImage;
       };
 
diff --git a/pyproject.toml b/pyproject.toml
index f057654..6caf4f8 100644
--- a/pyproject.toml
+++ b/pyproject.toml
@@ -1,3 +1,5 @@
+# This content was taken from this repo: https://github.com/mitchellh/flask-nix-example
+
 [project]
 name = "flask-example"
 version = "0.1.0"
@@ -9,11 +11,10 @@ readme = "README.md"
 packages = [{include = "src"}]
 requires-python = ">=3.10"
 license = {text = "MIT"}
+# Flask is necessary to run the application - torch, jupyter and beautifulsoup4 are included to understand how the plumbing works
 dependencies = [
     "Flask>=2.2.3",
-    #"pytorch>=2.0.0",
     "torch>=2.0.0",
-    # "numpy>=1.26.3",
     "jupyter>=1.0.0",
     "beautifulsoup4",
 ]
@@ -22,11 +23,6 @@ dependencies = [
 # we don't include src here because the packages directive above indicates that only content within the src file should be included
 app = 'app:main'
 
-# [[tool.pdm.source]]
-# url = "https://download.pytorch.org/whl/cpu"
-# verify_ssl = true
-# name = "torch"
-
 [build-system]
 requires = ["pdm-backend"]
 build-backend = "pdm.backend"