====== Docker tutorial ======
<note important>Docker is available for Linux, Windows, and Mac. The image is tested on Ubuntu 18.04 and Windows 10. It should work on other systems as well, but we can not guarantee that.</note>
<note tip>If you prefer to have everything installed on your system, you do not need to use Docker and install everything manually (see [[courses:hro:tutorials:0dockertutorial#manual_installation|Manual installation]]). However, using Docker is strongly recommended.</note>
===== Docker installation =====
The official installation guide is available [[https://docs.docker.com/engine/install/|here]]. For Windows and Mac, binaries are available to be downloaded. For Linux, you need to choose your distribution and follow the guide for installation from repository (recommended), .deb package, or with a convenience script.

<note tip>In case of problems with performance on your PC, you can run the image on [[https://www.gitpod.io|Gitpod]]. See [[courses:hro:tutorials:0dockertutorial#gitpod|Gitpod]].</note>

 <note important>Do not forget to perform also the first [[https://docs.docker.com/engine/install/linux-postinstall/|post-installation steps for Linux]] to run Docker without sudo.</note>
<note tip>You can also install [[https://docs.nvidia.com/datacenter/cloud-native/container-toolkit/install-guide.html#docker|nvidia-docker]] on top of the normal installation for better GPU utilization (not needed in this course).</note>
===== Docker commands =====

<note>The commands will work on Linux terminal without any prerequisites, but on Windows and Mac you need to run the Docker Engine first and then use a command-line interface (cmd, PowerShell) for the given system.</note>

==== Run the image ====

  * Download the image. The ''tag'' can be one of ''full, icub, graspit, hri''. Tag ''full'' contains iCub, grasping and HRI related things. Tag ''icub'' contains only iCub related software, tag ''graspit'' contains only grasping related things and tag ''hri'' contains HRI related software.
<code>   docker pull b3m33hro/labs:tag</code>  
  * Name your image for an easier usage. ''<image_name>'' is an arbitrary name for your image, //e.g.//, ''hro_image''  
<code>   docker tag b3m33hro/labs:tag <image_name></code>  
<note important>Names must start with lowercase letter</note>
  * Run the image. ''-it'' is for interactive mode. ''-p'' determines which ports will be accessible from the host system. ''<container_name>'' is an arbitrary name of your container, //e.g.//, ''hro''. ''-v'' specifies which folder will be shared between the container and the host system (optional). ''<image_name>'' is the name selected in the previous step.  
      * The shared folder is used for easier transfer of files created in the Docker container. You can also share code that way, so you can edit it from both the host machine and from inside the container. 
<code>   docker run -it -p 6080:6080 -p 8888:8888 --name <container_name> -v path_to_data_folder_host_system:/root/data <image_name></code>  
  * From inside the container run command to start the VNC server. The server is needed for OpenGL software.
<code>   start-vnc-session.sh</code>  
  * On your host machine open any internet browser and type ''http://localhost:6080'' to the address bar. A window with a Linux environment should open.  
      * The VNC server may crash sometimes. To fix it, just run ''start-vnc-session.sh'' again.
      * Unfortunately, you can not copy-paste from the host machine to the VNC.
          * Solution is to copy things from the internet browser directly in the VNC. Another possibility is to use the VNC only as a "screen" and use a terminal on the host machine to control it.
<note tip>You can connect to the VNC server from another machine or even from a mobile phone by using the IP address of the host machine instead of localhost.</note>
=== HRI ===

    * Choregraphe can be run from terminal with the command ''choregraphe''
      * you can select 90-days test, or enter this key ''654e-4564-153c-6518-2f44-7562-206e-4c60-5f47-5f45'' 
<note warning>To have Pepper in Choregraphe, you will need to either: A) run ''sed -i 's|su -c ./naoqi-bin chore &||g' /usr/bin/choregraphe && sed -i 's|./choregraphe-bin -p 9559 //-////-//ip 127.0.0.1 //-////-//no-naoqi //-////-//no-discovery|su -c ./choregraphe-bin chore|g' /usr/bin/choregraphe'' and run ''choregraphe'', or B) ''cd /opt/Aldebaran/bin'' and ''su -c ./choregraphe-bin chore'', or C) download the newest Docker image with tag ''full'' or ''hri''.  Robot can be then changed in ''Edit->Preferences->Virtual robot''---chose Pepper V16 robot. Next time you can run only ''choregraphe'' and Pepper will be there.</note>
    * RoboDK must be installed first (because of licensing). One can do it from terminal with command ''/root/Install-RoboDK''. The program can be then run with command ''/installation_path/RoboDK-Start.sh'' (where ''installation_path'' is ''/RoboDK'' in default), or with Desktop icon.
      * You will have 30days licence (which should be enough) 

==== Other commands ====
  * Stop the container (any of the three methods will work)  
<code>   docker stop <container_name></code>  
<code>   CTRL+D</code>  
<code>   exit</code>
  * Restart the container  
<code>   docker start <container_name>  
   docker attach <container_name></code>   
  * Open another terminal in the same container  
<code>   docker exec -it <container_name> /bin/bash</code>  
  * Remove a stopped container from your system  
<code>   docker container rm <container_name></code>  
  * Clean up all docker resources  
<code>   docker system prune -a</code>  

===== Functionality check =====
  * Check GraspIt!. Open the terminal and run ''graspit_simulator''
  * Check Jupyter. Open terminal, run ''jupyter-notebook''. Open a browser (in container or in the host machine) and enter ''http://localhost:8888'' and you should see Jupyter notebook interface.
    * **Do not run the notebook from Applications-Development menu**
<note>If you have problems with jupyter-notebook on Windows, please run ''fix_windows.sh''.</note>
  * Check Robotology build. Open the terminal and run the following lines. Gazebo interface with iCub robot should appear.
<code>   git clone https://gitlab.fel.cvut.cz/body-schema/teaching/b3m33hro-labs.git
   cd b3m33hro-labs/lab3/tutorial_cartesian-interface/smoke-test
   ./test.sh</code>

===== Gitpod =====
In case of problems with Docker on your computer, you can use Docker on [[https://www.gitpod.io|Gitpod]]. Gitpod allows running Docker images on their servers for free (each registered user can use 50 hours per month).
  * Open [[https://gitpod.io/#github.com/rustlluk/B3M33HRO-gitpod|Gitpod]]
    * you will need github.com account
    * Image should be automatically downloaded and run in your new Gitpod workspace
    * This will open the tag ''full'', check other branches of [[https://github.com/rustlluk/B3M33HRO-gitpod|https://github.com/rustlluk/B3M33HRO-
    * gitpod]] to open other tags
<note important>Only files in ''/workspace'' will be saved after you stop and start the workspace again!</note>
<note important>If you want to continue in your current workspace after you close it, open it from [[https://gitpod.io/workspaces|Dashboard]]. Opening the previous link again will result in creation of a new workspace.</note>
  * No ''docker run'' and others are needed 
  * Try  [[courses:hro:tutorials:0dockertutorial#functionality_check|Functionality check]] again
  * With every new terminal you should be automatically switched to user ''root''. If not, please run ''su'' with password ''root''.
    * **In older version of the image, you need to run** ''su'' as the first command in each new terminal you open and use the environment as before
      * password is ''root'' 

Everything should work almost the same as in the local installation, but server resources are used. However, you can not link folder from your PC as in the case of local Docker. You can either use data only in docker, or there are several ways how to share code:
  * Always upload and download data from the main page of Gitpod workspace
    * the workspace is in location ''/workspace'' and linked to ''/root/workspace'' 
  * Use Git. You can:
    * Run Gitpod from your repository by:
      * make a fork of [[https://github.com/rustlluk/B3M33HRO-gitpod|https://github.com/rustlluk/B3M33HRO-gitpod]], or
      * create a new repository and add [[https://github.com/rustlluk/B3M33HRO-gitpod/blob/main/.gitpod.yml|.gitpod.yml]] to it.
    * Use other repository to share code, //e.g.,// fork of our [[https://gitlab.fel.cvut.cz/body-schema/teaching/b3m33hro-labs|lab repository]]. 
  * Mount some folder on public server (//e.g.//, your folder at taylor.felk.cvut.cz) to the Docker environment and your host PC (with sshfs or other). This option may work almost the same as ''-v'' option in local Docker installation.
You can copy/paste things to the Gitpod workspace terminals, but you need to approve it (popup window with the question should appear after you first try to paste something).
<note tip>After your workspace gets initialized click on it or it will "load" infinitely. </note>

===== FAQ =====
  * On Windows, the Docker sometimes allocates too much memory, which may cause Gazebo to fail. Restart the Docker (from status bar) or restart the computer.
  * If you want to install anything inside the Docker, ''apt update'' will most probably be needed to be run first. Else you will get ''no package ...'' error.
  * If you are using Mint, do not use ''$(lsb_release -cs)'' when adding the repository, but use name of Ubuntu version corresponding to your Ubuntu kernel from [[https://wiki.ubuntu.com/Releases|Ubuntu versions]].
  * You can also run the smoke-test without GUI, which may be faster on slower computers. Just open ''some_path/smoke-test/fixtures/fixture.xml'' in the given project you want to test and remove/comment the whole ''<module>'' section containing ''gzclient''. 
  * Try to run Gazebo at least twice, it may fail sometimes.
  * If your Gazebo fails in the middle of operation try to free as many resources on your computer as possible (RAM, CPU) by, for example, closing other internet browser tabs. Restart Docker, or try to kill other running processes of yarp or Gazebo.
    * check whether anything is running in ''top'' or ''htop'' and kill it (look for anything with yarp, gz, iCartesian* etc.). However, using ''pkill -f gz'', ''pkill -f yarp'' and ''pkill -f tutorial'' should be enough in most cases to kill all Gazebo and Yarp related things.



===== Manual installation =====
You need to install [[https://github.com/robotology/robotology-superbuild|Robotology superbuild]], [[https://github.com/graspit-simulator/graspit|GraspIt!]], [[https://github.com/atenpas/gpdPython|gpd]], Python 2.7 and 3.X. Optionally, [[http://wiki.ros.org/melodic/Installation/Ubuntu|ROS]] is needed. You can check [[https://gitlab.fel.cvut.cz/body-schema/teaching/b3m33hro-labs/-/blob/main/lab1/Dockerfile|Dockerfile]] to get an idea of how everything is installed.