Run GuPPy in a container#

GuPPy is published as a container image, ghcr.io/lernerlab/guppy, with GuPPy and everything it needs already installed. Use it when you cannot install software on the machine that holds your data, such as a shared compute cluster, or when you want a fixed GuPPy version without managing a Python environment. To install GuPPy directly instead, see Installation.

The image is tagged with each GuPPy release (for example v2.0.0-beta5), and latest points at the most recent release. Name a release tag when you want the same GuPPy version every time you start it.

GuPPy runs as a web server inside the container. You open it in your own browser at http://localhost:5006, and every page GuPPy opens reaches you through that same port. Port 5006 is the usual default for Bokeh and Panel apps like GuPPy and has no other significance. Any free port works, as long as you use the same number in every command below and pass it to GuPPy with --port.

With Docker#

On a machine with Docker, publish port 5006 and mount the folder that holds your data:

docker run --rm -p 127.0.0.1:5006:5006 -v /path/to/data:/data \
    ghcr.io/lernerlab/guppy:latest --input-root /data --output-root /data

Replace /path/to/data with the folder on your computer that holds your data. Inside the container that folder is /data, and GuPPy starts with both its input and output roots there, so the folder browser shows your own folders. If your sessions or outputs live in a subfolder, change either root on the GuPPy homepage.

Then open http://localhost:5006. The 127.0.0.1 in -p keeps GuPPy reachable from your own machine only. Keep 5006 on both sides of -p, because GuPPy only accepts connections addressed to the port it serves on.

The image is built for linux/amd64. Docker Desktop on an Apple silicon Mac runs it through emulation, which works but is slower than installing GuPPy directly.

On a shared compute cluster with Apptainer#

Shared clusters rarely allow Docker, since it needs administrator rights. Most provide Apptainer (formerly Singularity) instead, which runs the same image without them. Check with apptainer --version, or ask your cluster’s support team how to load it.

Download the image once into a file you keep:

apptainer pull guppy.sif docker://ghcr.io/lernerlab/guppy:latest

Start GuPPy on the cluster node where you will analyze the data, making the data folder visible inside the container as /data with --bind:
```
apptainer run --bind /path/to/data:/data guppy.sif \
    --address 127.0.0.1 --port 5006 \
    --input-root /data --output-root /data
```
Replace /path/to/data with the folder that holds your data. As with Docker, GuPPy starts with both roots at /data, and you can change either one on the GuPPy homepage. --address 127.0.0.1 keeps GuPPy reachable only from the node itself, so other users of the cluster cannot open your session. If another user already has port 5006 in use on that node, choose another number and use it in the next step too.
On your own computer, forward the port through SSH, naming the node GuPPy runs on and the login host you normally connect to:
```
ssh -L 5006:localhost:5006 -J <user>@<login-host> <user>@<node>
```
Replace <user> with your cluster username, <login-host> with the address you normally ssh to, and <node> with the name of the node GuPPy runs on, which hostname prints on that node. If GuPPy runs on the login host itself, ssh -L 5006:localhost:5006 <user>@<login-host> is enough. Use the same port number on both sides of -L, because GuPPy only accepts connections addressed to the port it serves on.
Open http://localhost:5006 in your browser.