diff --git a/docs/css/access-nri.css b/docs/css/access-nri.css index 2a7827690..086c74ec5 100644 --- a/docs/css/access-nri.css +++ b/docs/css/access-nri.css @@ -164,7 +164,7 @@ h2 { } h3 { - margin: 1em 0 0.4em !important; + margin: 1.3em 0 0.4em !important; } /* =============================================================== diff --git a/docs/get_started/index.md b/docs/get_started/index.md index 0e6a41b47..6e358426b 100644 --- a/docs/get_started/index.md +++ b/docs/get_started/index.md @@ -12,6 +12,7 @@ If you are new to climate science or ACCESS models, and - Perform other tasks involving ACCESS Models You will need to follow these steps to get started with any of the tasks above. +
## Create an NCI user account Most of the data and models you will need are available at the National Computing Infrastructure (NCI) . @@ -23,7 +24,9 @@ To be able to access them, you need an NCI account.
If you don't think you possess an email address with such institution, please get in contact. +
Once you sign up, you will be assigned a username (e.g. `ab1234`). We will also refer to this username as `$USER`. +
## Join relevant NCI projects To join a project, search for it on NCI website and request membership. @@ -68,6 +71,7 @@ Even though we recommend you have a chat with your supervisor to identify the re | m18 | Evolution and dynamics of the Australian lithosphere | Other projects | | q97 | Earth dynamics and resources over the last billion years | Other projects | | qu79 | Collaborative REAnalysis Technical Environment Intercomparison Project (CREATE-IP) | Other projects | +
## Log in to Gadi Operations such as model runs and output data I/O take place on the Gadi supercomputer. @@ -89,10 +93,10 @@ To log in to Gadi you need a few pre-requisites: To log in to Gadi we use SSH. The basic command is: -
ssh <NCI-username>@gadi.nci.org.au
+
ssh <your-NCI-username>@gadi.nci.org.au
You will be asked for your NCI password and then you will get connected to Gadi: - ssh <NCI-username>@gadi.nci.org.au + ssh <your-NCI-username>@gadi.nci.org.au <NCI-username>@gadi.nci.org.au's password: ############################################################################### #           Welcome to the NCI National Facility!             # @@ -111,29 +115,131 @@ You will be asked for your NCI password and then you will get connected to Ga ### Automate the log in step To simplify the log in step and avoid having to always insert your NCI password, there are a few steps we suggest you to follow: +
    -
  1. - Create an SSH key -
    -
    2. -
  2. - Create/Update the ssh config file -
    -
    3. -
  3. - Add the ssh key to the gpg agent -
    -
    4. +
  4. + Create an SSH key +
    + To create an SSH key, in your terminal, run: + 
    ssh-keygen -t rsa -b 4096 -f ~/.ssh/id_gadi
    + You will be asked to create a passphrase linked to the SSH key, and insert it 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]-----+ + +
    + We suggest you don't leave the passphrase empty for security reason. +
    + As you will see in the next step, you will not need to insert the passphrase every time you log in to Gadi. +
    +
    5. +
  5. + Add the SSH key to the ssh-agent +
    + An ssh-agent is an SSH key manager that avoids you having to type a passphrase every time you connect to a server. +
    + To add the SSH key to the ssh-agent: +
      +
    1. + In your terminal, start the ssh-agent by running: + 
      eval "$(ssh-agent -s)"
      + + eval "$(ssh-agent -s)" + Agent pid <agent-PID> + +
      2. +
    2. + Add your SSH key to the ssh-agent by running: + 
      ssh-add --apple-use-keychain ~/.ssh/id_gadi
      + You will be asked for the 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 running a MacOS versions prior to Monterey (12.0), the --apple-use-keychain flag needs to be substituted with -K. +
      +
      3. +
    +
    6. +
  6. + Create/Update the SSH config file +
    + The ~/.ssh/config file is a file where you can store the SSH configurations for different servers, labeled so you don't have to remember them. +
    + To create your ssh config file, in your terminal, run: + 
    touch ~/.ssh/config
    +
    + If you already have an existing ~/.ssh/config file, the command above will not have any effect. +
    + To store the SSH configurations for Gadi in the SSH config file, you can add the following lines to your ~/.ssh/config file: + 
    Host gadi
+       Hostname gadi.nci.org.au
+       User <your-NCI-username>
+       ForwardX11 true
+       ForwardX11Trusted yes
+       IdentityFile ~/.ssh/id_gadi
+
    +
- Once you complete all the above steps, you will be able to connect to Gadi simply by running: 
ssh gadi
### Change default project on Gadi It is recommended that you change your default project on Gadi, as this might be used by tasks such as running a model or model evaluation. - -
+To check which is your default project, on Gadi, run: +
echo $PROJECT
+If you want to change your default project, on Gadi you should manually change the `PROJECT` field in the `~/.config/gadi-login.conf` file, exit from Gadi, and log back in. +
+Alternatively, on Gadi you can run: +
sed "s/\(PROJECT \).*/\1<new-default-project>/" ~/.config/gadi-login.conf
+exit from Gadi, and log back in. +
+For example, if you want to change your default project to `tm70`, on Gadi, run: + + 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 http://nci.org.au/users/nci-terms-and-conditions-access; # + ############################################################################### + |      gadi.nci.org.au - 260,760 processor InfiniBand x86_64 cluster     | + =============================================================================== + =============================================================================== + echo $PROJECT + tm70 + +
+
References
diff --git a/mkdocs.yml b/mkdocs.yml index e3541d3e6..1f8493f4a 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -42,6 +42,7 @@ theme: - content.action.view - content.code.copy # for displaying copy icon at top right in code snippets - content.code.annotate + - content.tabs.link - search.suggest - search.highlight - search.share