Skip to content

Latest commit

 

History

History
194 lines (122 loc) · 6.45 KB

USER.md

File metadata and controls

194 lines (122 loc) · 6.45 KB
Raw

User guide

Logging into server

You should have recieved a invitation to a eWatercycle collaborative organization, please follow instructions in email.

The username you should use to login can be found on on SRC dashboard profile page

  1. To login to the Explorer or Jupyter environment, you should setup TOTP on SRC dashboard profile page, this is your password on the server.
  2. Optionally to login into machine with ssh, your SSH public key on your laptop/workstation must be added to https://sbs.sram.surf.nl/profile

Save notebooks to GitHub

The Jupyter notebooks that you write should be saved outside the Jupyter server. Code like notebooks can be saved git repositories on GitHub.

1. Create GitHub account

To store notebooks in a repository on GitHub you need an account. Goto https://github.com/signup to create an account.

2. Create GitHub repository

  1. Goto https://github.com/new to create a repository.

  2. Fill the form

    • For .gitignore select the Python template, it will prevent you from commiting auto generated files
    • Make sure to pick a license like Apache-2.0 so others know what they can do with code in the repository

3. Setup GitHub authentication on server

To clone private repositories or push changes to public repositories you need to setup authentication against GitHub. You can do this by creating a SSH key pair on the server and register the public key on GitHub.

  1. On the server open a terminal.

  2. Create a SSH key pair with following command

    ssh-keygen -t ed25519 -C "[email protected]" -N "" -f ~/.ssh/id_ed25519

    Replace [email protected] with the email adress you used for your GitHub account.

  3. Copy the content of ~/.ssh/id_ed25519.pub to clipboard.

    In a Jupyter terminal run cat ~/.ssh/id_ed25519.pub, select the content, use SHIFT-right click to get context menu and then select copy)

  4. Register the public key on GitHub by going to https://github.com/settings/ssh/new

    1. For title use name of server where you generated SSH key pair.
    2. Paste contents of clipboard in key text area.
    3. Press green button to add the key

You are now ready to clone a repository.

For brevity and easyness only SSH key pair without passphrase is explained, see GitHub docs for alternatives and more secure methods.

4. Clone repository

On the GitHub repository page there is a green Code button, open it to get the SSH git URL of the repository. It should look something like [email protected]:<user name>/<repository>.git

  1. On the server open a terminal

  2. Run the following command to clone a repo

    git clone [email protected]:<user name>/<repository>.git

    Replace <user name> and <repository> with your username and repository name respectivly.

    • For the first time it will prompt if you want to connect to github.com, enter yes followed by enter.

You will now have a local copy of the repository.

5. Add & commit & push notebooks on server to GitHub

Following commands should be run in a terminal on the server inside the repository directory.

To add a file to git staging use

git add <filename>

To commit the file to git you first need tell git who you are with

git config --global user.email "[email protected]"
git config --global user.name "Your Name"

(Replace [email protected] with the email adress you used for your GitHub account and fill in your full name)

To commit use

git commit -m "some message"

Replace some message text that describes changes that where made since last commit.

Now your changes have been saved locally, to push them to GitHub use

git push

6. Pull changes from GitHub to server

If files on GitHub and you want to pull those changes to the server then in terimal use

git pull

The git commands can also be done using the Git tab in the Jupyter Lab environment.

Install own software

The default Jupyter kernel is read-only and has the eWaterCycle Python package and friends installed. To install additional Python or Conda packages you need to create your own conda environment with a Jupyter kernel.

  1. Install eWaterCycle Python package dependencies with user chosen Conda environment name.
  • Get the eWaterCycle environment.yml file:
wget https://raw.githubusercontent.com/eWaterCycle/ewatercycle/main/environment.yml
  • Create your own conda environment e.g. testewatercycle:
mamba env create --file environment.yml --name testewatercycle
  1. Install eWaterCycle Python package
  • Activate your own conda environment e.g. testewatercycle:
conda activate testewatercycle
  • Install eWaterCycle Python package:
pip install ewatercycle

or

pip install -e .[dev]

to be in development mode if you have the source code.

  1. Install Jupyter kernel
  • Install ipykernel:
mamba install -c conda-forge ipykernel
  • Get the path to python in our own conda environment:
which python

that returns /home/usr/.conda/envs/testewatercycle/bin/python

  • Add it to Jupyter:
/home/usr/.conda/envs/testewatercycle/bin/python -m ipykernel install --user --name 'testewatercycle'

that returns Installed kernelspec testewatercycle in /home/usr/.local/share/jupyter/kernels/testewatercycle

  1. Restart your own Jupyter server from tab File > Hub Control Panel

  2. Open a notebook and pick the new kernel that is testewatercycle

  3. Install additional software