tutorials/01-Setup-and-connect.ipynb

{
 "cells": [
  {
   "cell_type": "markdown",
   "id": "b37a773f",
   "metadata": {},
   "source": [
    "# Setup and connect to iRODS"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "610d2838",
   "metadata": {},
   "source": [
    "## The iRODS environment file"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "466e791e",
   "metadata": {},
   "source": [
    "To connect to a specific iRODS instance you will need a so-called `irods_environment.json` file. This file contains all parameters to establish the connection. Your iRODS sysadmin or service provider will give you such an environment file."
   ]
  },
  {
   "cell_type": "markdown",
   "id": "c0dec8b5",
   "metadata": {},
   "source": [
    "When you are working with Yoda, you can find the information by clicking on the Yoda version label on the bottom of the Yoda portal **after you logged into the portal**.\n",
    "\n",
    "<img src=\"img/Yoda_environment.png\" align=\"center\" width=\"200\"/>"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "1fecf346",
   "metadata": {},
   "source": [
    "## Required information to connect to iRODS"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "0763be04",
   "metadata": {},
   "source": [
    "The `irods_envirnment.json` needs to contain the following information:\n",
    "\n",
    "```\n",
    "{\n",
    "\"irods_host\": \"<SERVER ADDRESS>\",\n",
    "\"irods_port\": 1247,\n",
    "\"irods_home\": \"<YOUR CURRENT WORKING DIRECTORY>\",\n",
    "\"irods_user_name\": \"<YOUR USERNAME>\",\n",
    "\"irods_zone_name\": \"<ZONE NAME>\",\n",
    "\"irods_authentication_scheme\": \"pam\",\n",
    "\"irods_encryption_algorithm\": \"AES-256-CBC\",\n",
    "\"irods_encryption_key_size\": 32,\n",
    "\"irods_encryption_num_hash_rounds\": 16,\n",
    "\"irods_encryption_salt_size\": 8,\n",
    "\"irods_client_server_policy\": \"CS_NEG_REQUIRE\",\n",
    "\"irods_client_server_negotiation\": \"request_server_negotiation\"\n",
    "}\n",
    "```\n",
    "Apart from your user name all settings should be given by your iRODS service provider.\n",
    "\n",
    "**Important**: please make sure that the parameter `\"irods_client_server_policy\": \"CS_NEG_REQUIRE\",` is there!"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "b9ce1bf1",
   "metadata": {},
   "source": [
    "## Additional information"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "57f676d6",
   "metadata": {},
   "source": [
    "- The `\"irods_home\"` functions similarly to a \"current working directory\" and you will be be guided to that location automatically. So we encourage you to set it to a valid location for your project.\n",
    "\n",
    "    - Plain iRODS: `\"irods_home\": \"/<ZONE NAME>/home/<YOUR USERNAME>\"`.\n",
    "\n",
    "    - Yoda: `\"irods_home\": \"/<ZONE NAME>/home/research-<YOUR GROUP>\"`\n",
    "    \n",
    "\n",
    "- We also encourage you to ask your iRODS provider about the `\"irods_default_resource\"`. \n",
    "    In most Yoda instances this is `\"irods_default_resource\": \"irodsResc\"`.\n",
    "\n",
    "Both of the settings are not essential but will make it easier and less error-prone when working with data in iRODS. The `\"irods_home\"` can also be changed later."
   ]
  },
  {
   "cell_type": "markdown",
   "id": "a1e82b29",
   "metadata": {},
   "source": [
    "## Where to put the irods_environment.json?"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "1ba9bf4c",
   "metadata": {},
   "source": [
    "All iRODS clients (icommands and APIs) expect the above parameters to be stored in a special folder. This folder is called `.irods` and it lies in your home directory:\n",
    "- Mac: `/Users/<user>/.irods`\n",
    "- Linux: `/home/<user>/.irods`\n",
    "- Windows: `C:\\Users\\<user>\\.irods`\n",
    "\n",
    "In Mac and Linux you can simply create the folder manually in the file browser.\n",
    "The `.` shows that it is a hidden folder, which can be quite difficult to create in Windows. Below we provide a python cde snippet which creates the folder:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "5196436f",
   "metadata": {},
   "outputs": [],
   "source": [
    "Path.mkdir"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "e9c74026",
   "metadata": {},
   "outputs": [],
   "source": [
    "from pathlib import Path\n",
    "\n",
    "loc = Path.expanduser(Path('~')).joinpath(\".irods\")\n",
    "if not loc.exists():\n",
    "    loc.mkdir()"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "d404e8d0",
   "metadata": {},
   "source": [
    "Please store your `irods_environment.json` in that folder and make sure that its extension is `json`. \n",
    "\n",
    "Again under Windows the text editors usually safe files with the `.txt` extension. So please watch out for this.\n",
    "Below we provide a code snippet which saves your personal iRODS/Yoda information in the right place. Please adjust:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "d8ac6622",
   "metadata": {},
   "outputs": [],
   "source": [
    "import json\n",
    "env = {\n",
    "    \"irods_host\": \"<FILL_IN>\",\n",
    "    \"irods_port\": 1247,\n",
    "    \"irods_home\": \"<FILL_IN>\",\n",
    "    \"irods_user_name\": \"<FILL_IN>\",\n",
    "    \"irods_zone_name\": \"<FILL_IN>\",\n",
    "    \"irods_default_resource\": \"<FILL_IN>\",\n",
    "    \"irods_authentication_scheme\": \"pam\",\n",
    "    \"irods_client_server_policy\": \"CS_NEG_REQUIRE\",\n",
    "    \"irods_client_server_negotiation\": \"request_server_negotiation\",\n",
    "    \"irods_encryption_algorithm\": \"AES-256-CBC\",\n",
    "    \"irods_encryption_key_size\": 32,\n",
    "    \"irods_encryption_num_hash_rounds\": 16,\n",
    "    \"irods_encryption_salt_size\": 8\n",
    "}\n",
    "loc = Path.expanduser(Path('~')).joinpath(\".irods\", \"irods_environment.json\")\n",
    "with open(loc, 'w') as write_json:\n",
    "    json.dump(env, write_json)"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "da3ea9e2",
   "metadata": {},
   "source": [
    "If your settings are saved correctly under Windows, you should see this file in `C:\\Users\\<user>\\.irods`.\n",
    "\n",
    "<img src=\"img/Save_json.png\">\n",
    "\n",
    "Some last check, if the output is `True` all is setup correctly:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "f01e88f2",
   "metadata": {},
   "outputs": [],
   "source": [
    "loc = Path.expanduser(Path('~')).joinpath(\".irods\", \"irods_environment.json\")\n",
    "Path.is_file(loc)"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "a1648345",
   "metadata": {},
   "source": [
    "## Connecting to iRODS"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "460db0d9",
   "metadata": {},
   "source": [
    "### Interactively creating an  iRODS session"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "acede9da",
   "metadata": {},
   "source": [
    "When you are working interactively in a jupyter notebook or another environment, we can use the following way of connecting:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "c047bf20",
   "metadata": {},
   "outputs": [],
   "source": [
    "from ibridges.interactive import interactive_auth\n",
    "session = interactive_auth()"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "8837188d",
   "metadata": {},
   "source": [
    "This command reads in the information from your `irods_environment.json`; it tries to find a cached password in the `.irods` folder and asks you for your password, in case there is no cached password. \n",
    "Upon successful login, the command/function stores your password in a scrambled way so that the next time you will not be bothered with typing in the password again.\n",
    "\n",
    "Let's see what happens if we rerun this command. We will first delete the current session and login again:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "cb564f71",
   "metadata": {},
   "outputs": [],
   "source": [
    "del session\n",
    "session = interactive_auth()"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "7f9dd9b3",
   "metadata": {},
   "source": [
    "You see, that `interactive_auth` still remembers the password from the last time you logged in. **NOTE, that the cached password will expire at some point!**"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "29aa5a45",
   "metadata": {},
   "source": [
    "### Connecting by passing a password"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "20a3b231",
   "metadata": {},
   "source": [
    "In some programming situations you cannot interactively pass a password. For these cases `iBridges` provides you with another function to connect:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "cd07d90f",
   "metadata": {},
   "outputs": [],
   "source": [
    "from ibridges import Session\n",
    "env_file = Path.expanduser(Path('~')).joinpath(\".irods\", \"irods_environment.json\")\n",
    "password = <YOUR PASSWORD>\n",
    "\n",
    "session = Session(irods_env_path=env_file, password=password)"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "ac22dfc7",
   "metadata": {},
   "source": [
    "## What is this session thing?"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "71376db2",
   "metadata": {},
   "source": [
    "The `session` stores all information from your `irods_environment.json`, it provides you with even more information about the iRODS you are connected to and it is needed for all interactions with iRODS.\n",
    "\n",
    "Let's ave a look:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "d4d14991",
   "metadata": {},
   "outputs": [],
   "source": [
    "print(session.username)\n",
    "print(session.default_resc) # the resource to which data will be uploaded\n",
    "print(session.zone) \n",
    "print(session.server_version)\n",
    "print(session.home) # default home for iRODS /zone/home/username"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "0a34d792",
   "metadata": {},
   "source": [
    "You will see some information about you as a user on iRODS. The last statement shows your current working location on iRODS.\n",
    "**Note that it is not verified that this location exists!**. Let's have a closer look."
   ]
  },
  {
   "cell_type": "markdown",
   "id": "64d1e7c7",
   "metadata": {},
   "source": [
    "## The iRODS home"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "33bffc91",
   "metadata": {},
   "source": [
    "Let us verify that the current working location ineed exists:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "6d06932a",
   "metadata": {},
   "outputs": [],
   "source": [
    "from ibridges.path import IrodsPath\n",
    "irods_path = IrodsPath(session, session.home)\n",
    "irods_path.collection_exists()"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "a06f0c7d",
   "metadata": {},
   "source": [
    "We create an `IrodsPath` which is not a simple text or string, but which is actually connected to iRODS through the `session`. With that we can ask iRODS wether the path indeed is a collection (similar to folder, see chapter about Data).\n",
    "\n",
    "In case the last command gave you a `False`, do not despair. You can set this parameter with."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "619e1f5b",
   "metadata": {},
   "outputs": [],
   "source": [
    "session.home = \"<YOUR NEW iRODS PATH>\""
   ]
  },
  {
   "cell_type": "markdown",
   "id": "efa0b4b5",
   "metadata": {},
   "source": [
    "Another way to access the current iRODS home is the `~`. Linux and Mac users might know this notation:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "5590a92d",
   "metadata": {},
   "outputs": [],
   "source": [
    "print(IrodsPath(session, \"~\"))"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "7e49aea2",
   "metadata": {},
   "outputs": [],
   "source": []
  }
 ],
 "metadata": {
  "kernelspec": {
   "display_name": "Python 3 (ipykernel)",
   "language": "python",
   "name": "python3"
  },
  "language_info": {
   "codemirror_mode": {
    "name": "ipython",
    "version": 3
   },
   "file_extension": ".py",
   "mimetype": "text/x-python",
   "name": "python",
   "nbconvert_exporter": "python",
   "pygments_lexer": "ipython3",
   "version": "3.10.13"
  }
 },
 "nbformat": 4,
 "nbformat_minor": 5
}