Skip to content

Latest commit

 

History

History
113 lines (79 loc) · 4.85 KB

install.md

File metadata and controls

113 lines (79 loc) · 4.85 KB
Raw

First of all, ensure you have installed the Pre-requisites / Preliminary software and followed the corresponding configuration.

Then this repository is hosted on Github. Assuming you have installed and configured git:

Cloning the ULHPC git repository

To clone this repository, proceed as follows (adapt accordingly):

$> mkdir -p ~/git/github.com/ULHPC
$> cd ~/git/github.com/ULHPC
$> git clone https://github.com/ULHPC/tutorials.git
$> cd tutorials
# /!\ IMPORTANT: run 'make setup' only **AFTER** Pre-requisites software are installed

To setup you local copy of this repository (after pre-requisites are satisfied), simply run:

$> make setup    # Under Mac OS / Linux

This will initiate the Git submodules of this repository (see .gitmodules) and setup the git flow layout for this repository. Later on, you can update your local branches by running:

 $> make up

If upon pulling the repository, you end in a state where another collaborator have upgraded the Git submodules for this repository, you'll end in a dirty state (as reported by modifications within the .submodules/ directory). In that case, just after the pull, you have to run make up to ensure consistency with regards the Git submodules.

Finally, you can upgrade the Git submodules to the latest version by running:

$> make upgrade

Python Virtualenv / Pyenv and Direnv

If you want to perform a local rendering of this documentation, a few Python packages are required to be installed (see requirements.txt). You will have to ensure you have installed direnv (configured by .envrc), pyenv and pyenv-virtualenv. This assumes also the presence of ~/.config/direnv/direnvrc from this page - for more details, see this blog post.

You can run the following command to setup your local machine in a compliant way:

make setup-direnv
make setup-pyenv

Adapt your favorite shell configuration as suggested. You may want to add the following:

for f in $XDG_CONFIG_HOME/*/init.sh; do
  . ${f}
done

Running direnv allow (this will have to be done only once), you should automatically enable the virtualenv ulhpc-docs based on the python version specified in .python-version. You'll eventually need to install the appropripriate Python version with pyenv:

pyenv versions   # Plural: show all versions
pyenv install $(head .python-version)
# Activate the virtualenv by reentering into the directory
cd ..
cd -

From that point, you should install the required packages using:

make setup-python

# OR (manually)
pip install --upgrade pip
pip install -r requirements.txt

You should now be able to preview the documentation locally (as rendered on readthedocs).

Documentation

See docs/.

The documentation for this project is handled by mkdocs. You might wish to generate locally the docs:

  • Install mkdocs and the mandatory package from the requirements.txt file (ideally within a virtual environment as above)
  • Preview your documentation from the project root by running mkdocs serve and visit with your favorite browser the URL http://localhost:8000
    • Alternatively, you can run make doc at the root of the repository.
  • (eventually) build the full documentation locally (in the site/ directory) by running mkdocs build.

Prepare for Tutorial sessions

To take the best out the tutorial sessions proposed during the HPC school, you probably wish on your homedir on the cluster to

  1. clone (or update) the ULHPC/tutorials as instructed above
  2. work in a separate directory structure when following a given event. Here is a suggested approach:
# First time: clone the repo under a meaningfull path
$> mkdir -p ~/git/github.com/ULHPC
$> cd ~/git/github.com/ULHPC
$> git clone https://github.com/ULHPC/tutorials.git
$> cd tutorials
$> make setup

# Next times: pull latest changes
$> cd ~/git/github.com/ULHPC/tutorials
$> make up     # update both branches (production and devel)

# Prepare a dedicated (separated) working directory
$> mkdir -p ~/tutorials/ULHPC-School-2021         # Adapt event name accordingly
$> cd ~/tutorials/ULHPC-School-2021
$> ln -s ~/git/github.com/ULHPC/tutorials  ref.d  # create a symbolic link pointing to the tutorial reference material
# Now  $HOME/tutorials/ULHPC-School-2021/ref.d/ points to reference training material