Merge pull request #176 from eccenca/feature/include_wsl_documentation

Feature/include wsl documentation

Author: rpietzsch

docs/deploy-and-configure/installation/scenario-local-installation/index.md

@@ -13,15 +13,92 @@ The code examples in this section assumes that you have POSIX-compliant shell (l
 -   [docker](https://www.docker.com/) and [docker compose](https://docs.docker.com/compose/install/) (v2) installed locally
 -   [git](https://git-scm.com/book/en/v2/Getting-Started-Installing-Git) installed locally
 -   [jq](https://jqlang.github.io/jq/download/) installed locally
+-   make - build tools (apt-get install make) installed locally
 -   At least 4 CPUs and 12GB of RAM (recommended: 16GB) dedicated to docker
 
+## wsl installation and configuration
+
+For all you need to start Powershell started as administrator.
+Alternatively you can also install a WSL distribution from Microsoft Store.
+
+Install WSL, then restart your Windows machine.
+
+```shell
+wsl --install
+```
+
+List available distributions
+
+```shell
+wsl --list --online
+```
+
+Install a distribution.
+Chose from the `Name` column.
+Here we use a Debian based distribution like Debian or any Ubuntu.
+However other Distributions might work as well.
+
+```shell
+wsl --install Debian
+```
+
+Ensure you use wsl version 2 (this is necessary to use `systemd` services).
+
+```shell
+wsl -l -v
+```
+
+Install version 2 components (this requires a windows restart)
+
+```shell
+dism.exe /online /enable-feature /featurename:VirtualMachinePlatform /all /norestart
+```
+
+Enter WSL machine
+
+```shell
+wsl -d Debian
+```
+
+Enable `generateHosts = false` in your `/etc/hosts` file to make sure that this file won't be overwritten from the host system on every restart.
+
+To be able to use `systemd` services and commands make sure `/etc/wsl.conf` is available with this content (should be the default with wsl v2):
+
+```shell
+[boot]
+systemd=true
+```
+
+(Optional) If you need to restart your WSL use in Powershell:
+
+```shell
+wsl --shutdown
+```
+
+(Optional) you can create a `.wslconfig` file under `C:\users\<your username>` to specify some system resources like:
+
+```shell
+[wsl2]
+memory=16GB # restrict ram wsl can use
+processors=4 # restrict cpu-cores
+swap=8GB # set swap size
+swapFile=C:/Users/<your username>/wsl/Debianswap.vhdx  # location to swap-file
+```
+
+Alternatively, (with wsl v2) you may use the graphical configuration application _WSL Settings_.
+
 ## Setup & Check Installation Environment
 
+For docker we recommend to use the linux docker within wsl.
+Follow the instruction in [Server Provisioning in Scenario: Single Node Cloud Installation](../scenario-single-node-cloud-installation/index.md#server-provisioning).
+Alternatively, you may use docker for desktop and enable wsl integration in the settings.
+
 Open a terminal window, create a directory, copy and extract docker orchestration there.
 
-```bash
-# Create eccenca-corporate-memory directory in your ${HOME} and set as a 
+```shell
+# Create eccenca-corporate-memory directory in your ${HOME} and set as a
 # working dir.
+sudo apt install -y curl jq make git unzip gpg
 
 mkdir ${HOME}/eccenca-corporate-memory && cd ${HOME}/eccenca-corporate-memory
 
@@ -39,19 +116,19 @@ git init && git add . && git commit -m "stub"
 
 Check your local environment:
 
-```bash
+```shell
 # Run the following command to check your docker server version.
 # To have the current security patches, always update your docker version
 # to the latest one.
 
 docker version | grep -i version
-# Version:    26.1.4
+# Docker version: 27.5.1, build 9f9e405
 
 # Check docker compose version, should be at least v2.*.*
 # update to the latest version if necessary
 
 docker compose version
-# Docker Compose version v2.29.1
+# Docker Compose version v2.32.4
 
 # login into eccenca docker registry
 
@@ -65,7 +142,7 @@ docker login docker-registry.eccenca.com
 
 To install Corporate Memory, you need to modify your local hosts file (located in /etc/hosts), minimal configuration is as follows:
 
-```bash
+```shell
 ##
 # Host Database
 #
@@ -76,35 +153,37 @@ To install Corporate Memory, you need to modify your local hosts file (located i
 127.0.0.1 docker.localhost
 ```
 
-Corporate Memory uses Ontotext GraphDB triple store as default backend. Graphdb is available as free version and does not requires a license. If you have a license for graphdb you can copy the file to the ```license```folder inside Corporate Memory's root folder.
+Corporate Memory uses Ontotext GraphDB triple store as default backend.
+Graphdb is available as free version and does not requires a license.
+If you have a license for Ontotext GraphDB you can copy the file to the `license` folder inside Corporate Memory's root folder.
 
-```bash
+```shell
 cp YOUR_SE_LICENSE_FILE \
   ${HOME}/cmem-orchestration-VERSION/licenses/graphdb-se.license
 # or
 cp YOUR_EE_LICENSE_FILE \
   ${HOME}/cmem-orchestration-VERSION/licenses/graphdb-ee.license
 ```
 
-Then change the file ```environments/config.env``` to use the correct version:
+Then change the file `environments/config.env` to use the correct version:
 
-```bash
+```shell
 # Use Free, 'se' or 'ee' or adjust the mountpoint in 
 # compose/docker-compose.store.graphdb.yaml
 GRAPHDB_LICENSE=se
 ```
 
 Run the command to clean workspace, pull the images, start the Corporate Memory instance and load initial data:
 
-```bash
+```shell
 # Pulling the images will take time
 
 make clean-pull-start-bootstrap
 ```
 
 You should see the output as follows:
 
-```bash
+```shell
 make[1]: Entering directory '/home/ttelleis/cmem-dist/cmem-orchestration'
 The target cleans up everything and esp. REMOVES ALL YOUR DATA. Do you want to continue?
 
@@ -150,17 +229,17 @@ Run make logs to see log output
 
 Open your browser and navigate to <http://docker.localhost>
 
-| account | password | description                                                                                 |
-| ------- | -------- | ------------------------------------------------------------------------------------------- |
-| `admin` | `admin`  | Is member of the global admin group (can see and do anything)                               |
+| account | password | description |
+| ------- | -------- | ----------- |
+| `admin` | `admin`  | Is member of the global admin group (can see and do anything) |
 
 After successful login, you will see Corporate Memory interface. You can now proceed to the :arrow_right:[Getting Started](../../../getting-started/index.md) section.
 
 ### Backup
 
 To create a backup you have to prepare the backup folders. Make sure these folders exists and have write permissions. Run this:
 
-```bash
+```shell
 # assuming you are currently in the the cmem-orchestration folder
 mkdir -p data/backups/graphs data/backups/workspace
 chmod 777 data/backups/graphs data/backups/workspace
@@ -189,6 +268,16 @@ zip -r data/backups/2024-07-26_14-15.zip data/backups/keycloak/2024-07-26_14-15.
   adding: data/backups/graphs/2024-07-26_14-15.zip (stored 0%)
   adding: data/backups/python-packages/2024-07-26_14-15.zip (stored 0%)
 ln -sf 2024-07-26_14-15.zip data/backups/latest.zip
-
 ```
+
 The full backup is now at `data/backups/latest.zip`.
+
+### Caveats
+
+In case you have problems starting and receive error messages like Port 80 already assigned.
+Then check if a apache2 service is running and remove it.
+
+```shell
+sudo service apache2 status
+sudo service stop apache2
+```

docs/deploy-and-configure/installation/scenario-single-node-cloud-installation/index.md

@@ -42,6 +42,7 @@ sudo apt-get install docker-ce docker-ce-cli containerd.io \
     docker-compose-plugin
 
 # (optional) add a user to docker group
+# may require logout/login to reload group assignments
 # sudo usermod -a -G docker admin
 ```
 
@@ -62,7 +63,7 @@ cd /opt
 curl https://releases.eccenca.com/docker-orchestration/latest.zip \
     > cmem-orchestration.zip
 
-# unzip the orchestration and move the unzipped directory to 
+# unzip the orchestration and move the unzipped directory to
 # /opt/cmem-orchestration
 unzip cmem-orchestration.zip
 rm cmem-orchestration.zip