Merge pull request #2124 from jburel/centos8

Centos8

omero/sysadmins/unix/install-web/walkthrough/omeroweb-install-centos8-ice3.6.rst

@@ -0,0 +1,198 @@
+.. walkthroughs are generated using ansible, see 
+.. https://github.com/ome/omeroweb-install
+
+OMERO.web installation on CentOS 8 and IcePy 3.6
+================================================
+
+Please first read :doc:`../../server-centos8-ice36`.
+
+
+This is an example walkthrough for installing OMERO.web in a **virtual environment** using a dedicated system user. Installing OMERO.web in a virtual environment is the preferred way. For convenience in this walkthrough, we will use the **omero-web system user** and define the main OMERO.web configuration options as environment variables. Since 5.6, a new :envvar:`OMERODIR` variable is used, you should first unset :envvar:`OMERO_HOME` (if set) before beginning the installation process.
+
+
+**The following steps are run as root.**
+
+If required, first create a local system user omero-web and create directory::
+
+    useradd -m omero-web
+
+    mkdir -p /opt/omero/web/omero-web/etc/grid
+    chown -R omero-web /opt/omero/web/omero-web
+
+
+
+Installing prerequisites
+------------------------
+
+**The following steps are run as root.**
+
+
+Install dependencies::
+
+    yum -y install epel-release
+
+    yum -y install unzip
+
+    yum -y install python3
+
+    yum -y install nginx
+
+
+Creating a virtual environment
+------------------------------
+
+**The following steps are run as root.**
+
+Create the virtual environment. This is the recommended way to install OMERO.web::
+
+    python3 -mvenv /opt/omero/web/venv3
+
+
+
+Install ZeroC IcePy 3.6::
+
+    /opt/omero/web/venv3/bin/pip install --upgrade https://github.com/ome/zeroc-ice-centos8/releases/download/0.0.1/zeroc_ice-3.6.5-cp36-cp36m-linux_x86_64.whl
+
+
+
+Install OMERO.web::
+
+    /opt/omero/web/venv3/bin/pip install "omero-web>=5.6.1"
+
+Installing OMERO.web apps
+-------------------------
+
+
+A number of apps are available to add functionality to OMERO.web, such as `OMERO.figure <https://www.openmicroscopy.org/omero/figure/>`_ and `OMERO.iviewer <https://www.openmicroscopy.org/omero/iviewer/>`_. See the main website for a `list of released apps <https://www.openmicroscopy.org/omero/apps/>`_. These apps are optional and can be installed, as the **root user**, via :program:`pip` to your OMERO.web virtual environment and configured as the **omero-web system user**, at any time.
+
+
+
+Configuring OMERO.web
+---------------------
+
+**The following steps are run as the omero-web system user.**
+
+For convenience the main OMERO.web configuration options have been defined as environment variables. You can either use your own values, or alternatively use the following ones::
+
+    export OMERODIR=/opt/omero/web/omero-web
+    export WEBPORT=80
+    export WEBSERVER_NAME=localhost
+
+
+Configure OMERO.web and create the NGINX OMERO configuration file::
+
+    export PATH=/opt/omero/web/venv3/bin:$PATH
+
+
+    omero config set omero.web.application_server wsgi-tcp
+    omero web config nginx --http "${WEBPORT}" --servername "${WEBSERVER_NAME}" > /opt/omero/web/omero-web/nginx.conf.tmp
+
+For more customization, please read :ref:`customizing_your_omero_web_installation`.
+
+
+Configuring Gunicorn
+--------------------
+
+**The following steps are run as the omero-web system user.**
+
+ Additional settings can be configured by changing the properties below. Before changing the properties, run ``export PATH=/opt/omero/web/venv3/bin:$PATH``:
+
+    - :property:`omero.web.wsgi_workers` to (2 x NUM_CORES) + 1
+
+      .. note::
+          **Do not** scale the number of workers to the number of clients
+          you expect to have. OMERO.web should only need 4-12 worker
+          processes to handle many requests per second.
+
+    - :property:`omero.web.wsgi_args` Additional arguments. For more details
+      check `Gunicorn Documentation <https://docs.gunicorn.org/en/stable/settings.html>`_.
+
+
+
+Configuring NGINX
+-----------------
+
+**The following steps are run as root.**
+
+Copy the generated configuration file into the NGINX configuration directory, disable the default configuration and start NGINX::
+
+    sed -i.bak -re 's/( default_server.*)/; #\1/' /etc/nginx/nginx.conf
+    if [ -f /etc/nginx/conf.d/default.conf ]; then
+        mv /etc/nginx/conf.d/default.conf /etc/nginx/conf.d/default.disabled
+    fi
+    cp /opt/omero/web/omero-web/nginx.conf.tmp /etc/nginx/conf.d/omeroweb.conf
+
+    systemctl enable nginx
+
+    systemctl start nginx
+
+
+Running OMERO.web
+-----------------
+
+**The following steps are run as root.**
+
+Install `WhiteNoise <http://whitenoise.evans.io/>`_::
+
+    /opt/omero/web/venv3/bin/pip install --upgrade 'whitenoise<4'
+
+
+**The following steps are run as the omero-web system user.**
+
+
+Configure WhiteNoise and start OMERO.web manually to test the installation::
+
+    omero config append -- omero.web.middleware '{"index": 0, "class": "whitenoise.middleware.WhiteNoiseMiddleware"}'
+
+    omero web start
+
+    # Test installation e.g. curl -sL localhost:4080
+
+    omero web stop
+
+
+Automatically running OMERO.web
+-------------------------------
+
+
+**The following steps are run as root.**
+
+
+Copy the `systemd.service` file, then enable and start the service::
+
+    cp omero-web-systemd.service /etc/systemd/system/omero-web.service
+
+    systemctl daemon-reload
+
+    systemctl enable omero-web.service
+
+    systemctl stop omero-web.service
+
+    systemctl start omero-web.service
+
+
+
+Maintenance
+-----------
+
+**The following steps are run as the omero-web system user.**
+
+Please read :ref:`omero_web_maintenance`.
+
+
+SELinux
+-------
+
+**The following steps are run as root.**
+
+If you are running a system with `SELinux enabled <https://wiki.centos.org/HowTos/SELinux>`_ and are unable to access OMERO.web you may need to adjust the security policy::
+
+    if [ $(getenforce) != Disabled ]; then
+
+        yum -y install policycoreutils-python
+        setsebool -P httpd_read_user_content 1
+        setsebool -P httpd_enable_homedirs 1
+        semanage port -a -t http_port_t -p tcp 4080
+
+    fi
+

omero/sysadmins/unix/install-web/web-deployment.rst

@@ -34,6 +34,9 @@ more specific walkthrough listed below.
 :doc:`walkthrough/omeroweb-install-centos7-ice3.6`
   Instructions for installing OMERO.web from scratch on CentOS 7 with Ice 3.6.
 
+:doc:`walkthrough/omeroweb-install-centos8-ice3.6`
+  Instructions for installing OMERO.web from scratch on CentOS 8 with Ice 3.6.
+
 :doc:`walkthrough/omeroweb-install-debian10-ice3.6`
   Instructions for installing OMERO.web from scratch on Debian 10 with Ice 3.6.
 
@@ -57,6 +60,7 @@ more specific walkthrough listed below.
     :hidden:
 
     walkthrough/omeroweb-install-centos7-ice3.6
+    walkthrough/omeroweb-install-centos8-ice3.6
     walkthrough/omeroweb-install-ubuntu1604-ice3.6
     walkthrough/omeroweb-install-ubuntu1804-ice3.6
     walkthrough/omeroweb-install-ubuntu2004-ice3.6

omero/sysadmins/unix/server-centos8-ice36.rst

@@ -0,0 +1,167 @@
+.. walkthroughs are generated using a bash script, see
+.. https://github.com/ome/omero-install
+
+OMERO.server installation on CentOS 8
+=====================================
+
+This is an example walkthrough for installing OMERO on CentOS 8, using
+a dedicated local system user, and should be read in conjunction with
+:doc:`install-web`. You can use this as a guide
+for setting up your own test server. For production use you should also read
+the pages listed under :ref:`index-optimizing-server`.
+This guide will install Python 3.6.
+Since 5.6, a new :envvar:`OMERODIR` variable is used, you should first unset :envvar:`OMERO_HOME`
+(if set) before beginning the installation process.
+
+This guide describes how to install using the **recommended** versions for
+Java, Ice, PostgreSQL.
+This should be read in conjunction with :doc:`../version-requirements`.
+
+This guide **does not** describe how to install OMERO.web.
+To deploy OMERO.web, please read
+:doc:`install-web/walkthrough/omeroweb-install-centos8-ice3.6`.
+
+These instructions assume your Linux distribution is configured with a UTF-8
+locale (this is normally the default).
+
+For convenience in this walkthrough, we will use the **omero-server system user** and the main OMERO configuration options have
+been defined as environment variables. When following this walkthrough you can
+either use your own values, or alternatively create :file:`settings.env` for example under ``/tmp`` e.g. ``/tmp/settings.env`` containing the variables below and source it when required:
+
+.. literalinclude:: walkthrough/settings.env
+   :start-after: Substitute
+
+Installing prerequisites
+------------------------
+
+**The following steps are run as root.**
+
+Install Java |javaversion|, Ice |iceversion| and PostgreSQL |postgresversion|:
+
+To install Java |javaversion| and other dependencies:
+
+.. literalinclude:: walkthrough/walkthrough_centos8.sh
+    :start-after: #start-step01
+    :end-before: #end-step01
+
+To install Ice |iceversion|:
+
+.. literalinclude:: walkthrough/walkthrough_centos8.sh
+    :start-after: #start-recommended-ice
+    :end-before: #end-recommended-ice
+
+To install PostgreSQL |postgresversion|:
+
+.. literalinclude:: walkthrough/walkthrough_centos8.sh
+    :start-after: # install Postgres
+    :end-before: #end-step01
+
+.. Note:: if you are installing PostgreSQL in a Docker container, some of the commands above will not work. For more details check `step01_centos8_pg_deps.sh 
+ <https://github.com/ome/omero-install/blob/develop/linux/step01_centos8_pg_deps.sh>`_
+
+Create a local omero-server system user, and a directory for the OMERO repository:
+
+.. literalinclude:: walkthrough/walkthrough_centos8.sh
+    :start-after: #start-step02
+    :end-before: #end-step02
+
+Make the :file:`settings.env` available to the omero-server system user by copying in to the user home directory. The file will need to be sourced each time you switch user. You could add ``. ~/settings.env`` to the omero-server system user ``bash`` profile.
+
+Create a database user and initialize a new database for OMERO:
+
+.. literalinclude:: walkthrough/walkthrough_centos8.sh
+    :start-after: #start-step03
+    :end-before: #end-step03
+
+Installing OMERO.server
+-----------------------
+
+**The following step is run as root.**
+
+We recommend to create a virtual environment and install the Ice Python binding and PyTables_ using ``pip``:
+
+.. literalinclude:: walkthrough/walkthrough_centos8.sh
+    :start-after: #start-step03bis
+    :end-before: #end-step03bis
+
+Install ``omero-py``:
+
+.. literalinclude:: walkthrough/walkthrough_centos8.sh
+    :start-after: #start-step04-pre
+    :end-before: #start-release-ice36
+
+Download and unzip OMERO.server:
+
+.. literalinclude:: walkthrough/walkthrough_centos8.sh
+    :start-after: #start-release-ice36
+    :end-before: #end-release-ice36
+
+Change the ownership of the OMERO.server directory and create a symlink:
+
+.. literalinclude:: walkthrough/walkthrough_centos8.sh
+    :start-after: #end-release-ice36
+    :end-before: #end-step04-pre
+
+**The following steps are run as the omero-server system user.** (``su - omero-server``)
+
+The variable ``OMERODIR`` set in :download:`settings.env <walkthrough/settings.env>` above **must** point to the location where OMERO.server is installed.
+e.g. ``OMERODIR=/path_to_omero_server/OMERO.server``.
+
+Note that this script requires the same environment variables that were set
+earlier in `settings.env`, so you may need to copy and/or source this file as
+the omero user.
+
+Configure the server:
+
+.. literalinclude:: walkthrough/walkthrough_centos8.sh
+    :start-after: #end-copy-omeroscript
+    :end-before: #end-step04
+
+Patching OMERO.server
+---------------------
+
+Weaker ciphers like ADH are disabled by default in OpenSSL 1.1.0,
+the version installed on Debian 10.
+This means that it is not possible to connect to an OMERO.server
+using any OMERO clients e.g. the Java Desktop client,
+the OMERO.web client or the CLI.
+The parameter ``@SECLEVEL=0``, enabling the weaker ciphers, needs to be
+set in order to allow connection.
+
+.. literalinclude:: walkthrough/walkthrough_centos8.sh
+    :start-after: #start-seclevel
+    :end-before: #end-seclevel
+
+Running OMERO.server
+--------------------
+
+**The following steps are run as the omero-server system user.** (``su - omero-server``)
+
+OMERO should now be set up. To start the server run::
+
+    omero admin start
+
+Should you wish to start OMERO automatically, a `systemd service file` could be created.
+An example :download:`omero-server-systemd.service <walkthrough/omero-server-systemd.service>`
+is available.
+
+Copy the ``systemd.service`` file and configure the service:
+
+.. literalinclude:: walkthrough/walkthrough_centos8.sh
+    :start-after: #start-step06
+    :end-before: #end-step06
+
+You can then start up the service.
+
+Securing OMERO
+--------------
+
+**The following steps are run as root.**
+
+If multiple users have access to the machine running OMERO you should restrict
+access to OMERO.server's configuration and runtime directories, and optionally
+the OMERO data directory:
+
+.. literalinclude:: walkthrough/walkthrough_centos8.sh
+    :start-after: #start-step07
+    :end-before: #end-step07