updates for v10 based on pixi (#49)

Author: ReimarBauer

docs/02_installation.md

@@ -8,48 +8,105 @@ permalink: /install/
 ![image](https://img.shields.io/badge/Install%20with-conda-green.svg?style=flat-square)
 
 
-## Install distributed version by conda
+## Install by pixi
 
 
-We are based on [miniforge](https://github.com/conda-forge/miniforge#download),
-which provides the minimal installers for Conda and Mamba specific to conda-forge. The packages of the base are from the conda-forge channel.
-conda-forge is the default and only channel configured.
-MSS is available as a conda package on the channel.
+The Mission Support System (MSS) including a Web Map Service (MSWMS), a Collaboration Server (MSColab)
+and a Graphical User Interface (MSUI) is available as a [conda-forge](https://anaconda.org/conda-forge/mss) package.
 
-[conda-forge/mss](https://anaconda.org/conda-forge/mss)
+This channel conda-forge has builds for linux-64, osx-64, win-64, osx-arm64
 
-The conda-forge channel has builds for osx-64, linux-64 and win-64.
+The conda-forge [github organization](https://conda-forge.github.io/) uses various automated
+continuous integration build processes.
 
-The conda-forge [github organization](https://conda-forge.github.io/)
-uses various automated continuous integration build processes.
+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](https://pixi.sh/latest/) for an installation.
+Get **pixi** from https://pixi.sh/latest/ for your operation system.
 
+You can now decide if you want to install **mss** as global or a project.
 
-You must install mss into a new environment to ensure the most recent
-versions for dependencies:
+### Global Installation
 
-    $ mamba create -n mssenv mss
-    $ mamba activate mssenv
-    (mssenv) $ mss -h
+You can install **mss** globally without defining a project first.
+This method is practical when you are interested in starting the client and don't need server configurations.
 
-Afterwards reactivate the environment, this sets all env variables needed.
+```sh
+pixi global install mss
+```
 
-    (mssenv) $ mamba deactivate
-    $ mamba activate mssenv
+#### Usage
 
-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. 
+```sh
+msui
+mswms -h
+mscolab -h
+mssautoplot -h
+```
+
+#### Updating
+
+```sh
+pixi global update mss
+```
+
+### Project Installation
+
+Initialize a new project and navigate to the project directory:
+
+```sh
+pixi init MSS
+cd MSS
+```
+
+Use the shell command to activate the environment and start a new shell in there.
+
+```sh
+pixi shell
+```
+
+Add the **mss** dependencies from conda-forge.
+
+```sh
+(MSS) pixi add mss
+```
+
+#### Usage
+
+Always, when you want to start **mss** programs after its installation,
+you have 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 setup fonts.
+
+```sh
+cd MSS
+pixi shell
+```
+
+```sh
+(MSS) msui
+(MSS) mswms -h
+(MSS) mscolab -h
+(MSS) mssautoplot -h
+```
+
+#### Upgrading
+
+```sh
+cd MSS
+pixi shell
+(MSS) pixi upgrade mss
+```
 
-    $ mamba activate mssenv
-    (mssenv) $ mamba update mss
-    (mssenv) $ mamba update --all
 
 ## Usage
+
+We describe the global installation.
+
 ### GUI
-To start the MSS UI you can lookup for "mss" on your desktop program manager or use a terminal  
+To start the MSS UI you have to use a terminal.
 
-    (mssenv) $ mss
+```sh
+$ msui
+```
 
 > ![image](/assets/msui.png)
 
@@ -59,8 +116,10 @@ The configuration is described in the section
 ### mswms server
 To try out the setup you can use demo data. Read about a [server based installation](https://mss.readthedocs.io/en/stable/deployment.html). 
 
-    (mssenv) $ mswms_demodata --seed
-    (mssenv) $ mswms
+```sh
+    $ mswms_demodata --seed
+    $ mswms
+```
 
 This data is then available on localhost:8081.
 The capabilities can be read on a [web browser](http://localhost:8081/?service=WMS&request=GetCapabilities&version=1.1.1) too. 
@@ -70,9 +129,10 @@ The capabilities can be read on a [web browser](http://localhost:8081/?service=W
 ### mscolab server
 To tryout the setup you can use demo data. Read about a [server based installation](https://mss.readthedocs.io/en/stable/mscolab.html).
 
-    (mssenv) $ mscolab db --init
-    (mssenv) $ mscolab db --seed
-    (mssenv) $ mscolab start
+```sh
+    $ mscolab db --seed
+    $ mscolab start
+```
 
 The service is than availale on localhost:8083 and can be verified by the [server status](http://127.0.0.1:8083/status) 
 

docs/03_contributing.md

@@ -16,7 +16,7 @@ MSS is completely written in Python. The GUI is built using [PyQT5](https://www.
 
 ## Setup Instructions
 
-You can quickly setup MSS on your machine by following the steps given in our [setup instructions](/develop/Setup-Instructions). If you want to use Docker you can follow the steps in our [docker setup guide](/develop/docker_images). For more details, you can read [Mission Support System’s Documentation](https://mss.readthedocs.io/en/stable)
+You can quickly setup MSS on your machine by following the steps given in our [setup instructions](/develop/Setup-Instructions).
 
 ## Finding Issues
 

docs/04_gsoc.md

@@ -23,7 +23,7 @@ If you have any question please feel free to ask any of the mentors on our #gsoc
 We have labled small sized issues as "good first issue" on <https://github.com/Open-MSS/MSS/issues>.
 
 # Getting Started
- - You can quickly setup MSS on your machine by following the steps given in our [setup instructions](/develop/Setup-Instructions). If you want to use Docker you can follow the steps in our [docker setup guide](/develop/docker_images). For more details, you can read [Mission Support System’s Documentation](https://mss.readthedocs.io/en/stable)
+ - You can quickly setup MSS on your machine by following the steps given in our [setup instructions](/develop/Setup-Instructions).  For more details, you can read [Mission Support System’s Documentation](https://mss.readthedocs.io/en/stable)
  - You can go through the issues labelled as [good first issue](https://github.com/Open-MSS/MSS/issues?q=is%3Aissue+is%3Aopen+label%3A%22good+first+issue%22) on our github repository and pick an issue you feel you can take up. Please write a comment on the issue you're taking up so multiple people don't work on the same issue. If you have any doubts related to the issue feel free to ask us on the Slack channel. You can also report any new issue you find on the Slack channel itself.
  - Once you've found the issue you want to work on you need to create a new branch on your local clone of the project and start working on it. As a general rule of thumb, bug fixes go to the `stable` branch while enhancements and other new features go to the `develop` branch. Generally it is mentioned in the issue itself which branch the fix needs to go. Otherwise you can always ask us on Slack.
  - To start working, create a new git branch, write your code, commit it and push this branch to your fork. Now create a pull request to the Master Repo's `develop` or `stable` branch. All pull requests must pass the test pipeline before they are merged.

docs/assets/msui.png

@@ -17,21 +17,19 @@ exclude: true
 -   Are there any unusual libraries/applications that need to be
     installed first?
 
-    We are based on [miniforge](https://github.com/conda-forge/miniforge#download) and [conda-forge](https://conda-forge.org/). 
+    We are based on [pixi](https://pixi.sh/latest/) and [conda-forge](https://conda-forge.org/).
     All development is done with python 3.
 
-    On linux install `xvfb` and the conda package `pyvirtualdisplay`. This is used to run tests on a virtual display.  
-
 
 -   How do I have to setup my environment?
 
     Dependent on the IDE there are differences, we try to describe this for anycase.
 
       * Verify by `pytest` in your MSS directory that tests are executed
-      * `python workspace/MSS/mslib/mswms/demodata.py -h` (see output on screen)
-      * `python workspace/MSS/mslib/mswms/mswms.py -h`
-      * `python workspace/MSS/mslib/msui/msui.py -h`
-      * `python workspace/MSS/mslib/mscolab/server.py -h`
+      * `mswms_demodata -h` (see output on screen)
+      * `mswms -h`
+      * `msui -h`
+      * `mscolab -h`
 
 
 -   What type of source control do you use? 

docs/assets/run_mss_docker.png

@@ -5,86 +5,93 @@ permalink: /develop/Setup-Instructions
 exclude: true
 ---
 
-## Environment Setup
+## Setup for development
 
-### Install distributed version by mamba
+Pixi is a package management tool for developers. It allows the developer to install libraries and
+applications in a reproducible way. Use pixi cross-platform, on Windows, Mac and Linux.
 
-Install miniforge on your system.
+Install pixi on your system.
 
-[Miniforge](https://github.com/conda-forge/miniforge#download) provides the minimal installers 
-for Conda and Mamba specific to conda-forge. The packages of the base are from the conda-forge channel.
-conda-forge is the default and only channel configured.
+[Pixi](https://pixi.sh) provides the minimal installers
+specific to conda-forge. conda-forge is the default channel configured.
 
 MSS is available as a package on the channel conda-forge.
 
 [conda-forge/mss](https://anaconda.org/conda-forge/mss)
 
-The conda-forge channel has builds for osx-64, linux-64 and win-64.
+The conda-forge channel has builds for osx-64, osx-arm64, linux-64 and win-64.
 
-You must install mss into a new environment to ensure the most recent
-versions for dependencies. :
 
-    $ mamba create -n mssdev mss --only-deps
-    $ mamba activate mssdev
-    (mssdev) $ 
+#### Setup an environment for development
 
-Afterwards reactivate the environment, this sets all env variables needed.
+The dependencies necessary to get a working development environment for MSS are specified in pixi.toml and pixi.lock inside the repository.
+This means you can get a shell with all required packages installed using
 
-    (mssdev) $ mamba deactivate
-    $ mamba activate mssdev
+```sh
+    pixi shell -e dev
+```
 
-### Installing development specific packages
+Afterwards, a call to e.g.
 
-Between the released and the develop version we have differences in used packages:
+```sh
+    msui
+```
 
-    git diff stable develop -- localbuild/meta.yaml
-    
-Update accordingly of the output.
+will run the development version of msui.
 
-For testing and building docs you need to install the these packages by running the following command:
+You can also use pixi's "run" subcommand to directly run a command in the development environment, like so::
+
+```sh
+    pixi run -e dev msui
+```
 
-    (mssdev) $ mamba install --file MSS/requirements.d/development.txt
 
 ## Running The Application
 
 MSS has 3 main components. These are MSUI (GUI), MSWMS (web map server) and MSCOLAB (collaboration server). You can run all 3 components individually on your system. 
 (Before running any of the commands make sure you have activated your environment.)
 
-You need to first add the main mss folder which will be created in your home directory to your python path. Go into the cloned repo and update your python path:
+You need to first add the mss folder where additional configurations can become provided.
+There the mswms_demodata adds the mswms demo server configuration. 
 
+```sh
     $ cd MSS
-    $ export PYTHONPATH="`pwd`:$HOME/mss"
+    $ pixi shell -e dev
+    $ (MSS) export PYTHONPATH=$HOME/mss"
+```
 
 To start the MSS PyQT application:
-
-    (mssdev) $ python mslib/msui/msui.py
-
+```sh
+    (MSS) $ msui
+```
 When running MSWMS for the first time. Use the following command to create some dummy data:
-
-    (mssdev) $ python mslib/mswms/demodata.py --seed
-
+```sh
+    (MSS) $ mswms_demodata --seed
+```
 To start MSWMS:
-
-    (mssdev) $ python mslib/mswms/mswms.py
-
+```sh
+    (MSS) $ mswms
+```
 When running MSCOLAB for the first time you need to initialize your database (SQLite by default):
 
-    (mssdev) $ python mslib/mscolab/mscolab.py db --init
-
+```sh
+    (MSS) $ mscolab db --init
+```
 If you want to seed your MSCOLAB database you can run:
 
-    (mssdev) $ python mslib/mscolab/mscolab.py db --seed
+```sh
+    (MSS) $ mscolab db --seed
+```
 
 To start MSCOLAB server:
 
-    (mssdev) $ python mslib/mscolab/mscolab.py start
-
+```sh
+    (MSS) $ mscolab start
+```
 ## Running Tests
 
-On linux install the conda package pyvirtualdisplay and xvfb from your linux package manager. This is used to run tests on a virtual display. If you don’t want tests redirected to the xvfb display just setup an environment variable:
-
-    $ export TESTS_VISIBLE=TRUE
-
 To run the tests:
 
-    (mssdev) $ pytest --cov mslib
+```sh
+    (MSS) $ pytest --cov mslib
+```