From e5d2ceafdce6672516bb562df49db0687fa5b10a Mon Sep 17 00:00:00 2001 From: Reimar Bauer Date: Sat, 8 Feb 2025 12:19:42 +0100 Subject: [PATCH 1/5] update installation to pixi --- README.md | 96 ++++++++++++----------- docs/components.rst | 2 + docs/conf.py | 14 ---- docs/development.rst | 52 +++--------- docs/installation.rst | 178 +++++++++++++++--------------------------- 5 files changed, 127 insertions(+), 215 deletions(-) diff --git a/README.md b/README.md index 9c0f110a4..cb8f0817b 100644 --- a/README.md +++ b/README.md @@ -12,65 +12,71 @@ into the right direction in order to get the software working on your computer. -Installing MSS -============== +## Installing MSS -Automatically -------------- +We distinguish between Developer and User installations. -- For **Windows**, go [here](https://github.com/Open-MSS/mss-install/blob/main/Windows.bat?raw=1) - - Right click on the webpage and select "Save as..." to download the file - - Double click the downloaded file and follow further instructions - - For fully automatic installation, open cmd and execute it with `/Path/To/Windows.bat -a` -- For **Linux/Mac**, go [here](https://github.com/Open-MSS/mss-install/blob/main/LinuxMac.sh?raw=1) - - Right click on the webpage and select "Save as..." to download the file - - Make it executable via `chmod +x LinuxMac.sh` - - Execute it and follow further instructions `./LinuxMac.sh` - - For fully automatic installation, run it with the -a parameter `./LinuxMac.sh -a` +### Developer Installation +Please read our [contributing](https://open-mss.github.io/contributing/) pages. +and [development](https://mss.readthedocs.io/en/stable/development.html) guidelines -Manually --------- +### User Installation -As **Beginner** start with an installation of Miniforge -Get [miniforge](https://github.com/conda-forge/miniforge#download) for your Operation System +Get **pixi** from https://pixi.sh/latest/ for your operation system. +You can now decide if you want to install **mss** as a project or global. -You must install mss into a new environment to ensure the most recent -versions for dependencies (On the Anaconda Prompt on Windows, you have -to leave out the 'source' here and below). +#### Project installation +Initialize a new project and navigate to the project directory. -``` - $ mamba create -n mssenv - $ mamba activate mssenv - (mssenv) $ mamba install mss python -``` -For updating an existing MSS installation to the current version, it is -best to install it into a new environment. If an existing environment -shall be updated, it is important to update all packages in this -environment. + pixi init MSS + cd MSS -``` - $ mamba activate mssenv - (mssenv) $ msui --update -``` +Use the shell command to activate the environment and start a new shell in there. + + pixi shell -It is possible to list all versions of `mss` available on your platform with: +Add the **mss** dependencies from conda-forge. -``` - $ mamba search mss --channel conda-forge -``` + (MSS) pixi add mss -For a simple test you can setup a demodata wms server and start a msolab server with default settings +##### Usage +Always when you want to start **mss** programs you have after its installation +to activate the environment by pixi shell in the project dir. +On the very first start of **msui** it takes a bit longer because it setups fonts. -``` - (mssenv) $ mswms_demodata --seed - (mssenv) $ export PYTHONPATH=~/mss - (mssenv) $ mswms & - (mssenv) $ mscolab start & - (mssenv) $ msui -``` + cd MSS + pixi shell + (MSS) msui + (MSS) mswms -h + (MSS) mscolab -h + (MSS) mssautoplot -h +##### Updating + + cd MSS + pixi shell + (MSS) pixi update mss + +#### Global installation +You can install **mss** global without defining a project first. +This method is practical when you are interested in starting the client +and don't need server configurations. + + pixi global install mss + +#### Usage + + msui + mswms -h + mscolab -h + mssautoplot -h + + +##### Updating + + pixi global update mss Current release info diff --git a/docs/components.rst b/docs/components.rst index a3eb80b40..941cdc41c 100644 --- a/docs/components.rst +++ b/docs/components.rst @@ -1,3 +1,5 @@ +.. _components: + Components ========== diff --git a/docs/conf.py b/docs/conf.py index 80e5e185d..b84efe222 100644 --- a/docs/conf.py +++ b/docs/conf.py @@ -153,20 +153,6 @@ def get_tutorial_images(): # The full version, including alpha/beta/rc tags. release = __version__ -# Replace $variables in the .rst files if on a readthedocs worker -if "/home/docs/checkouts" in " ".join(sys.argv): - mss_search = subprocess.run(["conda", "search", "-c", "conda-forge", "mss"], stdout=subprocess.PIPE, - stderr=subprocess.STDOUT, encoding="utf8").stdout - # mss_search is inside a code block, reflect indentation - mss_search = (" " * 3).join([line for line in mss_search.splitlines(True) if line.startswith("mss ")][-2:]) - - for file in os.listdir(): - if file.endswith(".rst"): - with open(file, "r") as rst: - content = Template(rst.read()) - with open(file, "w") as rst: - rst.write(content.safe_substitute(mss_version=version, mss_search=mss_search)) - # The language for content autogenerated by Sphinx. Refer to documentation # for a list of supported languages. # diff --git a/docs/development.rst b/docs/development.rst index 66f72cf31..f8340a0dc 100644 --- a/docs/development.rst +++ b/docs/development.rst @@ -17,6 +17,15 @@ When it is ready the developer version becomes the next stable. The stable version of MSS is tracked on `BLACK DUCK Open Hub `_ + +Contributing +------------ + +Please read our `contributing `_ guidelines and +`setup instructions `_ to get +started with MSS development. + + Using our Issue Tracker on github --------------------------------- @@ -37,9 +46,6 @@ Then, please `create a new issue `_ Be sure to include as much detail as possible including step-by-step descriptions, specific examples, screenshots or mockups, and reasoning for why the enhancement might be worthwhile. - - - Forking the Repo ---------------- @@ -103,44 +109,6 @@ If you don't have a stable branch, create one first or change to that branch:: git push -Setting Up a Local Environment ------------------------------- - -In the description we added as example to setup access to the mslib an export of the PYTHONPATH in your environment :: - - cd workspace/MSS - export PYTHONPATH=`pwd` - -When you don’t want to enter this you can add the PYTHONPATH to mslib to your .bashrc - -If you don’t want the PYTHONPATH by export changed you can start modules differently:: - - cd workspace/MSS - PYTHONPATH=. python mslib/msui/msui.py - - - - -Requirements -............ - -1. System requirements - - | Any system with basic configuration. - | Operating System : Any (Windows / Linux / Mac). - -2. Software requirement - - | Python - | `Miniforge `_ - | `Additional Requirements `_ - - -3. Skill set - - | Knowledge of git & github - | Python - Using predefined docker images instead of installing all requirements ..................................................................... @@ -194,6 +162,7 @@ After the image was configured you can use it like a self installed env :: + Manual Installing dependencies .............................. @@ -264,7 +233,6 @@ Going to http://localhost:8083/status should now show "MSColab server". This mea Now you can use the MSS desktop application to connect to it using the MSColab window of the application. - Code Style ---------- diff --git a/docs/installation.rst b/docs/installation.rst index 234d6b6c6..ce86201bb 100644 --- a/docs/installation.rst +++ b/docs/installation.rst @@ -1,88 +1,106 @@ Installation ============ -The Mission Support System (MSS) including a Web Map Service, a Collaboration Server and a Graphical User Interface is available as +The Mission Support System (MSS) including a Web Map Service (MSWMS), a Collaboration Server (MSColab) and a Graphical User Interface (MSUI) is available as `conda-forge `_ package. -This channel conda-forge has builds for osx-64, linux-64, win-64 +This channel conda-forge has builds for linux-64, osx-64, win-64, osx-arm64 The conda-forge `github organization `_ uses various automated continuous integration build processes. -We provide an automatic installation and a manual installation. +In 2024, the workflow that has packages co-installed from Anaconda's channel and conda-forge is `no longer supported +`_ +We recommend since version 10.0.0 of MSS to use `pixi `_ for an installation. +Get **pixi** from https://pixi.sh/latest/ for your operation system. -We recommend to use Mamba for an installation. -Automatic ---------- +You can now decide if you want to install **mss** as a project or global. +Further details what we provide in the mss package you can read +in the :ref:`components` section. +For the configuratation of the msui client see :ref:`msui-configuration` -* For **Windows**, use `Windows.bat `_ - #. Right click on the webpage and select "Save as..." to download the file +Project installation +-------------------- - #. Double click the downloaded file and follow further instructions +Initialize a new project and navigate to the project directory:: - * For fully automatic installation, open cmd and execute it with :code:`/Path/To/Windows.bat -a` + pixi init MSS + cd MSS -* For **Linux/Mac**, use `LinuxMac.sh `_ +Use the shell command to activate the environment and start a new shell in there.:: - #. Right click on the webpage and select "Save as..." to download the file + pixi shell - #. Make it executable via :code:`chmod +x LinuxMac.sh` +Add the **mss** dependencies from conda-forge.:: - #. Execute it and follow further instructions :code:`./LinuxMac.sh` + (MSS) pixi add mss - * For fully automatic installation, run it with the -a parameter :code:`./LinuxMac.sh -a` +Usage +..... +Always when you want to start **mss** programs you have after its installation +to activate the environment by pixi shell in the project dir. +On the very first start of **msui** it takes a bit longer because it setups fonts.:: -Manual ------- + cd MSS + pixi shell -Mamba based installation -........................ +:: + (MSS) msui + (MSS) mswms -h + (MSS) mscolab -h + (MSS) mssautoplot -h +Updating +........ -We strongly recommend to start from `Miniforge3 `_, -a community project of the conda-forge community. +:: -As **Beginner** start with an installation of Miniforge3 -- Get `Miniforge3 `__ for your Operation System + cd MSS + pixi shell + (MSS) pixi update mss -If you use already Mambaforge please read the `FAQ `__ +Global installation +------------------- +You can install **mss** global without defining a project first. +This method is practical when you are interested in starting the client +and don't need server configurations.:: + pixi global install mss -Install MSS -~~~~~~~~~~~ -You must install mss into a new environment to ensure the most recent -versions for dependencies. :: - $ mamba create -n mssenv - $ mamba activate mssenv - (mssenv) $ mamba install mss=$mss_version python - (mssenv) $ msui +Usage +..... +:: -Mamba Server based installation example -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + msui + mswms -h + mscolab -h + mssautoplot -h -For a wms server setup or mscolab setup you may want to have a dedicated user for the apache2 wsgi script. +Updating +........ + +:: + + pixi global update mss + + +Server based installation example +--------------------------------- + +For a WMS server setup or MSColab setup you may want to have a dedicated user for the apache2 wsgi script. We suggest to create a mss user. * create a mss user on your system * login as mss user -* create a *src* directory in /home/mss -* cd src -* get `Miniforge3 `__ -* set execute bit on install script -* execute script, enable environment in .bashrc -* login again -* mamba create -n mssenv -* mamba activate mssenv -* mamba install mss=$mss_version python - +* do a pixi project installation of **mss** For a simple test you could start the builtin standalone *mswms* and *mscolab* server:: $ mswms & @@ -93,75 +111,6 @@ Point a browser for the verification of both servers installed on - `http://127.0.0.1:8083/status `_ - `http://localhost:8081/?service=WMS&request=GetCapabilities&version=1.1.1 `_ -Further details in the components section on ``_ - - - - -Conda based installation -........................ - -`Anaconda `_ provides an enterprise-ready data analytics -platform that empowers companies to adopt a modern open data science analytics architecture. - -Please add the channel conda-forge to your defaults:: - - $ conda config --add channels conda-forge - -The conda-forge channel must be on top of the list before the anaconda default channel. - -From September 2023 libmamba is the `default installer in anaconda `__. - -Install MSS -~~~~~~~~~~~ - -You must install mss into a new environment to ensure the most recent -versions for dependencies. :: - - $ conda create -n mssenv - $ conda activate mssenv - (mssenv) $ conda install mss=$mss_version python --solver=libmamba - (mssenv) $ msui - - -Update Methods -.............. - -For updating an existing MSS installation to the current version, it is best to install -it into a new environment. If your current version is not far behind the new version -you could try the `mamba update mss` as described. - - -.. Important:: - mamba is under development. All dependencies of MSS and MSS itself are under development. - Sometimes this update feature of mamba can't resolve from existing to new dependencies. - -search for MSS what you can get :: - - (mssenv) $ mamba search mss - ... - $mss_search - - -compare what you have installed :: - - (mssenv) $ mamba list mss - - mss 7.0.2 py310hff52083_0 conda-forge - - -We have reports that often an update succeeds by using the install option and the new version number, -in this example $mss_version and python as second option :: - - (mssenv) $ mamba install mss=$mss_version python - -All attemmpts show what you get if you continue. **Continue only if you get what you want.** - -The alternative is to use a new environment and install mss. - - - -For further details of configuring mss :ref:`msui-configuration` Docker Instance @@ -234,3 +183,4 @@ You can start server and client by loading the image :: $ Singularity > mswms_demodata --seed # creates in your $HOME a mss/ folder with testdata $ Singularity > export PYTHONPATH=$HOME/mss; mswms # starts the development server $ Singularity > mscolab db --init; mscolab start # starts the mscolab development server + From adb354ea0167215f46b308c32cfa9af92a8cc361 Mon Sep 17 00:00:00 2001 From: Reimar Bauer Date: Sat, 8 Feb 2025 12:29:56 +0100 Subject: [PATCH 2/5] flake8 --- docs/conf.py | 3 --- 1 file changed, 3 deletions(-) diff --git a/docs/conf.py b/docs/conf.py index b84efe222..3980bcca6 100644 --- a/docs/conf.py +++ b/docs/conf.py @@ -14,14 +14,11 @@ import os import sys import setuptools -import subprocess import requests import zipfile import shutil import pathlib -from string import Template - def get_tutorial_images(): TUTORIAL_URL = "https://fz-juelich.sciebo.de/s/KcF29hPNRzkxN6q/download" From 96c8324324baaeb7c86b24139186e7aea4c6b5f1 Mon Sep 17 00:00:00 2001 From: Reimar Bauer Date: Thu, 13 Feb 2025 08:22:10 +0100 Subject: [PATCH 3/5] readded manual install and setup for devs --- docs/development.rst | 39 +++++++++++++++++++++++++++++++++++++++ 1 file changed, 39 insertions(+) diff --git a/docs/development.rst b/docs/development.rst index f8340a0dc..6b2c9e524 100644 --- a/docs/development.rst +++ b/docs/development.rst @@ -109,6 +109,45 @@ If you don't have a stable branch, create one first or change to that branch:: git push +Setting Up a Local Environment +------------------------------ + +In the description we added as example to setup access to the mslib an export of the PYTHONPATH in your environment :: + + cd workspace/MSS + export PYTHONPATH=`pwd` + +When you don’t want to enter this you can add the PYTHONPATH to mslib to your .bashrc + +If you don’t want the PYTHONPATH by export changed you can start modules differently:: + + cd workspace/MSS + PYTHONPATH=. python mslib/msui/msui.py + + + + +Requirements +............ + +1. System requirements + + | Any system with basic configuration. + | Operating System : Any (Windows / Linux / Mac). + +2. Software requirement + + | Python + | `Miniforge `_ + | `Additional Requirements `_ + + +3. Skill set + + | Knowledge of git & github + | Python + + Using predefined docker images instead of installing all requirements ..................................................................... From 6d60ea3fe6fd86c89fc8fdb9d0b5f2fe17bab183 Mon Sep 17 00:00:00 2001 From: Reimar Bauer Date: Thu, 13 Feb 2025 08:59:50 +0100 Subject: [PATCH 4/5] NL removed --- docs/development.rst | 2 -- 1 file changed, 2 deletions(-) diff --git a/docs/development.rst b/docs/development.rst index 6b2c9e524..5c7b053db 100644 --- a/docs/development.rst +++ b/docs/development.rst @@ -148,7 +148,6 @@ Requirements | Python - Using predefined docker images instead of installing all requirements ..................................................................... @@ -201,7 +200,6 @@ After the image was configured you can use it like a self installed env :: - Manual Installing dependencies .............................. From 14e7b8fdebe801aa91008a48003c308c9037417b Mon Sep 17 00:00:00 2001 From: Reimar Bauer Date: Thu, 13 Feb 2025 13:26:03 +0100 Subject: [PATCH 5/5] updated --- README.md | 42 +++++++++++++++--------------- docs/installation.rst | 59 +++++++++++++++++++++---------------------- 2 files changed, 50 insertions(+), 51 deletions(-) diff --git a/README.md b/README.md index cb8f0817b..8b7ce8cbb 100644 --- a/README.md +++ b/README.md @@ -24,7 +24,26 @@ and [development](https://mss.readthedocs.io/en/stable/development.html) guideli Get **pixi** from https://pixi.sh/latest/ for your operation system. -You can now decide if you want to install **mss** as a project or global. +You can now decide if you want to install **mss** as global or a project. + +#### Global installation +You can install **mss** global without defining a project first. +This method is practical when you are interested in starting the client +and don't need server configurations. + + pixi global install mss + +#### Usage + + msui + mswms -h + mscolab -h + mssautoplot -h + + +##### Updating + + pixi global update mss #### Project installation Initialize a new project and navigate to the project directory. @@ -33,7 +52,7 @@ Initialize a new project and navigate to the project directory. cd MSS Use the shell command to activate the environment and start a new shell in there. - + pixi shell Add the **mss** dependencies from conda-forge. @@ -59,25 +78,6 @@ On the very first start of **msui** it takes a bit longer because it setups font pixi shell (MSS) pixi update mss -#### Global installation -You can install **mss** global without defining a project first. -This method is practical when you are interested in starting the client -and don't need server configurations. - - pixi global install mss - -#### Usage - - msui - mswms -h - mscolab -h - mssautoplot -h - - -##### Updating - - pixi global update mss - Current release info ==================== diff --git a/docs/installation.rst b/docs/installation.rst index ce86201bb..942c2b98f 100644 --- a/docs/installation.rst +++ b/docs/installation.rst @@ -15,12 +15,40 @@ We recommend since version 10.0.0 of MSS to use `pixi ` Get **pixi** from https://pixi.sh/latest/ for your operation system. -You can now decide if you want to install **mss** as a project or global. +You can now decide if you want to install **mss** as global or a project. Further details what we provide in the mss package you can read in the :ref:`components` section. For the configuratation of the msui client see :ref:`msui-configuration` +Global installation +------------------- + +You can install **mss** global without defining a project first. +This method is practical when you are interested in starting the client +and don't need server configurations.:: + + pixi global install mss + + +Usage +..... + +:: + + msui + mswms -h + mscolab -h + mssautoplot -h + +Updating +........ + +:: + + pixi global update mss + + Project installation -------------------- @@ -63,34 +91,6 @@ Updating pixi shell (MSS) pixi update mss -Global installation -------------------- - -You can install **mss** global without defining a project first. -This method is practical when you are interested in starting the client -and don't need server configurations.:: - - pixi global install mss - - - -Usage -..... - -:: - - msui - mswms -h - mscolab -h - mssautoplot -h - -Updating -........ - -:: - - pixi global update mss - Server based installation example --------------------------------- @@ -183,4 +183,3 @@ You can start server and client by loading the image :: $ Singularity > mswms_demodata --seed # creates in your $HOME a mss/ folder with testdata $ Singularity > export PYTHONPATH=$HOME/mss; mswms # starts the development server $ Singularity > mscolab db --init; mscolab start # starts the mscolab development server -