Run a Renku Session on a Remote Machine

Prerequisites

Note

Note about Windows: Renku does not officially support Windows. If you would like to try to use Renku on Windows, we recommend using WSL. However, we do not promise that all Renku functionality will work.

Connect to the remote machine using SSH

Connect to the remote machine using ssh, e.g. ssh user@my.vm.io

Is the CLI installed?

Make sure the Renku CLI is installed: Install the Renku Command-line Interface.

Have you cloned your project?

To work on your project on the remote machine, you’ll need to have cloned your project. If you haven’t done that yet, check out Clone a Renku project.

Do you have Docker?

To run a Renku session, you need to have Docker installed.

On Linux systems, Docker requires root privileges. If you do not have root access to the host, you might consider rootless Docker. If the VM does not support Docker, you might need to ask an administrator to install it for you.

If the remote machine you want to use is itself a Docker container, you’ll need to enable Docker in Docker, either using the docker:dind image in priviledged mode or by mounting the host docker socket into your container.

Start a renku session

First, navigate into your renku project directory:

$ cd <project_name>

Then, start a session using renku session start:

$ renku session start
ID          STATUS    URL
----------  --------  ------------------------------------------------------------
f1693c198e  running   http://0.0.0.0:56674/?token=910ca732ef574049a22d41d0f1109f56

Note

Note: Renku may inform you that the container image for the current commit does not yet exist on your machine, and Renku will offer to build it for you. Say yes!

Note

Running under a specific port

By default, Renku will assign a random port to the session it starts. If you’d rather have a consistent experience with it running on the same port, use the --port flag for renku session start to start with a fixed port.

Port-forward to the Remote Renku Session

When the session was started above, it printed the URL where the session is running, http://0.0.0.0:56674/?token=910ca732ef574049a22d41d0f1109f56 in the above example.

Note the port, 56674 in the example, and port-forward to it from your local machine using SSH, e.g.:

$ ssh -L 56674:localhost:56674 user@my.vm.io

You can then open the session on your local machine by going to http://localhost:56674.

Stop the session

When you’re done with your session, use renku session stop ID on the remote machine.

$ renku session stop <session_id>

to shut down the session.

Clean up unused Docker objects

As you run renku sessions, the docker images used in each session will accumulate on the remote machine. We suggest you occasionally prune docker containers you don’t need anymore so they don’t take up space on your machine.

For example, you can use the following commands to remove all docker images created more than 24 hours ago:

$ docker image prune -a --filter "until=24h"

and all stopped docker containers older than 24 hours:

$ docker container prune --filter "until=24h"

Take a look at the Docker documentation if you’d like to learn more.