Skip to content

Commit

Permalink
Merge branch 'web-install' into 'master'
Browse files Browse the repository at this point in the history 
[web] Improved installation instructions and links

See merge request ogs/ogs!4728
  • Loading branch information
@bilke
bilke committed Sep 7, 2023
2 parents fda1ed0 + 98a3bc6 commit c8bf20e
Show file tree
Hide file tree
Showing 5 changed files with 71 additions and 57 deletions.
100 changes: 44 additions & 56 deletions web/content/docs/userguide/basics/introduction/index.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -19,100 +19,88 @@ category = "Beginner"

## Installation

There are various ways to obtain a running version of OpenGeoSys (OGS) on your machine. You can have OGS for different
operating systems including Windows, Linux, and macOS. Most of the functionality is available for all operating systems,
however, for parallel execution of OGS we recommend to set up OGS either under Linux or macOS. It is your choice, if you just
want to use prebuild version of OGS for easy use (or just to get started), or if you would like to customize your OGS-build for
your specific application, or even become an active development member. However, all kinds of installation will provide you
with a modelling platform including all physical processes available in OGS.
There are various ways to obtain a (pre-built) running version of OpenGeoSys (OGS) on your machine. You can have OGS for different
operating systems including Windows, Linux, and macOS. The basic modelling platform is available for all operating systems.
The different operating systems and installation methods give you the feature matrix:

<div class='win'>

One easy way to obtain your running version is
to just download the latest stable or development release of OpenGeoSys from the [Releases](/releases)-page. Be sure to pick
the correct file for your operating system.

By downloading from the release page you will get a bunch of folders and files. However, OGS itself will come as a simple
executable file, which you will find in the `bin` sub-folder. You can put the executable wherever you like. For convenience you
may put it into a location which is in your `PATH`-environment variable which allows you to start the executable without
specifying its full file path just calling `ogs` from the terminal of your machine.
| Operating system / Installation method | [Processes](/docs/userguide/blocks/processes/) | [MFront](/docs/userguide/features/mfront/) | [PETSc]({{< ref "parallel_computing_mpi" >}})
| ---------------------------------------------------------------------------------------------------------------------------- | :-------------------------------------------------------------------------------: | :----------------------------------------: | :-------------------------------------------:
| <i class="fab fa-windows"/> Windows / [pip](#install-via-pip) & [binary download](#alternative-install-via-binary-downloads) | `TH2M` disabled, [see issue](https://gitlab.opengeosys.org/ogs/ogs/-/issues/3197) | ❌ | ❌
| <i class="fab fa-apple"/> macOS / [pip](#install-via-pip) | All | ✅ | ❌
| <i class="fab fa-linux"/> Linux / [pip](#install-via-pip) & [Serial Container]({{< ref "container.md" >}}) | All | ✅ | ❌
| <i class="fab fa-linux"/> Linux / [PETSc Container]({{< ref "container.md" >}}) | All | ✅ | ✅

<div class="note">

### Alternative: Install via `pip`
### Using Linux binaries on other operating systems

Currently, we are actively developing a Python-interface for manipulating OGS-models, which greatly speeds up the modelling
workflow using OGS. Following this spirit, you can also install OGS via Python's [`pip`-tool](https://packaging.python.org/en/latest/tutorials/installing-packages/):
Please note that you can use Linux binaries installed via `pip` or in the form of a container also on other operating systems.

```bash
pip install ogs
```
For Windows we recommend the [Windows Subsystem for Linux (WSL)]({{< ref "wsl" >}}).

We recommend using Python within a [virtual environment](https://docs.python.org/3/library/venv.html) to keep possible
conflicts of different Python-packages localised. If you use `pip` for installation of OGS in a virtual environment and you
activate the virtual environment, then OGS and its tools are automatically also in the `PATH`. If the virtual environment is
not activated you may still use OGS, but either have to give the full path to `ogs` being located in the `bin` folder of the
virtual environment, or add this path to your `PATH`-environment. Moreover, `pip` may print instructions which directory needs
to be added to the `PATH`.

</div>
On macOS you can use either a virtual machine (e.g. via [UTM](https://docs.getutm.app/installation/macos/)) or run a [Docker container]({{< ref "container.md#with-docker" >}}).

</div>

<div class='linux'>
## Install via pip

A straightforward way of installing a running build of OGS is via Python's [`pip`-tool](https://packaging.python.org/en/latest/tutorials/installing-packages/):
A straightforward way of installing OGS is via Python's [`pip`-tool](https://packaging.python.org/en/latest/tutorials/installing-packages/):

```bash
# Optional: create a Python virtual environment, see below
python -m venv .venv # or `python3 -m venv .venv`
source .venv/bin/activate # Linux / macOS; for Windows: .\venv\Scripts\activate

# Install ogs' pip package
pip install ogs
```

Please note that this requires a Python installation (version 3.8 - 3.11) with the `pip`-tool.

We recommend using Python within a [virtual environment](https://docs.python.org/3/library/venv.html) to keep possible
conflicts of different Python-packages localised. If you use `pip` for installation of OGS in a virtual environment and you
activate the virtual environment, then OGS and its tools are automatically also in the `PATH`. If the virtual environment is
not activated you may still use OGS, but either have to give the full path to `ogs` being located in the `bin` folder of the
not activated you may still use OGS, but either have to give the full path to `ogs` being located in the `bin` folder (or `Scripts` folder on Windows) of the
virtual environment, or add this path to your `PATH`-environment. Moreover, `pip` may print instructions which directory needs
to be added to the `PATH`.

You could also use [`pipx`](https://pypa.github.io/pipx/) for installation into an isolated environment.

</div>
<div class="note">

<div class='mac'>
### Get current development version with `pip`

A straightforward way of installing a running build of OGS is via Python's [`pip`-tool](https://packaging.python.org/en/latest/tutorials/installing-packages/):
The following command will download the latest development version:

```bash
pip install ogs
pip install --pre --index-url https://gitlab.opengeosys.org/api/v4/projects/120/packages/pypi/simple ogs
```

We recommend using Python within a [virtual environment](https://docs.python.org/3/library/venv.html) to keep possible
conflicts of different Python-packages localised. If you use `pip` for installation of OGS in a virtual environment and you
activate the virtual environment, then OGS and its tools are automatically also in the `PATH`. If the virtual environment is
not activated you may still use OGS, but either have to give the full path to `ogs` being located in the `bin` folder of the
virtual environment, or add this path to your `PATH`-environment. Moreover, `pip` may print instructions which directory needs
to be added to the `PATH`.

You could also use [`pipx`](https://pypa.github.io/pipx/) for installation into an isolated environment.

</div>

<div class='win'>

<div class="note">

### Get current development version with `pip`
### Alternative: Install via binary downloads

The following command will download the latest development version:
Another way to obtain a running version is
to just download the latest stable or development release of OpenGeoSys from the [Releases](/releases)-page.

```bash
pip install --index-url https://gitlab.opengeosys.org/api/v4/projects/120/packages/pypi/simple ogs
```
By downloading from the release page you will get a bunch of folders and files. However, OGS itself will come as a simple
executable file, which you will find in the `bin` sub-folder. You can put the executable wherever you like. For convenience you
may put it into a location which is in your `PATH`-environment variable which allows you to start the executable without
specifying its full file path just calling `ogs` from the terminal of your machine.

</div>

### Limitations of the `pip`-based installation
</div>

<div class='linux'>

- Please note that via the `pip`-based installation only the serial configuration is available! For parallel execution of the
source code, PETSc is required. For PETSc-support please use a [Singularity container]({{< relref "container" >}}). <!-- TODO: The
link is outdated. Please replace Singularity by Apptainer. -->
- A Python (3.8 - 3.11) installation with `pip` is required.
</div>

<div class='mac'>

</div>

Expand Down
1 change: 1 addition & 0 deletions web/content/releases/6.4.4.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -16,6 +16,7 @@ container = [
"serial.sif",
"openmpi-4.0.5.sif",
]
pip = true
note = """
**Note:** When using Python bindings make sure to have Python installed on your system:
Expand Down
6 changes: 6 additions & 0 deletions web/content/releases/_index.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -7,6 +7,12 @@ weight = 1

aliases = ["/downloads", "/download"] # Redirect for Hydrology II tutorial

[[head_downloads]]
name = "Latest pip-installable package"
url = "/docs/userguide/basics/introduction#installation"
note = "All platforms: `pip install --pre --index-url https://gitlab.opengeosys.org/api/v4/projects/120/packages/pypi/simple ogs`"
icon = "far fa-arrow-right"

# url encode job name, https://www.w3schools.com/tags/ref_urlencode.ASP
[[head_downloads]]
name = "Latest Windows CLI with Utilities"
Expand Down
19 changes: 19 additions & 0 deletions web/layouts/partials/releases/single.html
View file
Original file line number Diff line number Diff line change
Expand Up @@ -2,6 +2,7 @@
{{ $gh_download := print "https://github.com/ufz/ogs/releases/download/" .Params.tag }}
{{ $benchmarks_url := print "https://github.com/ufz/ogs-data/archive/" .Params.tag ".zip" }}
{{ $type := "GitHub"}}
{{ $pypi_url := print "https://pypi.org/project/ogs/" .Params.tag }}
{{/* comparison only works for two version parts, strip out 6. */}}
{{ if gt (slicestr .Params.tag 2) "3.1" }}
{{ $gh_release = print "https://gitlab.opengeosys.org/ogs/ogs/-/releases/" .Params.tag }}
Expand Down Expand Up @@ -43,6 +44,24 @@ <h2><i class="far fa-download"></i> Downloads</h2>
</tr>
</thead>
<tbody class="bg-white divide-y divide-gray-200">
{{ if .Params.downloads.pip }}
<tr>
<td class="text-center">All</td>
<td><a style="text-decoration: none" href="{{ $pypi_url }}">OpenGeoSys + Utilities (Release on
PyPI)</a><br> <span class="text-xs"><b>Note:</b> <a
href="/docs/userguide/basics/introduction#installation">Recommended install
method</a> for
users on all platforms.
</span></td>
<td><span
class="px-2 inline-flex text-xs leading-5 font-semibold rounded-full bg-green-100 text-green-800">
Python bindings</i>
</span></td>
<td>
<a href="{{ $pypi_url }}">PyPI release page</a>
</td>
</tr>
{{ end }}

{{ range .Params.downloads.binary }}
<tr>
Expand Down
2 changes: 1 addition & 1 deletion web/layouts/releases/list.html
View file
Original file line number Diff line number Diff line change
Expand Up @@ -58,7 +58,7 @@ <h1 id="bugfixes">Current release with bug-fixes: {{ .Params.tag }}</h1>
<div class="bg-green-50 py-1 px-4 rounded-lg shadow mb-12">
<h3><i class="far fa-download"></i> Downloads</h3>
<ul>
{{ range $.Params.head_downloads }}
{{ range after 1 $.Params.head_downloads }} <!-- skip pip download -->
<li>
<i class="{{ .icon }}"></i>
<a href='{{ replace .url "master" $vtag }}'>{{ replace .name "Latest" $vtag }}</a>
Expand Down

0 comments on commit c8bf20e

Please sign in to comment.