Skip to content

Configure your ssh

To configure an ssh connection with the important parameters set, copy the following commands to the file named ~/.ssh/config on your local computer. Details about the following commands can be found here (credits: Anne Archibald).

Text Only
Host tubular
User <USERNAME>
HostName tubular.chimenet.ca
ServerAliveInterval 10
ServerAliveCountMax 30
ControlMaster auto
ControlPath ~/.ssh/control-%r@%h:%p
ControlPersist 1h
DynamicForward 4440

Host frb-analysis
HostName frb-analysis
User <USERNAME>
ProxyCommand ssh tubular -a -x -e none -W %h:%p
ForwardX11 yes
ForwardAgent yes
ServerAliveInterval 10
ServerAliveCountMax 30
ControlMaster auto
ControlPath ~/.ssh/control-%r@%h:%p
ControlPersist 1h
LocalForward <PORT> 127.0.0.1:<PORT>
LocalForward <PORT+1> 127.0.0.1:<PORT+1>

Where \<PORT> is a 4-digit code that you can decide, as long as it is unique. (i.e. 0000 is not unique)

Now, you can access frb-analysis by running ssh frb-analysis. This will forward your X11 and ports.

Running a container

Text Only
docker run -d -it -v /home:/home -v /data:/data --name baseband_<YOURNAME> [-p <PORT>:<PORT>] chimefrb/baseband-analysis:latest bash

The label latest will run the most updated software version, which is the one running on-site. Old versions of the code can be run with chimefrb/baseband-localization:latest and chimefrb/baseband-analysis:stable.

[ ] are optional, don't include this unless you want to run a jupyter notebook inside the container (see below). PORT is a single 4-digit number, to configure it follow Configure your ssh below

Note that you need to be in the docker group in order to use docker commands on frb-analysis. It is possible to verify the groups you are subscribed to by running groups, docker should be on the list. If not, you need to contact one of the system admins. If you have been added very recently, docker may not show right away when you run groups. Logging out and back in resolves this.

Executing the container

Text Only
docker exec -it baseband_<YOURNAME> bash

To detach to the docker use the CTRL-p CTRL-q key sequence. To reattach in case you've detached or have been disconnected:

Text Only
docker attach baseband_<YOURNAME>

Removing a container

Once you don't need a container anymore, delete it by running

Text Only
docker stop baseband_<YOURNAME>
docker rm baseband_<YOURNAME>

Running your code version

The version of baseband-analysis used in a container by default is located in /opt/pysetup. If you want to develop new code, it is wise not to change the default module installed. Instead, you can use your own version of baseband-analysis instead. This can be done by running

Text Only
export PYTHONPATH="/home/PATH/TO/baseband-analysis"
cd /home/PATH/TO/baseband-analysis

Important, do not run any git command inside the container, your file permissions will be messed up seriously. Also, it is wise not editing the code inside a container. Instead, edit the code and use git commands in another terminal, outside any container. Containers will read your code if that is in your /home area.

In summary, you probably want to have two terminals one, one inside the container to run the code and one outside the container to edit the code.

To install your own version of baseband-analysis, follow these steps

A) Outside the container:

  1. cd /home/PATH/TO
  2. git clone https://github.com/CHIMEFRB/baseband-analysis.git, to clone the repository inside the current directory
  3. cd baseband-analysis
  4. If you already have your own branch, git checkout <YOUR_BRANCH>. Otherwise, git checkout pipeline-update and then git checkout -b <new_branch_name> to create a new branch for your work.

B) Inside the container:

  1. apt-get update && apt-get install build-essential
  2. poetry install, to install the module

Setting up authentication credentials

You need to set up tokens to communicate with the processing cluster. Detailed instructions are available here. In summary, you need to obtain two tokens with

Text Only
curl -X POST -H "Content-Type: application/json" -d '{"username": "<USERNAME>", "password": "<PASSWORD>"}' https://frb.chimenet.ca/frb-master/auth

The tokens can be written to a bash file, for example ~/start_env.sh, as

Text Only
export FRB_MASTER_ACCESS_TOKEN=<ACCESS_TOKEN>
export FRB_MASTER_REFRESH_TOKEN=<REFRESH_TOKEN>

In this case, every time you execute a container you need to run source ~/start_env.sh. The same command can be written in your ~/.bashrc file outside the container to load your credential on frb-analysis.

Storing credentials in the bashrc file is the preferred option. However, if you need to obtain new credentials quickly, this is a snippet that will store them in the current terminal and print them on screen

Text Only
echo Username:; read -s username; echo Password:; read -s password; str=`curl -X POST -H "Content-Type: application/json" -d '{"username": "'$username'", "password": "'$password'"}' https://frb.chimenet.ca/frb-master/auth`; cut1=${str#*:\"}; export FRB_MASTER_ACCESS_TOKEN=${cut1%\",*}; cut2=${str##*:\"}; export FRB_MASTER_REFRESH_TOKEN=${cut2%\"*}; echo $str

Using jupyter notebook

First, you need to set-up your ssh configuration file on your local computer. Choose a single random 4-digit port for LocalForward and note that down; it will be the value of in the following and above. Note that must be unique, you can check ports in use by other containers by running docker ps -a in frb-analysis.

Check out whether jupyter is installed in the container with jupyter --version. If you get bash: jupyter: command not found, then you can install it with

Text Only
pip install jupyter

cd to the folder containing your notebook files. To start a notebook, run

Text Only
jupyter notebook --ip=0.0.0.0 --port <PORT> --no-browser --allow-root

Open your web browser and past the last of the links that will be output (http://127.0.0.1:<PORT>/?token=<TOKEN>).

You can make a notebook server persistent by running it in the background by adding the symbol & at the end of the last command. To kill a notebook server running in the background, run top (if not found, run apt-get update && apt-get install -y procps), exit with q, copy the PID of the command you wish to kill and run kill <PID>. To know the list of jupyter servers currently running in a container and their tokens, use jupyter notebook list.