diff --git a/00_intro.ipynb b/00_intro.ipynb index 20c30ce8..682ed067 100644 --- a/00_intro.ipynb +++ b/00_intro.ipynb @@ -18,6 +18,7 @@ "- [Timetable](#Timetable)\n", "- [How to interact](#How-to-interact)\n", "- [How to run the tutorial](#How-to-run-the-tutorial)\n", + " - [On Renkulab](#On-RenkuLab)\n", " - [With GitHub Codespaces](#With-GitHub-Codespaces)\n", " - [With Binder](#With-Binder)\n", " - [On your laptop](#On-your-laptop)\n", @@ -27,7 +28,7 @@ " - [Simple view](#Simple-view)\n", " - [File browser](#File-browser)\n", " - [Terminal](#Terminal)\n", - "- [Exercises 🌶️](#Exercises-🌶️)\n", + "- [Exercises](#Exercises)\n", " - [Exercise example](#Exercise-example)\n", " - [Exercise variables](#Exercise-variables)\n", " - [Exercise difficulty](#Exercise-difficulty)\n", @@ -103,6 +104,80 @@ "We designed the tutorial as a hands-on workshop. You should try to write as much code as possible to practice the foundational concepts." ] }, + { + "attachments": {}, + "cell_type": "markdown", + "metadata": {}, + "source": [ + "## On RenkuLab\n", + "\n", + "### What is Renku?\n", + "\n", + "Renku (or RenkuLab) is a platform developed by the Swiss Data Science Center.\n", + "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", + "\n", + "Two concepts are central to Renku:\n", + "\n", + "- 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", + "- 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", + "\n", + "For this tutorial, we already created a project and prepared the environment to launch new sessions.\n", + "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", + "\n", + "### Create an Account on Renku\n", + "\n", + "1. Visit [RenkuLab](https://renkulab.io)\n", + "2. Click on **Login** at the top right corner\n", + "3. Sign up using your preferred option (edu-ID, GitHub, or ORCID)\n", + "\n", + "### Start a New Session\n", + "\n", + "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", + "\n", + "\"Start\n", + "\n", + "By clicking on the Renku badge link, you will automatically start a new session of the **Python Tutorial Launcher**.\n", + "This is the default launcher we are going to use for the whole tutorial.\n", + "If you terminate the session and need to start a fresh one, always choose \"Python Tutorial Launcher\".\n", + "\n", + "### Working in a Session\n", + "\n", + "Once your session starts, you'll be in a **JupyterLab environment** where you can work with notebooks, Python files, and terminal commands.\n", + "\n", + "#### Essential Things to Know\n", + "\n", + "**Saving your work**\n", + "- Your work is automatically saved within the session, but you can always *manually* save the notebook you are working on\n", + "- Files are located in `/home/jovyan/work/` - this is your working directory inside the session (but you shouldn't worry about that)\n", + "- To preserve changes permanently, you need to commit and push them (we'll cover this in the tutorial)\n", + "\n", + "**Session management**\n", + "- Sessions **auto-pause after 30 minutes of inactivity** to save resources\n", + "- You can resume a paused session from where you left off - your work won't be lost\n", + "- **Always stop your session when done**: Click the session controls (top right) and select \"Stop session\"\n", + "\n", + "**Installing packages**\n", + "- The environment already has the necessary Python packages installed\n", + "- You can install other packages with a standard `pip install ` in a Terminal window\n", + " - **Note:** Packages installed this way are temporary and only last for your current session\n", + "\n", + "\n", + "\"Open\n", + "\n", + "\n", + "**Starting fresh**\n", + "- The first time you start a session, it may take 1-2 minutes to build the environment\n", + "- If something breaks, you can always stop the session and start a new one\n", + "\n", + "### Troubleshooting\n", + "\n", + "| Problem | Solution |\n", + "|---------|----------|\n", + "| Session won't start | Wait 1-2 minutes - the environment is building |\n", + "| Lost your work | If you didn't stop the session, your files are still there. Resume the session to continue |\n", + "| Something broke | Stop the current session and start a fresh one |" + ] + }, { "cell_type": "markdown", "metadata": {}, @@ -368,7 +443,7 @@ "cell_type": "markdown", "metadata": {}, "source": [ - "# Exercises 🌶️\n", + "# Exercises\n", "\n", "For each topic we prepared a bunch of exercises to practice the concepts.\n", "\n", @@ -553,7 +628,7 @@ "name": "python", "nbconvert_exporter": "python", "pygments_lexer": "ipython3", - "version": "3.10.17" + "version": "3.12.12" }, "vscode": { "interpreter": { diff --git a/images/open_terminal.png b/images/open_terminal.png new file mode 100644 index 00000000..ffa73db9 Binary files /dev/null and b/images/open_terminal.png differ diff --git a/images/start_renku_session.png b/images/start_renku_session.png new file mode 100644 index 00000000..69cc31fe Binary files /dev/null and b/images/start_renku_session.png differ