Skip to content

Commit 047f9b4

Browse files
authored
Add instructions on using Renku (#339)
* Add basic instructions on using Renku * Address review suggestions
1 parent b47d718 commit 047f9b4

File tree

3 files changed

+78
-3
lines changed

3 files changed

+78
-3
lines changed

00_intro.ipynb

Lines changed: 78 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -18,6 +18,7 @@
1818
"- [Timetable](#Timetable)\n",
1919
"- [How to interact](#How-to-interact)\n",
2020
"- [How to run the tutorial](#How-to-run-the-tutorial)\n",
21+
" - [On Renkulab](#On-RenkuLab)\n",
2122
" - [With GitHub Codespaces](#With-GitHub-Codespaces)\n",
2223
" - [With Binder](#With-Binder)\n",
2324
" - [On your laptop](#On-your-laptop)\n",
@@ -27,7 +28,7 @@
2728
" - [Simple view](#Simple-view)\n",
2829
" - [File browser](#File-browser)\n",
2930
" - [Terminal](#Terminal)\n",
30-
"- [Exercises 🌶️](#Exercises-🌶️)\n",
31+
"- [Exercises](#Exercises)\n",
3132
" - [Exercise example](#Exercise-example)\n",
3233
" - [Exercise variables](#Exercise-variables)\n",
3334
" - [Exercise difficulty](#Exercise-difficulty)\n",
@@ -103,6 +104,80 @@
103104
"We designed the tutorial as a hands-on workshop. You should try to write as much code as possible to practice the foundational concepts."
104105
]
105106
},
107+
{
108+
"attachments": {},
109+
"cell_type": "markdown",
110+
"metadata": {},
111+
"source": [
112+
"## On RenkuLab\n",
113+
"\n",
114+
"### What is Renku?\n",
115+
"\n",
116+
"Renku (or RenkuLab) is a platform developed by the Swiss Data Science Center.\n",
117+
"Its goal is to bring data and code together by creating **interactive sessions**, where you can do any analysis and seamlessly share with others.\n",
118+
"\n",
119+
"Two concepts are central to Renku:\n",
120+
"\n",
121+
"- A **project** is the place where you connect your work (done interactively via JupyterLab, for example), your code repositories (from GitHub or GitLab), and your data (Renku supports multiple providers).\n",
122+
"- A **session** is an interactive run-time environment that can be used to do work on data and code. A session is a running instance of a predefined environment. Inside a session, all the project's code repositories are cloned and the data are mounted.\n",
123+
"\n",
124+
"For this tutorial, we already created a project and prepared the environment to launch new sessions.\n",
125+
"Your only tasks are to create (or login to) an account on Renku and then start a new session that you will use for the entire tutorial.\n",
126+
"\n",
127+
"### Create an Account on Renku\n",
128+
"\n",
129+
"1. Visit [RenkuLab](https://renkulab.io)\n",
130+
"2. Click on **Login** at the top right corner\n",
131+
"3. Sign up using your preferred option (edu-ID, GitHub, or ORCID)\n",
132+
"\n",
133+
"### Start a New Session\n",
134+
"\n",
135+
"After you created your account, go back to the [tutorial GitHub's page](https://github.com/empa-scientific-it/python-tutorial) and click on the Renku badge to start a new session:\n",
136+
"\n",
137+
"<img src=\"images/start_renku_session.png\" alt=\"Start a new Renku session\" width=\"800\"/>\n",
138+
"\n",
139+
"By clicking on the Renku badge link, you will automatically start a new session of the **Python Tutorial Launcher**.\n",
140+
"This is the default launcher we are going to use for the whole tutorial.\n",
141+
"If you terminate the session and need to start a fresh one, always choose \"Python Tutorial Launcher\".\n",
142+
"\n",
143+
"### Working in a Session\n",
144+
"\n",
145+
"Once your session starts, you'll be in a **JupyterLab environment** where you can work with notebooks, Python files, and terminal commands.\n",
146+
"\n",
147+
"#### Essential Things to Know\n",
148+
"\n",
149+
"**Saving your work**\n",
150+
"- Your work is automatically saved within the session, but you can always *manually* save the notebook you are working on\n",
151+
"- Files are located in `/home/jovyan/work/` - this is your working directory inside the session (but you shouldn't worry about that)\n",
152+
"- To preserve changes permanently, you need to commit and push them (we'll cover this in the tutorial)\n",
153+
"\n",
154+
"**Session management**\n",
155+
"- Sessions **auto-pause after 30 minutes of inactivity** to save resources\n",
156+
"- You can resume a paused session from where you left off - your work won't be lost\n",
157+
"- **Always stop your session when done**: Click the session controls (top right) and select \"Stop session\"\n",
158+
"\n",
159+
"**Installing packages**\n",
160+
"- The environment already has the necessary Python packages installed\n",
161+
"- You can install other packages with a standard `pip install <package-name>` in a Terminal window\n",
162+
" - **Note:** Packages installed this way are temporary and only last for your current session\n",
163+
"\n",
164+
"\n",
165+
"<img src=\"images/open_terminal.png\" alt=\"Open a new Terminal\" width=\"500\"/>\n",
166+
"\n",
167+
"\n",
168+
"**Starting fresh**\n",
169+
"- The first time you start a session, it may take 1-2 minutes to build the environment\n",
170+
"- If something breaks, you can always stop the session and start a new one\n",
171+
"\n",
172+
"### Troubleshooting\n",
173+
"\n",
174+
"| Problem | Solution |\n",
175+
"|---------|----------|\n",
176+
"| Session won't start | Wait 1-2 minutes - the environment is building |\n",
177+
"| Lost your work | If you didn't stop the session, your files are still there. Resume the session to continue |\n",
178+
"| Something broke | Stop the current session and start a fresh one |"
179+
]
180+
},
106181
{
107182
"cell_type": "markdown",
108183
"metadata": {},
@@ -368,7 +443,7 @@
368443
"cell_type": "markdown",
369444
"metadata": {},
370445
"source": [
371-
"# Exercises 🌶️\n",
446+
"# Exercises\n",
372447
"\n",
373448
"For each topic we prepared a bunch of exercises to practice the concepts.\n",
374449
"\n",
@@ -553,7 +628,7 @@
553628
"name": "python",
554629
"nbconvert_exporter": "python",
555630
"pygments_lexer": "ipython3",
556-
"version": "3.10.17"
631+
"version": "3.12.12"
557632
},
558633
"vscode": {
559634
"interpreter": {

images/open_terminal.png

122 KB
Loading

images/start_renku_session.png

90.2 KB
Loading

0 commit comments

Comments
 (0)