fix(start-stack): copy docker folder to user's home directory (DEV-1581) (#274)

Author: jnussbaum

README.md

@@ -26,6 +26,33 @@ make install
 ```
 
 
+
+## User data in the folder `.dsp-tools`
+
+DSP-TOOLS saves user data in the user's home directory, in the folder `.dsp-tools`. Here is an overview of its 
+structure:
+
+| folder     | command using it | description                                  |
+|:-----------|:-----------------|:---------------------------------------------|
+| xmluploads | `xmlupload`      | saves id2iri mappings and error reports      |
+| docker     | `stack-up`       | files necessary to startup Docker containers |
+
+
+
+## The `start-stack` command
+
+This command starts Docker containers of DSP-API and DSP-APP, in the version that is running on [https://admin.dasch.
+swiss](https://admin.dasch.swiss/help). In addition to the containers, a number of files from the DSP-API GitHub 
+repository is necessary. The version of the docker images and these files must be the same. The version is hardcoded at the 
+following places in the code:
+
+- `knora/dsplib/docker/docker-compose.yml`: The 4 variables `services/{app,db,sipi,api}/image` must point to the 
+  DockerHub image of the last deployed version
+- `knora/dsplib/utils/stack_handling.py`: The variable `commit_of_used_api_version` must be the commit hash of DSP-API 
+  of the version that is running on [https://admin.dasch.swiss](https://admin.dasch.swiss/help).
+
+
+
 ## Git submodules
 
 This repository embeds [https://github.com/dasch-swiss/0123-import-scripts](https://github.com/dasch-swiss/0123-import-scripts) 

knora/dsplib/utils/stack_handling.py

@@ -1,4 +1,6 @@
+import importlib.resources
 import re
+import shutil
 import subprocess
 import time
 from pathlib import Path
@@ -8,8 +10,8 @@
 
 from knora.dsplib.models.helpers import BaseError
 
-# relative path to "knora/dsplib/docker", to make it accessible when dsp-tools is called from another working directory
-docker_path = Path(__file__).parent / Path("../docker")
+docker_path_of_user = Path.home() / Path(".dsp-tools/docker")
+docker_path_of_user.mkdir(parents=True, exist_ok=True)
 
 
 def start_stack(
@@ -33,6 +35,14 @@ def start_stack(
     if enforce_docker_system_prune and suppress_docker_system_prune:
         raise BaseError('The arguments "--prune" and "--no-prune" are mutually exclusive')
 
+    # copy contents of knora/dsplib/docker to ~/.dsp-tools/docker
+    # rationale to use importlib.resources: https://setuptools.pypa.io/en/latest/userguide/datafiles.html#accessing-data-files-at-runtime
+    docker_path_of_distribution = importlib.resources.files("knora").joinpath("dsplib").joinpath("docker")
+    for file in docker_path_of_distribution.iterdir():
+        dst = docker_path_of_user / file.name
+        if not dst.is_file():
+            shutil.copy(file, dst)
+
     # get sipi.docker-config.lua
     commit_of_used_api_version = "3f44354df"
     url_prefix = f"https://github.com/dasch-swiss/dsp-api/raw/{commit_of_used_api_version}/"
@@ -42,11 +52,11 @@ def start_stack(
         if not re.search(max_post_size_regex, docker_config_lua_text):
             raise BaseError("Unable to set max_file_size. Please try again without this flag.")
         docker_config_lua_text = re.sub(max_post_size_regex, f"max_post_size = '{max_file_size}M'", docker_config_lua_text)
-    with open(docker_path / "sipi.docker-config.lua", "w") as f:
+    with open(docker_path_of_user / "sipi.docker-config.lua", "w") as f:
         f.write(docker_config_lua_text)
 
     # start up the fuseki database
-    completed_process = subprocess.run("docker compose up db -d", shell=True, cwd=docker_path)
+    completed_process = subprocess.run("docker compose up db -d", shell=True, cwd=docker_path_of_user)
     if not completed_process or completed_process.returncode != 0:
         raise BaseError("Cannot start the API: Error while executing 'docker compose up db -d'")
 
@@ -94,7 +104,7 @@ def start_stack(
             raise BaseError(f"Cannot start DSP-API: Error when creating graph '{graph}'")
 
     # startup all other components
-    subprocess.run("docker compose up -d", shell=True, cwd=docker_path)
+    subprocess.run("docker compose up -d", shell=True, cwd=docker_path_of_user)
     print("DSP-API is now running on http://0.0.0.0:3333/ and DSP-APP on http://0.0.0.0:4200/")
 
     # docker system prune
@@ -108,11 +118,11 @@ def start_stack(
             prune_docker = input("Allow dsp-tools to execute 'docker system prune'? This is necessary to keep your "
                                  "Docker clean. If you are unsure what that means, just type y and press Enter. [y/n]")
     if prune_docker == "y":
-        subprocess.run("docker system prune -f", shell=True, cwd=docker_path)
+        subprocess.run("docker system prune -f", shell=True, cwd=docker_path_of_user)
 
 
 def stop_stack() -> None:
     """
     Shut down the Docker containers of your local DSP stack and delete all data that is in it.
     """
-    subprocess.run("docker compose down --volumes", shell=True, cwd=docker_path)
+    subprocess.run("docker compose down --volumes", shell=True, cwd=docker_path_of_user)