diff --git a/.devcontainer.json b/.devcontainer.json
index 8f68abe9b01411b8df713108e0f31df115fd7722..2cd3004c19c3a69139e48e50e7e7a678fb49bc36 100644
--- a/.devcontainer.json
+++ b/.devcontainer.json
@@ -1,9 +1,6 @@
{
"name": "ogs-gcc-dev",
"image": "registry.opengeosys.org/ogs/ogs/vscode:latest",
- "containerEnv": {
- "CPM_SOURCE_CACHE": "/opt/cpm"
- },
"postStartCommand": "nohup bash -c 'cd web; yarn; yarn build; hugo server &'",
"forwardPorts": [
1313
diff --git a/web/content/docs/devguide/advanced/vscode-devcontainer/devcontainer_debug.png b/web/content/docs/devguide/advanced/vscode-devcontainer/devcontainer_debug.png
new file mode 100644
index 0000000000000000000000000000000000000000..29a368870a533d462ee6421624dd2072cbf1389f
Binary files /dev/null and b/web/content/docs/devguide/advanced/vscode-devcontainer/devcontainer_debug.png differ
diff --git a/web/content/docs/devguide/advanced/vscode-devcontainer/devcontainer_footer.png b/web/content/docs/devguide/advanced/vscode-devcontainer/devcontainer_footer.png
new file mode 100644
index 0000000000000000000000000000000000000000..74dee29d6b7a09d2d6a09c11dc2196dc117f0ea8
Binary files /dev/null and b/web/content/docs/devguide/advanced/vscode-devcontainer/devcontainer_footer.png differ
diff --git a/web/content/docs/devguide/advanced/vscode-devcontainer/index.md b/web/content/docs/devguide/advanced/vscode-devcontainer/index.md
new file mode 100644
index 0000000000000000000000000000000000000000..bcda58a8b7fdd366efcc6665b8911bb320812713
--- /dev/null
+++ b/web/content/docs/devguide/advanced/vscode-devcontainer/index.md
@@ -0,0 +1,74 @@
++++
+date = "2018-02-26T11:00:13+01:00"
+title = "Develop with VS Code Remote – Containers"
+author = "Lars Bilke"
+weight = 1061
+
+[menu]
+ [menu.devguide]
+ parent = "advanced"
++++
+
+[Visual Studio Code](https://code.visualstudio.com/) is a powerful text editor which can be expanded to a full featured integrated development environment (IDE) with plugins. With the [Visual Studio Code Remote - Containers](https://code.visualstudio.com/docs/remote/containers) extension you can use prebuilt Docker container as the runtime environment for your code development. This page serves as an alterntive to the [Getting Started]({{< relref "docs/devguide/getting-started/introduction.md" >}})-section. The following features make this a nice development environment:
+
+- All ogs prerequisites (except of MPI / PETSc support, may come later) already setup.
+- Code editing with auto-completion.
+- Easy build configuration by simply selecting CMake presets.
+- Start a debugging session with a click of a button.
+- Hugo web server automatically running at [http://localhost:1313](http://localhost:1313) watching for changes in `web/content`.
+- `zsh`-terminal with sane defaults (`oh-my-zsh`).
+-
+- Works also on a remote machine!
+
+## Set-up prerequisites
+
+- Install Git [as described in the Getting-Started section]({{< relref "prerequisites#step-install-git" >}}).
+- Clone the OGS source code [as described in the Getting-Started section]({{< relref "get-the-source-code#option-clone-the-source-code-repository-with-git" >}}).
+- Create a `build`-directory at the same level as the `ogs` source code directory.
+- Install [Docker](https://docs.docker.com/get-docker/) (**or** have a Docker machine available where you have SSH access).
+- Install [VS Code](https://code.visualstudio.com).
+- Inside VS Code install the [Remote Development](https://marketplace.visualstudio.com/items?itemName=ms-vscode-remote.vscode-remote-extensionpack) extension pack (includes *Remote – Containers* and *Remote – SSH* extensions).
+
+## Open OGS source code inside the development container
+
+- Open VS Code.
+- Open the OGS source code folder.
+- Press `F1` and type `reopen in [container]`, press `ENTER`.
+
+This takes now some time as the container is downloaded from the registry. Once finished you should see the following in the bottom status bar:
+
+
+
+## Debug ogs
+
+As an example use case we configure, build and debug the ogs executable.
+
+CMake configuration is handled by using CMake presets which can be selected from the bottom status bar in VS Code. See the [Configure and build with CMake Presets in Visual Studio Code](https://github.com/microsoft/vscode-cmake-tools/blob/main/docs/cmake-presets.md) for details.
+
+In the editor:
+
+- Open `ogs.cpp`
+- Set a [breakpoint](https://code.visualstudio.com/docs/editor/debugging#_breakpoints) in the first line of the `main()`-function (around line 58) by clicking on the left gutter in the editor window (a red dot marks the enabled breakpoint).
+
+In the status bar:
+
+1. Select the `debug` preset.
+2. Click the `Build` button.
+3. Select `ogs` as the launch target.
+4. Click the bug icon.
+
+After some seconds the status bar color changes orange to indicate an active debugging session:
+
+
+
+## Use a remote machine
+
+All of this works also via ssh. If you do not have Docker locally running but some server with Docker where you have ssh access to you can do the following:
+
+- Open VS Code.
+- Click the green button on the bottom left.
+- Press `ENTER` (*Connect to host*).
+- Choose the server.
+- [Now you are in a [Remote – SSH](https://code.visualstudio.com/docs/remote/ssh)-session.]
+- Open the OGS source code folder (you have to clone it before on that server).
+- Press `F1` and type `reopen in [container]`, press `ENTER`.
diff --git a/web/content/docs/devguide/environments/docker/index.md b/web/content/docs/devguide/environments/docker/index.md
index 091d5ade6c9478741c7a1ece9ab3b10a877207d0..e13d9735d9e250ac9d302f2e48068ce322d00ba3 100644
--- a/web/content/docs/devguide/environments/docker/index.md
+++ b/web/content/docs/devguide/environments/docker/index.md
@@ -19,7 +19,7 @@ aliases = ["/docs/devguide/advanced/docker"]
> <cite>[www.docker.com/whatisdocker](https://www.docker.com/whatisdocker)</cite>
<!-- vale on -->
-See the [docs](https://docs.docker.com) for installation instructions (if you are on Windows we highly recommend the [Docker Desktop WSL 2 backend](https://docs.docker.com/docker-for-windows/wsl/)).
+See the [docs](https://docs.docker.com/get-docker/) for installation instructions (if you are on Windows we highly recommend the [Docker Desktop WSL 2 backend](https://docs.docker.com/docker-for-windows/wsl/)).
## Images
diff --git a/web/content/docs/devguide/getting-started/introduction/index.md b/web/content/docs/devguide/getting-started/introduction/index.md
index 91eb3055792e8efa73bfef743e8d98e722818f92..9d5ea6b2866b8ac61a0b4550fe85fe8d77f62573 100644
--- a/web/content/docs/devguide/getting-started/introduction/index.md
+++ b/web/content/docs/devguide/getting-started/introduction/index.md
@@ -17,8 +17,10 @@ parent = "getting-started"
+++
-In this help section you will find everything related to development. Please walk through the Getting Started-section **step by step**. At the end you will have the latest OGS source code and the OGS finite element simulator compiled and ready to run! This first section of the developer guide will give you just a brief introduction, make sure to read the more advanced topics after you have familiarized yourself with the basics.
+In this help section you will find everything related to setting up a native development environment. Please walk through the Getting Started-section **step by step**[^1]. At the end you will have the latest OGS source code and the OGS finite element simulator compiled and ready to run! This first section of the developer guide will give you just a brief introduction, make sure to read the more advanced topics after you have familiarized yourself with the basics.
If you **want to contribute** to the OGS project please also walk through the [Development Workflows]({{< ref "/docs/devguide/development-workflows/introduction.md" >}})-section **step-by-step**.
Instructions may differ depending on your operating system (OS). Be sure to pick the right one in the **OS selector** at the top of the **next page**.
+
+[^1]: If you want to take a shortcut and have a machine with the Docker container runtime available you may want to look at [VS Code Remote – Containers]({{< relref "vscode-devcontainer" >}})!