add some usage docs (#17)

README.md

@@ -4,6 +4,61 @@ This repository contains the docker configuration for the pixi container image.
 The pixi container image is based on different base images, depending on the use case.
 All images have pixi installed in `/usr/local/bin/pixi` and are ready to use.
 
+## Pulling the images
+
+The images are [available on "GHCR" (Github Container Registry)](https://github.com/prefix-dev/pixi-docker/pkgs/container/pixi).
+You can pull them using docker like so:
+
+```bash
+docker pull ghcr.io/prefix-dev/pixi:latest
+```
+
+There are different tags for different base images available:
+
+- `latest` - based on `ubuntu:jammy`
+- `focal` - based on `ubuntu:focal`
+- `bullseye` - based on `debian:bullseye`
+- `jammy-cuda-12.2.2` - based on `nvidia/cuda:12.2.2-jammy`
+- ... and more
+
+## Usage with shell-hook
+
+The following example uses the pixi docker image as a base image for a multi-stage build.
+It also makes use of the `shell-hook` feature of pixi to define a convenient entry point (after executing the `shell-hook` script, the environment is activated.
+
+```Dockerfile
+FROM ghcr.io/prefix-dev/pixi:0.18.0 AS build
+
+# copy source code, pixi.toml and pixi.lock to the container
+COPY . /app
+WORKDIR /app
+# run some compilation / build task (if needed)
+RUN pixi run build
+# run the `install` command (or any other). This will also install the dependencies into `/app/.pixi`
+# assumes that you have a `prod` environment defined in your pixi.toml
+RUN pixi run install -e prod
+# Create the shell-hook bash script to activate the environment
+RUN pixi shell-hook -e prod > /shell-hook.sh
+
+# extend the shell-hook script to run the command passed to the container
+RUN echo 'exec "$@"' >> /shell-hook.sh
+
+FROM ubuntu:22.04 AS production
+
+# only copy the production environment into prod container
+# please note that the "prefix" (path) needs to stay the same as in the build container
+COPY --from=build /app/.pixi/envs/prod /app/.pixi/envs/prod
+COPY --from=build /shell-hook.sh /shell-hook.sh
+WORKDIR /app
+EXPOSE 8000
+
+# set the entrypoint to the shell-hook script (activate the environment and run the command)
+# no more pixi needed in the prod container
+ENTRYPOINT ["/bin/bash", "/shell-hook.sh"]
+
+CMD ["start-server"]
+```
+
 ## Images
 
 There are images based on `ubuntu`, `debian` and `nvidia/cuda` available.

example/.dockerignore

@@ -0,0 +1 @@
+.pixi/

example/.gitattributes

@@ -0,0 +1,2 @@
+# GitHub syntax highlighting
+pixi.lock linguist-language=YAML

example/.gitignore

@@ -0,0 +1,5 @@
+# pixi environments
+.pixi
+
+__pycache__/
+*.pyc

example/Dockerfile

@@ -0,0 +1,30 @@
+FROM ghcr.io/prefix-dev/pixi:0.18.0 AS build
+
+# copy source code, pixi.toml and pixi.lock to the container
+COPY . /app
+WORKDIR /app
+
+# run some compilation / build task (if needed)
+RUN pixi run build-wheel
+RUN pixi run postinstall-production
+
+# Create the shell-hook bash script to activate the environment
+RUN pixi shell-hook -e prod > /shell-hook.sh
+
+# extend the shell-hook script to run the command passed to the container
+RUN echo 'exec "$@"' >> /shell-hook.sh
+
+FROM ubuntu:22.04 AS production
+
+# only copy the production environment into prod container
+# please note that the "prefix" (path) needs to stay the same as in the build container
+COPY --from=build /app/.pixi/envs/prod /app/.pixi/envs/prod
+COPY --from=build /shell-hook.sh /shell-hook.sh
+WORKDIR /app
+EXPOSE 8000
+
+# set the entrypoint to the shell-hook script (activate the environment and run the command)
+# no more pixi needed in the prod container
+ENTRYPOINT ["/bin/bash", "/shell-hook.sh"]
+
+CMD ["gunicorn", "-w", "4", "docker_project:app", "--bind", ":8000"]

example/README.md

@@ -0,0 +1,17 @@
+# Docker example
+
+This example is using docker in combination with [solve-groups](https://pixi.sh/latest/configuration/#the-environments-table).
+The solve-groups ensure that the `default` environment (where the tests are run) is using *exactly* the same versions of the dependencies as the `prod` environment.
+
+In the docker container, we only copy the `prod` environment into the final layer, so the `default` environment and all its dependencies are not included in the final image.
+Also, `pixi` itself is not included in the final image and we activate the environment using `pixi -e prod shell-hook`.
+
+## Usage
+
+To build and run the docker container you require [`docker`](https://docs.docker.com/engine/install/)
+When you have `docker` use the following commands:
+
+```shell
+docker build -t pixi-docker .
+docker run -p 8000:8000 pixi-docker
+```

example/docker_project/__init__.py

@@ -0,0 +1,8 @@
+from flask import Flask
+
+app = Flask(__name__)
+
+
+@app.route("/")
+def hello():
+    return "Hello, Pixi server!"