diff --git a/docs/run/podman/index.md b/docs/run/podman/index.md index cd59325..af249a2 100644 --- a/docs/run/podman/index.md +++ b/docs/run/podman/index.md @@ -5,12 +5,33 @@ sidebar_position: 0 # _ChRIS_ on Podman +::::danger + +This page is WIP. + +:::: + +## Introduction + +[Podman](https://podman.io) is a rootless, daemon-less\*, +and somewhat more vendor neutral alternative to [Docker](https://docker.com). + +Podman has two ways of supporting Kubernetes YAMLs: directly using the +[`podman kube play`](https://docs.podman.io/en/stable/markdown/podman-kube-play.1.html) +command, or by running Kubernetes in Podman using [KinD](https://kind.sigs.k8s.io/). +The `podman kube play` command has some limitations but avoids the overhead of running +kubelet and containerd in Podman containers. + + + \*Even though daemonlessness is a primary selling point of Podman, often times a damon + is nonetheless necessary, as is the case with running _ChRIS_ using Podman. + + ## System Requirements -_miniChRIS-podman_ requires Podman version 4.3 or above. +Podman version 4.3 or above is required. We aim to support "out-of-the-box" setups of rootless Podman (using slirp4netns and aardvark-dns). - -Supported OS: Fedora Silverblue 37, Ubuntu 22.04, Arch Linux +_ChRIS_ on Podman has previously been tried and worked on: Fedora Silverblue 37, Ubuntu 22.04, and Arch Linux.
@@ -40,96 +61,59 @@ Try downgrading `crun` to version 1.8.7. ::: -## Preconditions - -Make sure your system is not running anything which might interfere with _miniChRIS_. +## Dependencies -- Existing container/pod names might clash with _miniChRIS_. - To be safe, the output of `podman ps -a` should be empty-ish. -- Running servers might clash with _miniChRIS_, which wants to bind TCP ports - 5005, 5010, 8000, 8010, 8080, 8020, and 8021. +In addition to Podman, you also need to have [Helm](https://helm.sh/) installed. -## Podman: Quick Start +## Configuration -```bash -git clone https://github.com/FNNDSC/miniChRIS-podman.git -cd miniChRIS-podman -./minichris.sh up -``` - -## Podman: Tear Down +_ChRIS_ runs containers of its own, so you need to run a Podman socket. +On systemd GNU/Linux, run -```bash -./minichris.sh down +```shell +systemctl --user start podman.service ``` -## Podman: Nuke - -In case `./minichris.sh down` does not work, run: +Create a `values.yaml` configuration file: ```shell -podman pod rm -af -podman volume prune -f +git clone https://github.com/FNNDSC/charts.git fnndsc-charts +cd fnndsc-charts/podman +./init.sh > values.yaml ``` -This might happen if you change the YAMLs. +## Usage -## Using Podman Desktop +First, set your working directory to the `fnndsc-charts` repo cloned above. -It is necessary to feed to Podman Desktop a single YAML file defining all _ChRIS_ resources. -The YAML file is produced by the command `./minichris.sh cat`. +### Startup ```shell -./minichris.sh cat > chris-all-in-one.yml +helm template chris ./charts/chris -f podman/values.yaml | podman kube play --replace - ``` -In the sidebar of Podman Desktop, click the "Containers" icon and then -in the top-right, click "Play Kubernetes YAML". Select the `chris-all-in-one.yml` -file and then click "Play." - -![Screenshot of Podman Desktop: selecting a file](./podman_desktop_select_file.png) - -Wait 1-5 minutes for _ChRIS_ to start up. Optionally, you can monitor the progress from a terminal with the command +### Shutdown ```shell -./minichris.sh watch-migration +helm template chris ./charts/chris -f podman/values.yaml | podman kube down - ``` -When it's done, return the Containers screen and you should see -_ChRIS_ containers running. - -![Screenshot of Podman Desktop: running _ChRIS_ containers](./podman_desktop_created_containers.png) - -At this point _ChRIS_ is running, but it is empty. To add users and plugins to _ChRIS_, -go back to the terminal and run +### Shutdown and Delete Data ```shell -./minichris.sh chrisomatic +helm template chris ./charts/chris -f podman/values.yaml | podman kube down --force - ``` -Finally, you're ready to log in to http://localhost:8020 with username `chris`, password `chris1234`. +### Use Podman Desktop -## Using Quadlet - -The `podman/quadlet/minichris.kube` file can be used with the YAML generated by `./minichris.sh cat` -to deploy _ChRIS_ using [Quadlet](https://www.redhat.com/sysadmin/quadlet-podman). +You need to generate the Kubernetes YAML first: ```shell -systemctl --user start podman.service -./minichris.sh cat > ~/.config/containers/systemd/minichris-aio.yml -cp podman/quadlet/minichris.kube ~/.config/containers/systemd/minichris.kube -systemctl --user daemon-reload -systemctl --user start minichris.service +helm template chris ./charts/chris -f podman/values.yaml > chris.yaml ``` -:::warning - -Friendly reminder to not use _miniChRIS_ in production. - -::: +TODO TODO TODO -## What to expect: performance +### ChRIS_ui -On a fast computer with good internet speed, running `./minichris.sh up` -for the first time (pulls images) takes about 1.5 to 2 minutes. -Subsequent runs will be faster, about 40 seconds. +TODO TODO TODO