Skip to content

Commit

Permalink
Complete page. Needs different tabs for different Systems
Browse files Browse the repository at this point in the history
  • Loading branch information
@atteggiani
atteggiani committed Jul 18, 2023
1 parent 4067f19 commit 1822cfe
Show file tree
Hide file tree
Showing 3 changed files with 131 additions and 18 deletions.
2 changes: 1 addition & 1 deletion docs/css/access-nri.css
View file
Original file line number Diff line number Diff line change
Expand Up @@ -164,7 +164,7 @@ h2 {
}

h3 {
margin: 1em 0 0.4em !important;
margin: 1.3em 0 0.4em !important;
}

/* ===============================================================
Expand Down
146 changes: 129 additions & 17 deletions docs/get_started/index.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -12,6 +12,7 @@ If you are new to climate science or <a href="../models/">ACCESS models</a>, and
- Perform other tasks involving ACCESS Models

You will need to follow these steps to get started with any of the tasks above.
<hr>

## Create an NCI user account
Most of the data and models you will need are available at the <a href="https://nci.org.au/about-us/who-we-are" target="_blank">National Computing Infrastructure (NCI) </a>.
Expand All @@ -23,7 +24,9 @@ To be able to access them, you need an NCI account.
<br>
If you don't think you possess an email address with such institution, please <a href="https://www.access-nri.org.au/contact/" target="_blank">get in contact</a>.
</div>
<br>
Once you sign up, you will be assigned a <i>username</i> (e.g. `ab1234`). We will also refer to this <i>username</i> as `$USER`.
<hr>

## Join relevant NCI projects
To join a project, search for it on <a href="https://my.nci.org.au/mancini/project-search" target="_blank">NCI website</a> and request membership.
Expand Down Expand Up @@ -68,6 +71,7 @@ Even though we recommend you have a chat with your supervisor to identify the re
| m18 | <a href="https://my.nci.org.au/mancini/project/m18" target="_blank">Evolution and dynamics of the Australian lithosphere</a> | Other projects |
| q97 | <a href="https://my.nci.org.au/mancini/project/q97" target="_blank">Earth dynamics and resources over the last billion years</a> | Other projects |
| qu79 | <a href="https://my.nci.org.au/mancini/project/qu79" target="_blank">Collaborative REAnalysis Technical Environment Intercomparison Project (CREATE-IP)</a> | Other projects |
<hr>

## Log in to Gadi
Operations such as model runs and output data I/O take place on the <a href="https://nci.org.au/our-systems/hpc-systems" target="_blank">Gadi supercomputer</a>.
Expand All @@ -89,10 +93,10 @@ To log in to <i>Gadi</i> you need a few pre-requisites:

To log in to <i>Gadi</i> we use <a href="https://en.wikipedia.org/wiki/Secure_Shell" target="_blank">SSH</a>.
The basic command is:
<pre><code>ssh &lt;NCI-username&gt;@gadi.nci.org.au</code></pre>
<pre><code>ssh &lt;your-NCI-username&gt;@gadi.nci.org.au</code></pre>
You will be asked for your NCI password and then you will get connected to <i>Gadi</i>:
<terminal-animation lineDelay=0>
<terminal-line data="input" lineDelay=300>ssh &lt;NCI-username&gt;@gadi.nci.org.au</terminal-line>
<terminal-line data="input" lineDelay=300>ssh &lt;your-NCI-username&gt;@gadi.nci.org.au</terminal-line>
<terminal-line lineDelay=300>&lt;NCI-username&gt;@gadi.nci.org.au's password: <i class="icon-key" style="display: inline-block; font-size: 0.4em; transform: rotate(-90deg);"></i></terminal-line>
<terminal-line lineDelay=3000>###############################################################################</terminal-line>
<terminal-line>#&emsp;&emsp;&emsp;&emsp;&emsp;&emsp;&emsp;&emsp;&emsp;&emsp;&emsp;Welcome to the NCI National Facility!&emsp;&emsp;&emsp;&emsp;&emsp;&emsp;&emsp;&emsp;&emsp;&emsp;&emsp;&emsp;&emsp;#</terminal-line>
Expand All @@ -111,29 +115,131 @@ You will be asked for your NCI password and then you will get connected to <i>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:

<ol>
<li>
<b>Create an SSH key</b>
<br>
</li>
<li>
<b>Create/Update the ssh config file</b>
<br>
</li>
<li>
<b>Add the ssh key to the gpg agent</b>
<br>
</li>
<li>
<b>Create an SSH key</b>
<br>
To create an SSH key, in your terminal, run:
<pre><code>ssh-keygen -t rsa -b 4096 -f ~/.ssh/id_gadi</code></pre>
You will be asked to create a passphrase linked to the SSH key, and insert it twice:
<terminal-animation>
<terminal-line data="input">ssh-keygen -t rsa -b 4096 -f ~/.ssh/id_gadi</terminal-line>
<terminal-line>Generating public/private rsa key pair.</terminal-line>
<terminal-line>Enter passphrase (empty for no passphrase):</terminal-line>
<terminal-line lineDelay=3000>Enter same passphrase again:</terminal-line>
<terminal-line lineDelay=3000>Your identification has been saved in &lt;$HOME&gt;/.ssh/id_gadi</terminal-line>
<terminal-line>Your public key has been saved in /Users/davide/.ssh/id_gadi.pub</terminal-line>
<terminal-line lineDelay=0>The key fingerprint is:</terminal-line>
<terminal-line lineDelay=0>SHA256:&lt;fingerprint-code&gt; &lt;$USER@hostname&gt;</terminal-line>
<terminal-line lineDelay=0>The key's randomart image is:</terminal-line>
<terminal-line lineDelay=0>+---[RSA 4096]----+</terminal-line>
<terminal-line lineDelay=0>|xxxxxxxxxxxxxxxxx|</terminal-line>
<terminal-line lineDelay=0>|xxxxxxxxxxxxxxxxx|</terminal-line>
<terminal-line lineDelay=0>|xxxxxxxxxxxxxxxxx|</terminal-line>
<terminal-line lineDelay=0>|xxxxxxxxxxxxxxxxx|</terminal-line>
<terminal-line lineDelay=0>|xxxxxxxxxxxxxxxxx|</terminal-line>
<terminal-line lineDelay=0>|xxxxxxxxxxxxxxxxx|</terminal-line>
<terminal-line lineDelay=0>|xxxxxxxxxxxxxxxxx|</terminal-line>
<terminal-line lineDelay=0>|xxxxxxxxxxxxxxxxx|</terminal-line>
<terminal-line lineDelay=0>+----[SHA256]-----+</terminal-line>
</terminal-animation>
<div class="note">
We suggest you don't leave the passphrase empty for security reason.
<br>
As you will see in the next step, you will not need to insert the passphrase every time you log in to <i>Gadi</i>.
</div>
</li>
<li>
<b>Add the SSH key to the ssh-agent</b>
<br>
An ssh-agent is an SSH key manager that avoids you having to type a passphrase every time you connect to a server.
<br>
To add the SSH key to the ssh-agent:
<ol>
<li>
In your terminal, start the ssh-agent by running:
<pre><code>eval "$(ssh-agent -s)"</code></pre>
<terminal-animation>
<terminal-line data="input">eval "$(ssh-agent -s)"</terminal-line>
<terminal-line>Agent pid &lt;agent-PID&gt;</terminal-line>
</terminal-animation>
</li>
<li>
Add your SSH key to the ssh-agent by running:
<pre><code>ssh-add --apple-use-keychain ~/.ssh/id_gadi</code></pre>
You will be asked for the SSH key passphrase, which will be stored inside the ssh-agent:
<terminal-animation>
<terminal-line data="input">ssh-add --apple-use-keychain ~/.ssh/id_gadi</terminal-line>
<terminal-line>Enter passphrase for &lt;$HOME&gt;/.ssh/id_gadi:</terminal-line>
<terminal-line lineDelay=3000>Identity added: &lt;$HOME&gt;/.ssh/id_gadi &lt;$USER@hostname&gt;</terminal-line>
</terminal-animation>
<div class="note">
If you are running a MacOS versions prior to Monterey (12.0), the <code>--apple-use-keychain</code> flag needs to be substituted with <code>-K</code>.
</div>
</li>
</ol>
</li>
<li>
<b>Create/Update the SSH config file</b>
<br>
The <code>~/.ssh/config</code> file is a file where you can store the SSH configurations for different servers, labeled so you don't have to remember them.
<br>
To create your ssh config file, in your terminal, run:
<pre><code>touch ~/.ssh/config</code></pre>
<div class="note">
If you already have an existing <code>~/.ssh/config</code> file, the command above will not have any effect.
</div>
To store the SSH configurations for <i>Gadi</i> in the SSH config file, you can add the following lines to your <code>~/.ssh/config</code> file:
<pre><code>Host gadi
&emsp;Hostname gadi.nci.org.au
&emsp;User &lt;your-NCI-username&gt;
&emsp;ForwardX11 true
&emsp;ForwardX11Trusted yes
&emsp;IdentityFile ~/.ssh/id_gadi
</code></pre>
</li>
</ol>

Once you complete all the above steps, you will be able to connect to <i>Gadi</i> simply by running:
<pre><code>ssh gadi</code></pre>

### Change default project on Gadi
It is recommended that you change your default project on <i>Gadi</i>, as this might be used by tasks such as running a model or model evaluation.


<br>
To check which is your default project, on <i>Gadi</i>, run:
<pre><code>echo $PROJECT</code></pre>
If you want to change your default project, on <i>Gadi</i> you should manually change the `PROJECT` field in the `~/.config/gadi-login.conf` file, exit from <i>Gadi</i>, and log back in.
<br>
Alternatively, on <i>Gadi</i> you can run:
<pre><code>sed "s/\(PROJECT \).*/\1&lt;new-default-project&gt;/" ~/.config/gadi-login.conf</code></pre>
exit from <i>Gadi</i>, and log back in.
<br>
For example, if you want to change your default project to `tm70`, on <i>Gadi</i>, run:
<terminal-animation>
<terminal-line data="input">echo $PROJECT</terminal-line>
<terminal-line>&lt;old-default-project&gt;</terminal-line>
<terminal-line data="input">sed "s/\(PROJECT \).*/\1tm70/" ~/.config/gadi-login.conf</terminal-line>
<terminal-line data="input">exit</terminal-line>
<terminal-line>logout</terminal-line>
<terminal-line>Connection to gadi.nci.org.au closed.</terminal-line>
<terminal-line data="input" PS1="<span style='color: #897a36;'>(User PC)$ </span>">ssh gadi</terminal-line>
<terminal-line>###############################################################################</terminal-line>
<terminal-line lineDelay=0>#&emsp;&emsp;&emsp;&emsp;&emsp;&emsp;&emsp;&emsp;&emsp;&emsp;&emsp;Welcome to the NCI National Facility!&emsp;&emsp;&emsp;&emsp;&emsp;&emsp;&emsp;&emsp;&emsp;&emsp;&emsp;&emsp;&emsp;#</terminal-line>
<terminal-line lineDelay=0>#&emsp;&emsp;&emsp;&emsp;This service is for authorised clients only. It is a criminal&emsp;&emsp;&emsp;&emsp;&emsp;&nbsp;#</terminal-line>
<terminal-line lineDelay=0>#&emsp;&emsp;&emsp;&emsp;offence to:&emsp;&emsp;&emsp;&emsp;&emsp;&emsp;&emsp;&emsp;&emsp;&emsp;&emsp;&emsp;&emsp;&emsp;&emsp;&emsp;&emsp;&emsp;&emsp;&emsp;&emsp;&emsp;&emsp;&emsp;&emsp;&emsp;&emsp;&emsp;&emsp;&emsp;&emsp;&emsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;#</terminal-line>
<terminal-line lineDelay=0>#&emsp;&emsp;&emsp;&emsp;&emsp;&emsp;&emsp;&emsp;&emsp;&emsp;- Obtain access to data without permission;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&emsp;#</terminal-line>
<terminal-line lineDelay=0>#&emsp;&emsp;&emsp;&emsp;&emsp;&emsp;&emsp;&emsp;&emsp;&emsp;- Damage, delete, alter or insert data without permission;&emsp;&nbsp;#</terminal-line>
<terminal-line lineDelay=0>#&emsp;&emsp;&emsp;&emsp;Use of this system requires acceptance of the Conditions of Use;&emsp;&emsp;&emsp;&emsp;#</terminal-line>
<terminal-line lineDelay=0>#&emsp;&emsp;&emsp;&emsp;published at http://nci.org.au/users/nci-terms-and-conditions-access;&emsp;#</terminal-line>
<terminal-line lineDelay=0>###############################################################################</terminal-line>
<terminal-line lineDelay=0>|&emsp;&emsp;&emsp;&emsp;&emsp;&emsp;gadi.nci.org.au - 260,760 processor InfiniBand x86_64 cluster&emsp;&emsp;&nbsp;&nbsp;&nbsp;|</terminal-line>
<terminal-line lineDelay=0>===============================================================================</terminal-line>
<terminal-line lineDelay=0>===============================================================================</terminal-line>
<terminal-line data="input">echo $PROJECT</terminal-line>
<terminal-line>tm70</terminal-line>
</terminal-animation>
<hr>

<h6>References</h6>
<ul class="references">
<li>
Expand All @@ -142,4 +248,10 @@ It is recommended that you change your default project on <i>Gadi</i>, as this m
<li>
<a href = "https://opus.nci.org.au/display/Help/0.+Welcome+to+Gadi" target="_blank">https://opus.nci.org.au/display/Help/0.+Welcome+to+Gadi</a>
</li>
<li>
<a href = "https://docs.github.com/en/authentication/connecting-to-github-with-ssh/generating-a-new-ssh-key-and-adding-it-to-the-ssh-agent" target="_blank">https://docs.github.com/en/authentication/connecting-to-github-with-ssh/generating-a-new-ssh-key-and-adding-it-to-the-ssh-agent</a>
</li>
<li>
<a href = "https://linuxize.com/post/using-the-ssh-config-file/" target="_blank">https://linuxize.com/post/using-the-ssh-config-file</a>
</li>
</ul>
1 change: 1 addition & 0 deletions mkdocs.yml
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down

0 comments on commit 1822cfe

Please sign in to comment.