From f3dd616789655ca5f4fb5a9355560d91233a4cd3 Mon Sep 17 00:00:00 2001 From: Michele Simionato Date: Mon, 23 Oct 2023 09:40:56 +0200 Subject: [PATCH 1/3] Updated the documentation for installating the engine on Windows --- doc/faq.md | 90 ++----------------------------------- doc/installing/universal.md | 22 ++++++--- doc/installing/windows.md | 33 -------------- 3 files changed, 20 insertions(+), 125 deletions(-) delete mode 100644 doc/installing/windows.md diff --git a/doc/faq.md b/doc/faq.md index 22f5cdeafc2b..eb8e7ae866f3 100644 --- a/doc/faq.md +++ b/doc/faq.md @@ -131,34 +131,12 @@ The OpenQuake Engine has several installation methods. To choose the one that be ### Supported operating systems -Binary packages are provided for the following 64bit operating systems: -- [Windows 10](installing/windows.md) -- [macOS 11.6+](installing/universal.md) -- Linux [Ubuntu 18.04+](installing/ubuntu.md) and [RedHat/CentOS 7/RockyLinux 8 ](installing/rhel.md) via _deb_ and _rpm_ -- Any other generic Linux distribution via the [universal installer](installing/universal.md) -- [Docker](installing/docker.md) hosts +Binary packages are provided for Windows. For all other systems use the +[universal installer](installing/universal.md). We also provide +[Docker](installing/docker.md). A 64bit operating system **is required**. Please refer to each OS specific page for details about requirements. -****** - -### Unsupported operating systems - -- Windows 8 may or may not work and we will not provide support for it -Binary packages *may* work on Ubuntu derivatives and Debian if the dependencies are satisfied; these configurations are known to work: -- Ubuntu 18.04 (Bionic) packages work on **Debian 10.0** (Buster) -- Ubuntu 20.04 (Focal) packages work on **Debian 11.0** (Bullseye) - -These configurations however are not tested and we cannot guarantee on the quality of the results. Use at your own risk. - -****** - -### 32bit support - -The OpenQuake Engine **requires a 64bit operating system**. Starting with version 2.3 of the Engine binary installers and packages aren't provided for 32bit operating systems anymore. - -****** - ### MPI support MPI is not supported by the OpenQuake Engine. Task distribution across network interconnected nodes is done via *zmq*. The worker nodes must have read access to a shared file system writeable from the master node. Data transfer is made on TCP/IP connection. @@ -173,62 +151,6 @@ Support for Python 2.7 has been dropped. The last version of the Engine compatib ****** -### Python scripts that import openquake - -On **Ubuntu** and **RHEL** if a third party python script (or a Jupyter notebook) needs to import openquake as a library (as an example: `from openquake.commonlib import readinput`) you must use a virtual environment and install a local copy of the Engine: - -``` -$ python3 -m venv -$ . /path/to/myvenv/bin/activate -$ pip3 install openquake.engine -``` - -****** - -### Errors upgrading from an old version on Ubuntu - -When upgrading from an OpenQuake version **older than 2.9 to a newer one** you may encounter an error on **Ubuntu**. Using `apt` to perform the upgrade you may get an error like this: - -```bash -Unpacking oq-python3.5 (3.5.3-1ubuntu0~gem03~xenial01) ... -dpkg: error processing archive /var/cache/apt/archives/oq-python3.5_3.5.3-1ubuntu0~gem03~xenial01_amd64.deb (--unpack): - trying to overwrite '/opt/openquake/bin/easy_install', which is also in package python-oq-libs 1.3.0~dev1496296871+a6bdffb -``` - -This issue can be resolved uninstalling OpenQuake first and then making a fresh installation of the latest version: - -```bash -$ sudo apt remove python-oq-.* -$ sudo rm -Rf /opt/openquake -$ sudo apt install python3-oq-engine -``` - -****** - -### OpenQuake Hazardlib errors - -```bash -pkg_resources.DistributionNotFound: The 'openquake.hazardlib==0.XY' distribution was not found and is required by openquake.engine -``` -Since OpenQuake Engine 2.5, the OpenQuake Hazardlib package has been merged with the OpenQuake Engine one. - -If you are using git and you have the `PYTHONPATH` set you should update `oq-engine` and then remove `oq-hazardlib` from your filesystem and from the `PYTHONPATH`, to avoid any possible confusion. - -If `oq-hazardlib` has been installed via `pip` you must uninstall both `openquake.engine` and `openquake.hazardlib` first, and then reinstall `openquake.engine`. - -```bash -$ pip uninstall openquake.hazardlib openquake.engine -$ pip install openquake.engine -# -OR- development installation -$ pip install -e /path/to/oq-engine/ -``` - -If you are using Ubuntu or RedHat packages no extra operations are needed, the package manager will remove the old `python-oq-hazardlib` package and replace it with a fresh copy of `python3-oq-engine`. - -On Ubuntu make sure to run `apt dist-upgrade` instead on `apt upgrade` to make a proper upgrade of the OpenQuake packages. - -****** - ### 'The openquake master lost its controlling terminal' error When the OpenQuake Engine is driven via the `oq` command over an SSH connection an associated terminal must exist throughout the `oq` calculation lifecycle. @@ -248,12 +170,6 @@ configuration file) is `1908` (for a development installation) or `1907` ****** -### Swap partitions - -Having a swap partition active on resources fully dedicated to the OpenQuake Engine is discouraged. More info [here](installing/cluster.md#swap-partitions). - -****** - ### System running out of disk space The OpenQuake Engine may require lot of disk space for the raw results data (`hdf5` files stored in `/home//oqdata`) and the temporary files used to either generated outputs or load input files via the `API`. On certain cloud configurations the amount of space allocated to the root fs (`/`) is fairly limited and extra 'data' volumes needs to be attached. To make the Engine use these volumes for `oqdata` and the _temporary_ storage you must change the `openquake.cfg` configuration; assuming `/mnt/ext_volume` as the mount point of the extra 'data' volume, it must be changed as follow: diff --git a/doc/installing/universal.md b/doc/installing/universal.md index 5e5525d69853..7202f936b247 100644 --- a/doc/installing/universal.md +++ b/doc/installing/universal.md @@ -1,7 +1,14 @@ +# Binary installer for Windows + +Windows users can use a traditional .exe installer which can be downloaded from +https://downloads.openquake.org/pkgs/windows/oq-engine/ and includes Python 3.10 +and all dependencies. However users needing to develop with the engine are better +off with the universal installation script, even on Windows. + # Universal installation script Since version 3.11 of the OpenQuake-engine, there is a universal installation script that works on any platform, provided you have a suitable Python installed. -The script allows the user to select between different kinds of installations: +The script allows the user to select between different kinds of installation: 1. [`user` installation](#user-installation) (Windows, macOS, and Linux) 2. [`devel` installation](#devel-installation) (Windows, macOS, and Linux) @@ -23,7 +30,9 @@ Alternatively, use Python from one of the OS X package managers (Homebrew, MacPo >
>_**Note 5.** Conda is not supported; some users have been able to run the OpenQuake-engine with Conda, but GEM is not using and not testing conda; you are on your own._ >
->_**Note 6.** On Windows installations we recommend using Python 3.10._ +>_**Note 6.** On Windows installations we require Python 3.10, while the Microsoft App +Store suggests Python 3.11 which is not supported yet, so you have to be careful and +search for Python 3.10 on the App Store or on the Python official download page._ After installing, you can get the location of the engine virtual enviroment with the command ``` @@ -70,13 +79,14 @@ C:\>%USERPROFILE%\openquake\Scripts\activate.bat ``` or, when using PowerShell, ``` +Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope CurrentUser C:\>%USERPROFILE%\openquake\Scripts\activate.ps1 ``` + **on macOS and Linux:** ``` $ source $HOME/openquake/bin/activate ``` - You can also invoke the `oq` command without activating the virtual environment by directly calling **on Windows:** @@ -91,8 +101,6 @@ $HOME/openquake/bin/oq Calculation data will be stored in `$HOME/oqdata`. - - ## `devel` installation Users who intend to modify the engine codebase or add new features for the engine should use the `devel` installation: @@ -110,6 +118,10 @@ C:\> git clone https://github.com/gem/oq-engine.git C:\> cd oq-engine C:\> python.exe install.py devel ``` +If using PowerShell you may have to give the command +``` +Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope CurrentUser +``` **on macOS:** diff --git a/doc/installing/windows.md b/doc/installing/windows.md deleted file mode 100644 index 639b670525af..000000000000 --- a/doc/installing/windows.md +++ /dev/null @@ -1,33 +0,0 @@ -# Installing the OpenQuake Engine on Windows - -The OpenQuake Engine can be installed on Windows with the [universal -installer](universal.md) (recommended if you plan to develop GMPEs) -or with a traditional .exe installer which can be downloaded from -https://downloads.openquake.org/pkgs/windows/oq-engine/ . -The .exe installer uses Python 3.10 and we recommend to use the same -Python version also with the universal installer. - -## Requirements - -Requirements are: - -- Windows 10 (64bit) -- 8 GB of RAM -- 4 GB of free disk space - -**Windows 7** and **Windows 8** are not supported. That means that we do -not test such platforms and they engine may or may not work there. Also, it -may work for small calculations and hang for large calculations, as it has -been reported by a few users. For large calculations (i.e. any calculation -in the hazard or risk mosaic) we recommend to use a Linux server. - -## Run the OpenQuake Engine - -Continue on [How to run the OpenQuake Engine](../running/windows.md) - -*** - -## Getting help -If you need help or have questions/comments/feedback for us, you can: - * Subscribe to the OpenQuake users mailing list: https://groups.google.com/g/openquake-users - * Contact us on IRC: irc.freenode.net, channel #openquake From af86bea76cb77d251a4c695a34150a702371b5c7 Mon Sep 17 00:00:00 2001 From: Michele Simionato Date: Mon, 23 Oct 2023 09:44:23 +0200 Subject: [PATCH 2/3] [ci skip] --- doc/faq.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/doc/faq.md b/doc/faq.md index eb8e7ae866f3..ba1a458e04be 100644 --- a/doc/faq.md +++ b/doc/faq.md @@ -133,7 +133,7 @@ The OpenQuake Engine has several installation methods. To choose the one that be Binary packages are provided for Windows. For all other systems use the [universal installer](installing/universal.md). We also provide -[Docker](installing/docker.md). +[Docker containers](installing/docker.md). A 64bit operating system **is required**. Please refer to each OS specific page for details about requirements. From e6ffe0e8347c29c1f56ac1e733ca2c67296a3eb4 Mon Sep 17 00:00:00 2001 From: Michele Simionato Date: Mon, 23 Oct 2023 09:46:10 +0200 Subject: [PATCH 3/3] [ci skip] --- doc/faq.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/doc/faq.md b/doc/faq.md index ba1a458e04be..f4a2355cebf5 100644 --- a/doc/faq.md +++ b/doc/faq.md @@ -131,9 +131,9 @@ The OpenQuake Engine has several installation methods. To choose the one that be ### Supported operating systems -Binary packages are provided for Windows. For all other systems use the -[universal installer](installing/universal.md). We also provide -[Docker containers](installing/docker.md). +Binary packages are [provided for Windows](https://downloads.openquake.org/pkgs/windows/oq-engine). For all other systems use the [universal +installer](installing/universal.md). We also provide [Docker +containers](installing/docker.md). A 64bit operating system **is required**. Please refer to each OS specific page for details about requirements.