.. _docs_docker: ******************** Docker Documentation ******************** .. include:: rst_directives.rst .. contents:: :local: Meta #### The file ``cleanup.sh`` ========================== The file ``🏃 cleanup.sh`` in the root directory cleans up all docker resources, the masymos scripts created on your system (like images, containers, volumes,…). Cloned repositories in ``📂 jar-builder/masymos-source`` or built jars in ``📂 jar-builder/masymos-builds`` are not affected. Using the bash-files on Windows =============================== - please run the bash files with `git-bash `__ or `Cygwin `__. If you face any problems, please contact us via GitHub and provide the whole output of the script. - provide paths in parameters in one of the following formats: - ``C:/my/path`` - ``"C:\my\path"`` - ``/c/my/path`` Jar-Builder ########### Everything in the folder ``📂 jar-builder`` is only for creating the jar files inside a docker container. Usage ===== Call the ``🏃 jar-builder/maven-build-masymos-jars.sh`` to create the jar files and library folder automatically. Use the parameter ``rebuild`` to force a rebuild of the image. If you want a different version then the ``master`` of the repositories, please check them out manually in the folder ``📂 jar-builder/masymos-source``. On the first run of the docker container, maven will download all dependencies and saves them to a docker volume. So it may take some time. Find the generated jar-files in ``📂 jar-builder/masymos-builds``: - 📃 masymos-cli-1.0.2.jar - the MaSyMoS Cli as fat jar with all dependencies - 📃 masymos-morre-1.0.2.jar - the MaSyMoS Morre thin jar - 📃 original-masymos-cli-1.0.2.jar - the MaSyMoS Cli as thin jar without all dependencies The docker volume for the maven dependencies is not removed automatically, use ``🏃 cleanup.sh`` for that. Folder and Storage Overview =========================== - 📂 jar-builder - 📂 d_jar-builder - contains the Dockerfile and the files, that are copied into the docker image during build process - 📂 masymos-builds - this is the docker-output-directory - find the jar files here - 📂 masymos-source - this is the docker-input-directory - it must contain the source repository of the masymos source code - ℹ it's not possible to use symlinks here - 🔧 user_group_numbers.sh - this file contains the UID and GID, that the files in ``📂 jar-builder/masymos-builds`` and ``📂 jar-builder/masymos-source`` will have after the run - if you have problems with editing/deleting the files, you may have to change the settings here - get your UID with :c_bash:`id -u` - get your GID with :c_bash:`id -g` - 🏃 maven-build-masymos-jars.sh - ℹ call with parameter ``rebuild`` to force the creation of a new docker image - this file automatically checks all dependencies to run the docker container #. remove old jar-builds #. clone masymos repositories (master), if they are missing #. create maven artifacts volume ``masymos_maven_artifacts``, if missing #. build docker image ``masymos-jar-builder``, if missing or if parameter ``rebuild`` is set #. on Windows-Systems (git-bash or cygwin) the script needs to edit the volume paths for docker - for debugging reasons these paths are written to the output (see ``OSTYPE``) #. run docker container ``masymos-jar-builder`` and remove it afterwards #. output non-success docker return codes Docker Dependencies =================== - the folder mounted to the output volume should not contain any old builds - the folder mounted to the input volume must contain the masymos repositories - a maven artifacts volume (no need to map it to another HOST-directory) Server Integration ################## - Everything in the folder ``📂 server-integration`` is for running masymos-morre as neo4j plugin in a docker container. - open Ports: `7474 and 7687 for HTTP and Bolt `__ - the default database used is named ``morre`` (run-parameter ``--env "NEO4J_dbms_active__database=morre"`` ) .. WARNING:: by default the server is not secured at all - Authentication is disabled (run-parameter ``--env "NEO4J_AUTH=none"``) - make sure to set your firewall rules to keep the server in you zone only .. image:: ../uml/structure_docker_morre.svg Usage ===== Call the ``🏃 server-integration/run-neo4j-server.sh`` after running the *jar-builder* to setup and start the neo4j server with the masymos morre plugin. Use the parameter ``rebuild`` to force a rebuild of the image. An empty docker volume ``masymos_neo4j_database`` is created as new neo4j database. If you want to use an existing database, please see :ref:`docker_using_own_volume`. The docker volume for the neo4j database is not removed automatically, use ``🏃 cleanup.sh`` for that. If you like to see the neo4j logs directly after starting the container, use this command: :c_bash:`./run-neo4j-server.sh && docker logs -f masymos_neo4j` The neo4j logs are written to the directory ``/logs`` in the container. .. _docker_using_own_volume: Using you own volume -------------------- If you have an existing neo4j database, there are two selutions using it with this docker instance: #. copy the database into a docker volume without mounting it to the user space - the volume is managed by docker - ⚠ calling the ``🏃 cleanup.sh`` may removes the volume and all stored data - this is the preferred method, as your local data will not be changed #. mount the local directory in the user space as docker volume - the database files will be changed by processing them with the server .. _docker_copy_database_into_docker_volume: Copy your database into the docker volume ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ #. find the file ``🏃 server-integration/copy_own_data_into_docker_volume.sh`` and the location of your local database - please note, that you need to use the database folder named after your database, not the neo4j-databases-root - your database is a named folder inside a folder called ``databases`` - example: ``/home/ulf/database-engine/neo4j/data/databases/my_db`` #. run the script with :c_bash:`$ ./copy_own_data_into_docker_volume.sh /path/to/neo4j/databases/my_database` - you may check the UID/GID (should be YOUR ids) - you may check the size of the created volume Mount a local volume in user space ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ You may edit the ``🏃 server-integration/run-neo4j-server.sh`` runner. #. find the docker run command #. you need to point to the root of your neo4j-database folder - inside this folder, there must be a directory ``databases`` - inside the ``databases`` directory, there must be your *database folder* #. change the volume mount parameter to the localisation of your database, i.e. - ``--volume "/opt/neo4j:/data" \`` - ``--volume "$HOME/neo4j:/data" \`` - ``--volume "$PWD/../../neo4j:/data" \`` #. you also need to change the database name to your *database folder name* in this line - ``--env "NEO4J_dbms_active__database=morre" \`` Folder and Storage Overview =========================== - 📂 server-integration - 📂 d_server - contains the Dockerfile and the files, that are copied into the docker image during build process - 📂 masymos-builds - this folder contains the copied jar-files from the *jar-builder* - 🏃 copy_own_data_into_docker_volume.sh - script for copying a local database into a docker volume, please see ":ref:`docker_copy_database_into_docker_volume`" - 🏃 run-neo4j-server.sh - ℹ call with parameter ``rebuild`` to force the creation of a new docker image - this file automatically checks all dependencies to run the docker container #. abort, if container is still running #. create docker database volume ``masymos_neo4j_database``, if missing #. build docker image ``masymos_neo4j``, if missing or if parameter ``rebuild`` is set - remove old jar copies - copy libraries from *jar-builder* to ``📂 server-integration/d_server/masymos-builds`` - build image #. run docker container ``masymos_neo4j`` in detached mode and remove it afterwards #. output non-success docker return codes