clients: document testing Oneclient with docker containers

approved
(Baptiste Grenier) #1
clients: document testing Oneclient with docker containers
diff --git a/source/clients.rst b/source/clients.rst
index 7a08727..5598e88 100644
--- a/source/clients.rst
+++ b/source/clients.rst
@@ -3,6 +3,12 @@
 Clients
 -------
 
+The `Oneclient` code and basic documnentation is available on GitHub:
+https://github.com/onedata/oneclient
+
+The officiel documentation is:
+https://onedata.org/#/home/documentation/doc/using_onedata/oneclient.html
+
 Using the web interface
 ^^^^^^^^^^^^^^^^^^^^^^^
 
@@ -53,6 +59,78 @@ Tokens have to be generated from the `DataHub` (Onezone) interface.
 
    The access tokens can be created and managed using the EGI DataHub web interface.
 
+Installing and testing Oneclient in a docker container
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+A quick and simple solution for testing is to install the client on demand in a
+container for a support Operating System flavor (mainly various CentOS and Ubuntu
+releases).
+
+The following variables have to be exported in the container:
+
+* `ONECLIENT_ACCESS_TOKEN`: access token allowing to access **all** the spaces.
+* `ONECLIENT_PROVIDER_HOST`: name or IP of the Oneprovider the client should connect to.
+
+.. code-block:: console
+
+   docker run -it --privileged centos:7 /bin/bash
+   root@81dbd7e84438 /]# curl -sS  http://get.onedata.org/oneclient.sh | bash
+   # (...)
+   Complete!
+   Installation has been completed successfully.
+   Run 'oneclient --help' for usage info.
+   root@81dbd7e84438 /]# export ONECLIENT_ACCESS_TOKEN=<ACCESS_TOKEN_FROM_ONEZONE>
+   root@81dbd7e84438 /]# export ONECLIENT_PROVIDER_HOST=plg-cyfronet-01.datahub.egi.eu
+   root@81dbd7e84438 /]# mkdir /tmp/space
+   root@81dbd7e84438 /]# oneclient /tmp/space
+   root@81dbd7e84438 /]# ls /tmp/space
+
+Here the data is mounted in `/tmp/space`, creating a file into it will push it
+to the oneprovider and it will be accessible up in the web interface and from
+other providers supporting the space.
+
+For a real production usage it's preferable to use the Oneclient container as a
+source for a volume mounted into another container.
+
+Testing Oneclient in a Oneclient docker container
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+Docker containers for the oneclient are available, the existing versions can be
+seen in docker hub: https://hub.docker.com/r/onedata/oneclient/tags
+
+It's possible to use the most recent version by specifying the `latest` tag,
+and it's also quite common to use a version identical to the other components
+versions that can be seen on the Onezone and Oneprovider pages.
+
+The following variables have to be exported to be used in the container:
+
+* `ONECLIENT_ACCESS_TOKEN`: access token allowing to access **all** the spaces.
+* `ONECLIENT_PROVIDER_HOST`: name or IP of the Oneprovider the client should connect to.
+
+.. code-block:: console
+
+   export ONECLIENT_ACCESS_TOKEN=<ACCESS_TOKEN_FROM_ONEZONE>
+   export ONECLIENT_PROVIDER_HOST=plg-cyfronet-01.datahub.egi.eu
+   docker run -it --privileged -e ONECLIENT_ACCESS_TOKEN=$ONECLIENT_ACCESS_TOKEN -e ONECLIENT_PROVIDER_HOST=$ONECLIENT_PROVIDER_HOST onedata/oneclient:18.02.0-rc13
+   Connecting to provider 'plg-cyfronet-01.datahub.egi.eu:443' using session ID: '4138963898952098752'...
+   Getting configuration...
+   Oneclient has been successfully mounted in '/mnt/oneclient'
+
+
+Now the client will run in the background and the data will now be available
+through `samba/CIFS` or `nfs` protocols:
+
+.. code-block:: console
+
+  # Identifying the IP of the container
+   docker inspect --format "{{ .NetworkSettings.IPAddress }}" $(docker ps -ql)
+   172.17.0.2
+
+So the data can be accessed at
+
+* `smb://172.17.0.2/onedata`
+* `nfs://172.17.0.2/onedata`
+
 Testing Oneclient in a Virtual Machine
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
@@ -64,7 +142,7 @@ The following variables have to be exported:
 .. code-block:: console
 
    curl -sS http://get.onedata.org/oneclient.sh | bash
-   export ONECLIENT_ACCESS_TOKEN=<ACCESS_TOKEN_FROM>
+   export ONECLIENT_ACCESS_TOKEN=<ACCESS_TOKEN_FROM_ONEZONE>
    export ONECLIENT_PROVIDER_HOST=plg-cyfronet-01.datahub.egi.eu
    mkdir /tmp/space
    oneclient /tmp/space
@@ -85,7 +163,7 @@ The following variables have to be exported:
    vagrant up
    vagrant ssh
    curl -sS http://get.onedata.org/oneclient.sh | bash
-   export ONECLIENT_ACCESS_TOKEN=<ACCESS_TOKEN_FROM>
+   export ONECLIENT_ACCESS_TOKEN=<ACCESS_TOKEN_FROM_ONEZONE>
    export ONECLIENT_PROVIDER_HOST=plg-cyfronet-01.datahub.egi.eu
    mkdir /tmp/space
    oneclient /tmp/space

GitHub sha: ecf79da4

(Bruce Becker) #2

Minor typo:

should be “official”

I would also make the links expicit (unless this is automatically generated by Sphinx)

I would also rephrase:

to:

It’s possible to use the most recent version by specifying the latest tag. We also recommend to keep other components (Onezone and Oneprovider) on the same version as the Oneclient.

(Baptiste Grenier) #4

So the links seems OK: https://egi-datahub.readthedocs.io/en/latest/clients.html

In fact it’s more the client that should be on the same version of the server components than the opposite, but I will rephrase.

Thanks Bruce!

(Bruce Becker) #5

No problem :hugs:

I believe it’s easier to read though (and, this is documentation after all), if the links are “protected” - i.e instead of :

The Oneclient code and basic documnentation is available on GitHub: https://github.com/onedata/oneclient

the document could read:

The Oneclient code and basic documnentation is available on GitHub

It’s a matter of style, but I believe the docs should be biased towards readability

(Bruce Becker) split this topic #6

2 posts were split to a new topic: Adopting a style guide for Technical Documentation

(Bruce Becker) Approved #7