diff --git a/README.md b/README.md index 9c999f1ff..ac0176a16 100644 --- a/README.md +++ b/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) diff --git a/knora/dsplib/utils/stack_handling.py b/knora/dsplib/utils/stack_handling.py index 9ea91e4b3..711e7b01f 100644 --- a/knora/dsplib/utils/stack_handling.py +++ b/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)