Docker client tutorial

The pepcli application is a command line interface (CLI) application to interact with the PEP system. With pepcli you can download and upload your data. Depending on you operating system, there may be an easy installer that you can use listed on the main installation page. Alternatively, you can use Docker. Docker is software that provides the ability to package and run an application in an isolated environment called a container. This tutorial explains how to use pepcli with Docker under, paying most attention to macOS & *nix.

Installing Docker

You can learn how to install Docker via https://www.docker.com/get-started/. For macOS, we also document the process here.

macOS

Download Docker Desktop application at Docker.com. Make sure to choose the software with the right CPU architecture.
Open the docker.dmg file. Drag the docker app into your Application folder. Now the installation of Docker Desktop starts.
After this, open the Docker Desktop application to finish the installation process. When the app opens for the first time, you have to set some configurations:
- Accept the service agreement
- Use recommended settings
- Choose continue without signing in
- You may skip the question about what kind of work you do

Now the Docker installation is complete. You can now close the installer application.

Using Docker

When running an application inside a docker container (which is how Docker works), communication between your container and your host machine (your computer outside the container) is by default disabled.

However you do need to have that line of communication, since you may need a token on your machine to be able to log in, and in order to use the data that you downloaded inside your container, you need to get it out of your docker container as well. So you can create so called bind mounts (using the --volume arguments in the next step), which means that a folder on your host machine is connected with a folder in the docker container.

Docker Images

Before proceeding, you'll need to know which Docker image to use. Throughout this tutorial, you'll see <IMAGE_URI> as a placeholder - this should be replaced with the actual URI of the Docker image specific to your project and environment. You can find the correct Docker image URIs on the main downloads page. Different projects and environments require different images, so make sure to use the one that corresponds to your specific use case.

Open a terminal window.
First create a folder on your machine where the oauth token which is needed to access PEP will be stored, e.g. oauth_token.
```
mkdir oauth_token
```

If you have already been given an oauth token, move the token file (e.g. OAuthToken.json) you received from the repository's Access Administrator to this folder and move on to step 4, else continue to step 3.

mv /Path/To/OAuthToken.json ./oauth_token/

The /Path/To/ should be replaced with the current path of your token, and OAuthToken.json with your token name.

If you have been granted access with interactive login (using SurfConext, Google, EduID, etc.), you might first want to request an oauth token, so you don't have to login every time when restarting a new container. You can request one by running the following command:
```
docker run -it --volume /Path/To/oauth_token/:/data/ <IMAGE_URI> /app/pepLogon --long-lived
```
- Where /Path/To/oauth_token/ is the path to the oauth_token folder you just created.
- and <IMAGE_URI> is the URI of the Docker image. Depending on the project and environment you will be working in, you will need a different Docker image URI, you can find these on the main downloads page.
- Follow the instructions in the terminal to log in. After you have successfully logged in, a file containing your oauth token (e.g. OAuthToken.json) will appear in /Path/To/oauth_token/.

Note

If you do not have interactive login access, please contact your repository's Access Administrator to set this up for you.

Create a new folder, e.g. data_output, in which you can later find the downloaded data.
```
mkdir data_output
```
Now you can start running the Docker container with the following command:
```
docker run -it --volume /Path/To/data_output/:/output/ --volume /Path/To/oauth_token/:/token/:ro <IMAGE_URI> bash
```
- Where Path/To/data_output/ is the path to the data_output folder you just created.
- Where Path/To/oauth_token/ is the path to the oauth_token folder where your token is located in.
- Where <IMAGE_URI> is the URI of the Docker image. Depending on the project and environment you will be working in, you will need a different Docker image URI, you can find these on the main downloads page.
Now you are in a shell inside a docker container. You can run the following command to download the data that you have access to:
```
cd /output
/app/pepcli --oauth-token /token/OAuthToken.json pull --all-accessible
```
- Where and OAuthToken.json should be replaced with your token name.

You can now find all your downloaded data in the data_output folder that you made.

Here you see an example in a terminal:

A screenshot from the terminal in which the docker and pepcli commands are inserted

See the PEP Command Line Interface documentation for more information on how to use pepcli.