From a7f57075c7c8bd3cffa88289dfdd22ada63045e6 Mon Sep 17 00:00:00 2001 From: atteggiani Date: Sat, 27 Apr 2024 11:26:46 +1000 Subject: [PATCH] Changed markdown + links in /docs/getting_started. Created custom-references tag to render references. --- .../community_data_processing.md | 2 +- .../community_med/index.md | 2 +- docs/getting_started/are.md | 232 ++++------ docs/getting_started/first_steps.md | 426 ++++++++---------- docs/getting_started/index.md | 4 +- docs/js/custom-tags.js | 43 ++ docs/js/support-level.js | 18 - mkdocs.yml | 2 +- testtest | 1 + 9 files changed, 335 insertions(+), 395 deletions(-) create mode 100644 docs/js/custom-tags.js delete mode 100644 docs/js/support-level.js create mode 100644 testtest diff --git a/docs/community_resources/community_med/community_data_processing.md b/docs/community_resources/community_med/community_data_processing.md index e4c2bc66a..9430de40b 100644 --- a/docs/community_resources/community_med/community_data_processing.md +++ b/docs/community_resources/community_med/community_data_processing.md @@ -1,6 +1,6 @@ # Community Processing Data Processing Tools - + If we are missing an important tool please let us know.
Check [How To Contribute](/about/contribute) to get in touch. diff --git a/docs/community_resources/community_med/index.md b/docs/community_resources/community_med/index.md index 23716ed20..cf53e689b 100644 --- a/docs/community_resources/community_med/index.md +++ b/docs/community_resources/community_med/index.md @@ -1,6 +1,6 @@ # Community Model Evaluation and Diagnostics Links - +
diff --git a/docs/getting_started/are.md b/docs/getting_started/are.md index fc2ec14a7..2d530dcb6 100644 --- a/docs/getting_started/are.md +++ b/docs/getting_started/are.md @@ -1,13 +1,14 @@ # Australian Research Environment (ARE) -ARE is a web-based graphical interface for performing your computational research, provided by NCI. -
-ARE can give you access to NCI’s Gadi supercomputer and data collections. +[ARE](https://are-auth.nci.org.au) is a web-based graphical interface for performing your computational research, provided by [NCI](https://nci.org.au/).
+ARE can give you access to NCI’s _Gadi_ supercomputer and data collections. -There are multiple applications included in ARE, but the two most used for ACCESS-related activities are Virtual Desktop (VDI) and JupyterLab. +There are multiple applications included in ARE, but the two most used for ACCESS-related activities are [Virtual Desktop (VDI)](#vdi) and [JupyterLab](#jupyterlab). ## Prerequisites -To use ARE, you must have an NCI account and be a member of a project with computing resources (SU). If you are new to ACCESS, follow the First Steps. +To use ARE, you must have an NCI account and be a member of a project with computing resources (SU).
+If you are new to ACCESS, follow the [First Steps](/getting_started/first_steps). + ## Start an ARE session
@@ -28,75 +29,54 @@ To use ARE, you must have an NCI account and be a member of a project with compu ### Session options -Launching an ARE session is similar to submitting an interactive PBS job that enables you to connect to a Gadi computing node. -
-Therefore, there are multiple PBS directives and other options you can select: -
    -
  • - Walltime (hours) -
    - Number of hours your VDI session will run for (unless manually ended earlier). -
    - The maximum number of hours an ARE session can run for depends on the selected Queue. For more information, check Gadi Queue Limits. -
    - Once the session ends any operation still in progress on the session's computing node(s) will be immediately terminated. -
    -
    • -
  • - Queue -
    - Gadi queue that your session will be scheduled in. For more information check Gadi Queue Structure. -
    • -
  • - Compute Size -
    - Amount of resources (CPUs, Memory, etc.) available to your session. -
    - You can either choose a pre-configured option, or select a custom one (e.g., cpus=6 mem=40G). -
    • -
  • - Project -
    - The NCI project the ARE session will be charged to. -
    - You must be a member of the specified project. -
    - The specified project must have allocated Service Units (SU). -
    - For more information, check how to join relevant NCI projects. -
    -
    • -
  • - Storage -
    - /g/data (inserted as gdata/<project-ID>) and /scratch (inserted as scratch/<project-ID>) data storage projects that will be available to the session. -
    - In ARE, data storage locations need to be explicitly defined. This means that you need to insert any /g/data and /scratch project folders you want to execute data I/O operations from. -
    - Multiple storage projects are separated by a plus (+) (e.g., gdata/tm70+gdata/hh5+scratch/xp65). -
    - Generally, you need to be a member of the specified projects to access their storage data. -
    - If you try to access data from a project folder not included in the session's storage, you will get an error similar to the following: -
    - <cmd>: cannot access '</path/to/file>': No such file or directory -
    -
    • -
  • - Software -
    - Software licenses that are requested for your ARE session. Leave blank if no license needed. -
    - Multiple licenses are separated by a colon (:). -
    • -

    Advanced options

    - -
    - -
    -
    - -
    +Launching an ARE session is similar to submitting an interactive [PBS job](https://opus.nci.org.au/display/Help/4.+PBS+Jobs) that enables you to connect to a _Gadi_ computing node.
    +Therefore, there are multiple [PBS directives](https://opus.nci.org.au/display/Help/PBS+Directives+Explained) and other options you can select: + +- **Walltime (hours)**
    + Number of hours your VDI session will run for (unless manually ended earlier).
    + The maximum number of hours an ARE session can run for depends on the selected Queue. For more information, check [Gadi Queue Limits](https://opus.nci.org.au/display/Help/Queue+Limits). + + !!! warning + Once the session ends any operation still in progress on the session's computing node(s) will be immediately terminated. + +- **Queue**
    + Gadi queue that your session will be scheduled in. For more information check [Gadi Queue Structure](https://opus.nci.org.au/display/Help/Queue+Structure). + +- **Compute Size**
    + Amount of resources (CPUs, Memory, etc.) available to your session.
    + You can either choose a pre-configured option, or select a custom one (e.g., _cpus=6 mem=40G_). + +- **Project**
    + The NCI project the ARE session will be charged to.
    + You must be a member of the specified project. + + !!! warning + The specified project must have allocated _Service Units (SU)_.
    + For more information, check [how to join relevant NCI projects](/getting_started/first_steps#join-relevant-nci-projects). + +- **Storage**
    + `/g/data` (inserted as _gdata/<project-ID>_) `/scratch` (inserted as _scratch/<project-ID>_) data storage projects that will be available to the session.
    + In ARE, data storage locations need to be explicitly defined. This means that you need to insert any `/g/data` and `/scratch` project folders you want to execute data I/O operations from.
    + Multiple storage projects are separated by a plus (_+_) (e.g., _gdata/tm70+gdata/hh5+scratch/xp65_). + + !!! warning + Generally, you need to be a member of the specified projects to access their storage data.
    + If you try to access data from a project folder not included in the session's storage, you will get an error similar to the following:
    + `: cannot access '': No such file or directory` + +- **Software**
    + Software licenses that are requested for your ARE session. Leave blank if no license needed.
    + Multiple licenses are separated by a colon (_:_). + +### Advanced options + +
    + +
    +
    + +
    +
    -
    +
- -
  • - Environment variables -
    - Environment variables passed to the session. Identical to the -v PBS directive. -
    - Multiple environment variables are separated by a comma (,). -
    • -
  • - Jobfs size -
    - The maximum amount of local disk available to the session. -
    - If missing, it is automatically set to 100MB. -
    • -
  • - PBS flags -
    - Extra PBS directives to be used for the ARE job submission. -
    • -
  • - Pre-script -
    - A script or executable that will be run just before starting the ARE session. -
    • - +
    + + +- **Environment variables**
    + Environment variables passed to the session. Identical to the [`-v` PBS directive](https://opus.nci.org.au/display/Help/PBS+Directives+Explained#PBSDirectivesExplained--v%3Cvar=10,%22var2='A,B'%22%3E).
    + Multiple environment variables are separated by a comma (_,_). + +- **Jobfs size**
    + The maximum amount of local disk available to the session.
    + If missing, it is automatically set to 100MB. + +- **PBS flags**
    + Extra [PBS directives](https://opus.nci.org.au/display/Help/PBS+Directives+Explained) to be used for the ARE job submission. + +- **Pre-script**
    + A script or executable that will be run just before starting the ARE session. ### Launch the session -
      -
    1. - Click on the Launch button to launch the session. - You will be prompted to your Interactive Sessions page and you will see your last requested session at the top. -
      2. -
    2. - -
      - -
      - Wait until your session starts and then click on the Launch VDI Desktop button to open a new tab with the VDI interface. -
      - Inside the VDI interface, you can open the terminal by clicking on the black terminal icon at the top of the window. -
      - -
      - Wait until your session starts and then click on the Open JupyterLab button to open a new tab with the JupyterLab interface. -
      - Inside the JupyterLab interface, you can open a new notebook by clicking on the Python3 Notebook button in the Launcher panel (to open a new Laucher panel, click on the plus button Plus button next to your current tab). -
      -
      - -
      3. + +1. Click on the Launch button to launch the session. You will be prompted to your Interactive Sessions page and you will see your last requested session at the top. + +2. +
      + Wait until your session starts and then click on the Launch VDI Desktop button to open a new tab with the VDI interface. +
      + Inside the VDI interface, you can open the terminal by clicking on the black terminal icon at the top of the window. Launch ARE VDI Desktop
      - +
      + Wait until your session starts and then click on the Open JupyterLab button to open a new tab with the JupyterLab interface. +
      + Inside the JupyterLab interface, you can open a new notebook by clicking on the Python3 Notebook button in the Launcher panel (to open a new Laucher panel, click on the plus button Plus button next to your current tab). Launch ARE JupyterLab
      -
    + ## Delete an ARE session -You can delete a session before its automatic expiration (based on the specified Walltime) by clicking on the session's Delete button Session Delete button in the Interactive Sessions page. - -
    -
    References
    - \ No newline at end of file +You can delete a session before its automatic expiration (based on the specified [Walltime](#walltime-option) by clicking on the session's ![Session Delete button](/assets/session_delete_button.png){: style="height:1em"} button in the [Interactive Sessions](https://are.nci.org.au/pun/sys/dashboard/batch_connect/sessions) page. + + +- [https://opus.nci.org.au/display/Help/ARE+User+Guide](https://opus.nci.org.au/display/Help/ARE+User+Guide) +- [https://are.nci.org.au/pun/sys/dashboard/batch_connect/sys/desktop_vnc/ncigadi/session_contexts/new](https://are.nci.org.au/pun/sys/dashboard/batch_connect/sys/desktop_vnc/ncigadi/session_contexts/new) +- [https://are.nci.org.au/pun/sys/dashboard/batch_connect/sys/jupyter/ncigadi/session_contexts/new](https://are.nci.org.au/pun/sys/dashboard/batch_connect/sys/jupyter/ncigadi/session_contexts/new) + \ No newline at end of file diff --git a/docs/getting_started/first_steps.md b/docs/getting_started/first_steps.md index a713e11f6..202b59434 100644 --- a/docs/getting_started/first_steps.md +++ b/docs/getting_started/first_steps.md @@ -7,279 +7,243 @@ The steps in this section are aimed at new users who would like to do any of the - Browse observational data catalogues - Evaluate model performance - Perform other tasks involving ACCESS models or evaluation tools -
    + ## Create an NCI user account -Most of the data and models you will need are available at the National Computing Infrastructure (NCI) . -
    -To access these, you need an NCI account. If you do not have one, sign up here. +Most of the data and models you will need are available at the [National Computing Infrastructure (NCI)](https://nci.org.au/about-us/who-we-are).
    +To access these, you need an [NCI account](https://opus.nci.org.au/display/Help/How+to+create+an+NCI+user+account). If you do not have one, [sign up here](https://my.nci.org.au/mancini/signup/0"). + +!!! warning + You will need an institutional email address with an organisation that allows access to NCI (e.g., an Australian university, ACCESS-NRI, CSIRO, BoM, CLEX, etc.). + +Once you sign up, you will be assigned a _username_ (e.g., `ab1234`). -
    -You will need an institutional email address with an organisation that allows access to NCI (e.g., an Australian university, ACCESS-NRI, CSIRO, BoM, CLEX, etc.). -
    -Once you sign up, you will be assigned a username (e.g., `ab1234`). -
    ## Join relevant NCI projects -NCI provides multiple services that are necessary for climate research. These include the access to supercomputing resources, data storage, and data collections management. +NCI provides multiple [services](https://nci.org.au/our-services) that are necessary for climate research. These include the access to supercomputing resources, data storage, and data collections management. For technical reasons, to access either of these services you need to join a specific `project`. -Each project has an ID (e.g. `xp65`), which is what the term project actually refers to. +Each project has an ID (e.g. `xp65`), which is what the term _project_ actually refers to. -If you are interested in datasets and data collections, you can browse the NCI Data Catalogue and follow the NCI Data Catalogue User Guide. +If you are interested in datasets and data collections, you can browse the [NCI Data Catalogue](https://geonetwork.nci.org.au/geonetwork/srv/eng/catalog.search#/search) and follow the [NCI Data Catalogue User Guide](https://opus.nci.org.au/display/Help/Data+Catalogue+User+Guide). -To run models on Gadi instead, you need to join a project with computing resources, also called Service Units (SU). The project ID will be provided by your supervisor, research project or institution. +To run models on _Gadi_ instead, you need to join a project with computing resources, also called _Service Units (SU)_. The project ID will be provided by your supervisor, research project or institution. -To join a project, search for it on NCI website and request membership. +To join a project, search for it on [NCI website](https://my.nci.org.au/mancini/project-search) and request membership. -
    - The first project you join will become your default one. If you would like to change this, check out how to change your default project on Gadi. -
    +!!! tip + The first project you join will become your default one. If you would like to change this, check out [how to change your default project on Gadi](/getting_started/first_steps#change-default-project-on-gadi). -There are several NCI projects that may be relevant to you, depending on the tasks you want to carry out. -
    +There are several NCI projects that may be relevant to you, depending on the tasks you want to carry out.
    For tasks supported by ACCESS-NRI (e.g., running a supported model configuration, using a supported model evaluation tool, etc.), you will find a list of relevant projects to join in the pages relative to each respective task. -
    ## Login to Gadi -Operations involving model runs and data collections take place on the Gadi supercomputer. - -Before you login to Gadi, you need to possess the following prerequisites: - -
      -
    • Internet connection
      • -
    • - Terminal with built-in SSH -
      - Linux, MacOS and Windows 10 (or later) operative systems already have a terminal with built-in SSH. -
      - Users of Windows 9 (or earlier) can install Windows Subsystems for Linux (WSL). -
      - Alternatively, you can login through the ARE Gadi Terminal. -
      - However, it is recommended that you connect to Gadi from your local machine's terminal without using ARE. -
      -
      • -
    +Operations involving model runs and data collections take place on the [_Gadi_ supercomputer](https://nci.org.au/our-systems/hpc-systems). + +Before you login to _Gadi_, you need to possess the following prerequisites: -To login to Gadi using SSH, on your **local machine's terminal** run the following command, replacing <your-NCI-username> with your NCI username (e.g., ab1234): +- **Internet connection** +- **Terminal with built-in SSH**
    + Linux, MacOS and Windows 10 (or later) operative systems already have a terminal with built-in SSH.
    + Users of Windows 9 (or earlier) can install [Windows Subsystems for Linux (WSL)](https://learn.microsoft.com/en-us/windows/wsl). + + !!! tip + Alternatively, you can login through the [ARE Gadi Terminal](https://are.nci.org.au/pun/sys/shell/ssh/gadi.nci.org.au).
    + However, it is recommended that you connect to _Gadi_ from your local machine's terminal without using ARE. -
    ssh <your-NCI-username>@gadi.nci.org.au
    +To login to _Gadi_ using [SSH](https://en.wikipedia.org/wiki/Secure_Shell), on your **local machine's terminal** run the following command, replacing `` with your NCI _username_ (e.g., `ab1234`): -You will be prompted to enter your NCI password, and then you will be connected to Gadi: +``` +ssh @gadi.nci.org.au +``` + +You will be prompted to enter your NCI password, and then you will be connected to _Gadi_: -ssh <your-NCI-username>@gadi.nci.org.au -<NCI-username>@gadi.nci.org.au's password: -############################################################################### -#           Welcome to the NCI National Facility!             # -#    This service is for authorised clients only. It is a criminal      # -#    offence to:                                      # -#          - Obtain access to data without permission;                 # -#          - Damage, delete, alter or insert data without permission;  # -#    Use of this system requires acceptance of the Conditions of Use;    # -#    published at https://nci.org.au/users/nci-terms-and-conditions-access; # -############################################################################### -|      gadi.nci.org.au - 260,760 processor InfiniBand x86_64 cluster     | -=============================================================================== -=============================================================================== - + ssh <your-NCI-username>@gadi.nci.org.au + <NCI-username>@gadi.nci.org.au's password: + ############################################################################### + #           Welcome to the NCI National Facility!             # + #    This service is for authorised clients only. It is a criminal      # + #    offence to:                                      # + #          - Obtain access to data without permission;                 # + #          - Damage, delete, alter or insert data without permission;  # + #    Use of this system requires acceptance of the Conditions of Use;    # + #    published at https://nci.org.au/users/nci-terms-and-conditions-access; # + ############################################################################### + |      gadi.nci.org.au - 260,760 processor InfiniBand x86_64 cluster     | + =============================================================================== + =============================================================================== + -### Auto login +### Automatic login To simplify the login and avoid being prompted every time to enter your NCI password, follow these steps: -
      -
    1. - Create an SSH key -
      - To create an SSH key on your local machine, run: - 
      ssh-keygen -t rsa -b 4096 -f ~/.ssh/id_gadi
      - You will be prompted to create a passphrase linked to the SSH key, which you will enter twice: +#### Create an SSH key +To create an SSH key on your **local machine**, run: +``` +ssh-keygen -t rsa -b 4096 -f ~/.ssh/id_gadi +``` +You will be prompted to create a passphrase linked to the SSH key, which you will enter twice: + + ssh-keygen -t rsa -b 4096 -f ~/.ssh/id_gadi + Generating public/private rsa key pair. + Enter passphrase (empty for no passphrase): + Enter same passphrase again: + Your identification has been saved in <$HOME>/.ssh/id_gadi + Your public key has been saved in /Users/davide/.ssh/id_gadi.pub + The key fingerprint is: + SHA256:<fingerprint-code> <$USER@hostname> + The key's randomart image is: + [RSA 4096-+ + |xxxxxxxxxxxxxxxxx| + |xxxxxxxxxxxxxxxxx| + |xxxxxxxxxxxxxxxxx| + |xxxxxxxxxxxxxxxxx| + |xxxxxxxxxxxxxxxxx| + |xxxxxxxxxxxxxxxxx| + |xxxxxxxxxxxxxxxxx| + |xxxxxxxxxxxxxxxxx| + -[SHA256--+ + + +!!! warning + For security reasons, it is recommended to enter a passphrase rather than leave it empty.
      + As you will see in the next step, you will not need to enter the passphrase every time you login to _Gadi_. + +#### Add the SSH key to the SSH-agent +An SSH-agent is an SSH key manager that avoids you having to enter your passphrase every time you connect to a server.
      +To add the SSH key to the SSH-agent: + +1. On your **local machine**, start the SSH-agent by running: + ``` + eval "$(ssh-agent -s)" + ``` - ssh-keygen -t rsa -b 4096 -f ~/.ssh/id_gadi - Generating public/private rsa key pair. - Enter passphrase (empty for no passphrase): - Enter same passphrase again: - Your identification has been saved in <$HOME>/.ssh/id_gadi - Your public key has been saved in /Users/davide/.ssh/id_gadi.pub - The key fingerprint is: - SHA256:<fingerprint-code> <$USER@hostname> - The key's randomart image is: - +---[RSA 4096]----+ - |xxxxxxxxxxxxxxxxx| - |xxxxxxxxxxxxxxxxx| - |xxxxxxxxxxxxxxxxx| - |xxxxxxxxxxxxxxxxx| - |xxxxxxxxxxxxxxxxx| - |xxxxxxxxxxxxxxxxx| - |xxxxxxxxxxxxxxxxx| - |xxxxxxxxxxxxxxxxx| - +----[SHA256]-----+ + eval "$(ssh-agent -s)" + Agent pid <agent-PID> -
      - For security reasons, it is recommended to enter a passphrase rather than leave it empty. -
      - As you will see in the next step, you will not need to enter the passphrase every time you login to Gadi. +2. Add your SSH key to the SSH-agent by running: + +
      + +
      -
      2. -
    2. - Add the SSH key to the SSH-agent -
      - An SSH-agent is an SSH key manager that avoids you having to enter your passphrase every time you connect to a server. -
      - To add the SSH key to the SSH-agent: -
        -
      1. - On your local machine, start the SSH-agent by running: - 
        eval "$(ssh-agent -s)"
        + +
        +
        + 
        ssh-add --apple-use-keychain ~/.ssh/id_gadi
        + You will be prompted to enter your SSH key passphrase, which will be stored inside the SSH-agent: - eval "$(ssh-agent -s)" - Agent pid <agent-PID> + ssh-add --apple-use-keychain ~/.ssh/id_gadi + Enter passphrase for <$HOME>/.ssh/id_gadi: + Identity added: <$HOME>/.ssh/id_gadi <$USER@hostname> -
        2. -
      2. - Add your SSH key to the SSH-agent by running: - -
        - - +
        + If you are using a MacOS version prior to Monterey (12.0), substitute the --apple-use-keychain flag with -K.
        - -
        - -
        - 
        ssh-add --apple-use-keychain ~/.ssh/id_gadi
        - You will be prompted to enter your SSH key passphrase, which will be stored inside the SSH-agent: - - ssh-add --apple-use-keychain ~/.ssh/id_gadi - Enter passphrase for <$HOME>/.ssh/id_gadi: - Identity added: <$HOME>/.ssh/id_gadi <$USER@hostname> - -
        - If you are using a MacOS version prior to Monterey (12.0), substitute the --apple-use-keychain flag with -K. -
        -
        - -
        - 
        ssh-add ~/.ssh/id_gadi
        - You will be prompted to enter your SSH key passphrase, which will be stored inside the SSH-agent: - - ssh-add ~/.ssh/id_gadi - Enter passphrase for <$HOME>/.ssh/id_gadi: - Identity added: <$HOME>/.ssh/id_gadi <$USER@hostname> - -
        - -
        3. -
      -
      3. -
    3. - Create/Update the SSH config file -
      - The ~/.ssh/config is a file where you can store labelled SSH configurations for different remote servers you regularly connect to, so you do not have to remember them all. -
      - To create an SSH config file, run the following command on your local machine: - 
      touch ~/.ssh/config
      -
      - If you already have an existing ~/.ssh/config file, the above command will not have any effect. -
      - The following lines should be added to your ~/.ssh/config to describe the SSH configuration for Gadi (replace <your-NCI-username> with your NCI username, e.g., ab1234): - 
      Host gadi
-    Hostname gadi.nci.org.au
-    User <your-NCI-username>
-    ForwardX11 true
-    ForwardX11Trusted yes
-    IdentityFile ~/.ssh/id_gadi
-    AddKeysToAgent yes
-    UseKeychain yes
      -
      - If you already have an existing ~/.ssh/config file which contains configurations for every Host (e.g., by using Host *), make sure you delete any of the keywords present in that SSH configuration from the Gadi configuration above. -
      -
      -
      4. -
    4. - Add the SSH key to the authorised keys -
      - To enable automatic connection to a server, that server needs to recognise the SSH key as authorised. The list of authorised keys for a certain server is stored in the file ~/.ssh/authorized_keys. -
      - To add the newly created SSH key as an authorised key for Gadi, run the following command from your local machine: - 
      var=$( cat ~/.ssh/id_gadi.pub ) && ssh gadi "echo $var >> .ssh/authorized_keys"
      -
      - Make sure to use double quotes " in the above command. + +
      + 
      ssh-add ~/.ssh/id_gadi
      + You will be prompted to enter your SSH key passphrase, which will be stored inside the SSH-agent: + + ssh-add ~/.ssh/id_gadi + Enter passphrase for <$HOME>/.ssh/id_gadi: + Identity added: <$HOME>/.ssh/id_gadi <$USER@hostname> + +
      - You will be prompted to enter your NCI password. If you did all of the above steps correctly, this should be the last time you need to do so. -
      5. -
    -Once you complete all the above steps, you should be able to connect to Gadi from your **local machine's terminal** simply by running: -
    ssh gadi
    + + +#### Create/Update the SSH config file +The `~/.ssh/config` is a file where you can store labelled SSH configurations for different remote servers you regularly connect to, so you do not have to remember them all.
    +To create an SSH config file, run the following command on your **local machine**: +``` +touch ~/.ssh/config +``` + +!!! tip + If you already have an existing `~/.ssh/config` file, the above command will not have any effect. + +The following lines should be added to your `~/.ssh/config` to describe the SSH configuration for _Gadi_ (replace `` with your NCI _username_, e.g., `ab1234`): +```ssh +Host gadi +Hostname gadi.nci.org.au +User <your-NCI-username> +ForwardX11 true +ForwardX11Trusted yes +IdentityFile ~/.ssh/id_gadi +AddKeysToAgent yes +UseKeychain yes +``` + +!!! warning + If you already have an existing `~/.ssh/config` file which contains configurations for any `Host` (e.g., by using `Host *`), make sure you delete any of the keywords present in that SSH configuration from the `Gadi` configuration above. + +#### Add the SSH key to the authorised keys +To enable automatic connection to a server, that server needs to recognise the SSH key as _authorised_. The list of authorised keys for a certain server is stored in the file `~/.ssh/authorized_keys`.
    +To add the newly created SSH key as an _authorised_ key for _Gadi_, run the following command from your **local machine**: +``` +ssh gadi "cat >> .ssh/authorized_keys <<< '$(cat ~/.ssh/id_gadi.pub)'" +``` + +You will be prompted to enter your NCI password. If you did all of the above steps correctly, this should be the last time you need to do so. + +Once you complete all the above steps, you should be able to connect to _Gadi_ from your **local machine's terminal** simply by running: +``` +ssh gadi +``` ### Change default project on Gadi -It is recommended that you check what your default project on Gadi is set to. The default project should be set to the computational project you will most likely use to run simulations/evaluations and store data. -
    -You can check which is your default project by logging into Gadi and running: - -
    echo $PROJECT
    - -To change your default project on Gadi, you need to manually change the `PROJECT` field in the `~/.config/gadi-login.conf` file. -
    -Alternatively, you can run the following command on Gadi's terminal: +It is recommended that you check what your default project on _Gadi_ is set to. The default project should be set to the computational project you will most likely use to run simulations/evaluations and store data.
    +You can check which is your default project by logging into _Gadi_ and running: +``` +echo $PROJECT +``` -
    sed "s/\(PROJECT \).*/\1<new-default-project>/" ~/.config/gadi-login.conf
    +To change your default project on _Gadi_, you need to manually change the `PROJECT` field in the `~/.config/gadi-login.conf` file.
    +Alternatively, you can run the following command **on _Gadi_'s terminal** (by substituting `` with the project you want to set as default): +``` +sed "s/\(PROJECT \)\w*/\1/" ~/.config/gadi-login.conf +``` -Once this is done, exit from Gadi and log back in. +Once this is done, exit from _Gadi_ and log back in.
    -For example, if you want to change your default project to `tm70` on Gadi: +For example, if you want to change your default project to `tm70` on _Gadi_: -echo $PROJECT - <old-default-project> - sed "s/\(PROJECT \).*/\1tm70/" ~/.config/gadi-login.conf - exit - logout - Connection to gadi.nci.org.au closed. - ssh gadi -############################################################################### -#           Welcome to the NCI National Facility!             # -#    This service is for authorised clients only. It is a criminal      # -#    offence to:                                      # -#          - Obtain access to data without permission;                 # -#          - Damage, delete, alter or insert data without permission;  # -#    Use of this system requires acceptance of the Conditions of Use;    # -#    published at https://nci.org.au/users/nci-terms-and-conditions-access; # -############################################################################### -|      gadi.nci.org.au - 260,760 processor InfiniBand x86_64 cluster     | -=============================================================================== -=============================================================================== -echo $PROJECT -tm70 + echo $PROJECT + <old-default-project> + sed "s/\(PROJECT \)\w*/\1tm70/" ~/.config/gadi-login.conf + exit + logout + Connection to gadi.nci.org.au closed. + ssh gadi + ############################################################################### + #           Welcome to the NCI National Facility!             # + #    This service is for authorised clients only. It is a criminal      # + #    offence to:                                      # + #          - Obtain access to data without permission;                 # + #          - Damage, delete, alter or insert data without permission;  # + #    Use of this system requires acceptance of the Conditions of Use;    # + #    published at https://nci.org.au/users/nci-terms-and-conditions-access; # + ############################################################################### + |      gadi.nci.org.au - 260,760 processor InfiniBand x86_64 cluster     | + =============================================================================== + =============================================================================== + echo $PROJECT + tm70 -
    - -
    References
    - + +- [https://nci.org.au](https://nci.org.au) +- [https://opus.nci.org.au/display/Help/0.+Welcome+to+Gadi](https://opus.nci.org.au/display/Help/0.+Welcome+to+Gadi) +- [https://docs.github.com/en/authentication/connecting-to-github-with-ssh/generating-a-new-ssh-key-and-adding-it-to-the-ssh-agent](https://docs.github.com/en/authentication/connecting-to-github-with-ssh/generating-a-new-ssh-key-and-adding-it-to-the-ssh-agent) +- [https://linuxize.com/post/using-the-ssh-config-file](https://linuxize.com/post/using-the-ssh-config-file) + diff --git a/docs/getting_started/index.md b/docs/getting_started/index.md index 02f606d64..e12dbc643 100644 --- a/docs/getting_started/index.md +++ b/docs/getting_started/index.md @@ -1,7 +1,7 @@ # Getting Started
    - +
    First Steps
    @@ -9,7 +9,7 @@ First Steps
    - +
    ARE
    diff --git a/docs/js/custom-tags.js b/docs/js/custom-tags.js new file mode 100644 index 000000000..60ec7e2fd --- /dev/null +++ b/docs/js/custom-tags.js @@ -0,0 +1,43 @@ +'use strict'; + +// Create an HTML tag to render the not-supported note +class NotSupported extends HTMLElement { + constructor() { + super(); + this.outerHTML = `
    +NOT directly supported by ACCESS-NRI +

    +The information below can be useful for the ACCESS community, +but is not directly supported by ACCESS-NRI, unless stated otherwise. +

    +
    +` + } +} + +// Create an HTML tag to render the references +class References extends HTMLElement { + constructor() { + super(); + let inner = this.innerHTML.split("\n") + let ul = document.createElement("ul") + inner.forEach((item) => { + item = item.trim() + if (item != "") { + console.log(item) + let li = document.createElement("li") + item.startsWith('- ') ? li.innerHTML = item.slice(2) : li.innerHTML = item + ul.appendChild(li) + } + }) + this.innerHTML = `
    +
    References
    +
    + ${ul.outerHTML} +
    + ` + } +} + +customElements.define("custom-not-supported", NotSupported) +customElements.define("custom-references", References) \ No newline at end of file diff --git a/docs/js/support-level.js b/docs/js/support-level.js deleted file mode 100644 index 07b4e60d7..000000000 --- a/docs/js/support-level.js +++ /dev/null @@ -1,18 +0,0 @@ -'use strict'; - -// Create an HTML tag to render the support level note -class NotSupported extends HTMLElement { - constructor() { - super(); - this.outerHTML = `
    -NOT directly supported by ACCESS-NRI -

    -The information below can be useful for the ACCESS community, -but is not directly supported by ACCESS-NRI, unless stated otherwise. -

    -
    -` - } -} - -customElements.define("not-supported", NotSupported) \ No newline at end of file diff --git a/mkdocs.yml b/mkdocs.yml index 18ddfa3b6..0451eea70 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -222,4 +222,4 @@ extra_javascript: - https://unpkg.com/tablesort@5.3.0/dist/tablesort.min.js # For tablesort functionality - https://cdn.jsdelivr.net/gh/atteggiani/animated-terminal@2.1/animated-terminal.min.js # Terminal animations - js/miscellaneous.js - - js/support-level.js + - js/custom-tags.js diff --git a/testtest b/testtest new file mode 100644 index 000000000..558d098dd --- /dev/null +++ b/testtest @@ -0,0 +1 @@ +ciao mamma