From 4e507b04964d6331d22dad83a844be463ca3c773 Mon Sep 17 00:00:00 2001 From: Jean-Marie Burel Date: Mon, 6 Nov 2023 14:19:34 +0000 Subject: [PATCH 01/14] add ubuntu2204 walkthrough --- .../unix/server-ubuntu2204-ice36.rst | 164 ++++++++++++++++++ 1 file changed, 164 insertions(+) create mode 100644 omero/sysadmins/unix/server-ubuntu2204-ice36.rst diff --git a/omero/sysadmins/unix/server-ubuntu2204-ice36.rst b/omero/sysadmins/unix/server-ubuntu2204-ice36.rst new file mode 100644 index 0000000000..6562aa7069 --- /dev/null +++ b/omero/sysadmins/unix/server-ubuntu2204-ice36.rst @@ -0,0 +1,164 @@ +.. walkthroughs are generated using a bash script, see +.. https://github.com/ome/omero-install + +OMERO.server installation on Ubuntu 22.04 +========================================= + +This is an example walkthrough for installing OMERO on Ubuntu 22.04, using +a dedicated local system user. 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.10. +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-ubuntu2204-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_recommended|, Ice |iceversion| and PostgreSQL: + +To install Java |javaversion_recommended| and other dependencies: + +.. literalinclude:: walkthrough/walkthrough_ubuntu2204.sh + :start-after: #start-step01 + :end-before: #end-step01 + +To install Ice |iceversion|: + +.. literalinclude:: walkthrough/walkthrough_ubuntu2204.sh + :start-after: #start-recommended-ice + :end-before: #end-recommended-ice + +To make Ice available to all users and activate the virtual environment, set the following in ``/etc/profile``: + +.. literalinclude:: walkthrough/omero-ice36.env + +and add the virtual environment to ``PATH``: + +.. literalinclude:: walkthrough/settings.env + :start-after: # Location of the virtual environment + +To install PostgreSQL: + +.. literalinclude:: walkthrough/walkthrough_ubuntu2204.sh + :start-after: # install Postgres + :end-before: #end-step01 + +Create a local omero-server system user, and a directory for the OMERO repository: + +.. literalinclude:: walkthrough/walkthrough_ubuntu2204.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_ubuntu2204.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 the dependencies required by the server using ``pip``: + +.. literalinclude:: walkthrough/walkthrough_ubuntu2204.sh + :start-after: #start-step03bis + :end-before: #end-step03bis + +Download and unzip OMERO.server: + +.. literalinclude:: walkthrough/walkthrough_ubuntu2204.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_ubuntu2204.sh + :start-after: #end-release-ice36 + :end-before: #end-step04-pre + +Configuring OMERO.server +------------------------ + +**The following steps are run as the omero-server system user.** (``su - omero-server``) + +The variable ``OMERODIR`` set in :download:`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 database and the location of the data directory: + +.. literalinclude:: walkthrough/walkthrough_ubuntu2204.sh + :start-after: #end-copy-omeroscript + :end-before: #end-step04 + +.. include:: ciphers + +.. literalinclude:: walkthrough/walkthrough_ubuntu2204.sh + :start-after: #start-seclevel + :end-before: #end-seclevel + +See also :doc:`../client-server-ssl`. + +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 `init.d` file could be created. +An example :download:`omero-server-init.d ` +is available. + +Copy the ``init.d`` file and configure the service: + +.. literalinclude:: walkthrough/walkthrough_ubuntu2204.sh + :start-after: #start-step06 + :end-before: #end-step06 + +You can then start up the service by running:: + + service omero-server start + +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_ubuntu2204.sh + :start-after: #start-step07 + :end-before: #end-step07 From 1ac9061c9c4e36d1d02d6754db495ae320bc32b2 Mon Sep 17 00:00:00 2001 From: Jean-Marie Burel Date: Mon, 6 Nov 2023 14:23:19 +0000 Subject: [PATCH 02/14] reference 22.04 walkthrough --- omero/sysadmins/unix/server-installation.rst | 7 ++++--- 1 file changed, 4 insertions(+), 3 deletions(-) diff --git a/omero/sysadmins/unix/server-installation.rst b/omero/sysadmins/unix/server-installation.rst index d55bcee675..25ba94ee60 100644 --- a/omero/sysadmins/unix/server-installation.rst +++ b/omero/sysadmins/unix/server-installation.rst @@ -28,13 +28,13 @@ Since 5.6, a new :envvar:`OMERODIR` variable is used, you should first unset :en Instructions for installing OMERO.server from scratch on Ubuntu 18.04 with Ice 3.6 and Python 3.6. - -**Upcoming:** - :doc:`server-ubuntu2004-ice36` Instructions for installing OMERO.server from scratch on Ubuntu 20.04 with Ice 3.6 and Python 3.8. +:doc:`server-ubuntu2204-ice36` + Instructions for installing OMERO.server from scratch on + Ubuntu 22.04 with Ice 3.6 and Python 3.10. **Development:** @@ -51,6 +51,7 @@ Since 5.6, a new :envvar:`OMERODIR` variable is used, you should first unset :en server-centos7-ice36 server-ubuntu1804-ice36 server-ubuntu2004-ice36 + server-ubuntu2204-ice36 server-debian10-ice36 server-install-homebrew From 13643e3566b3c96ae2ea981798ffd1bdf6ed4d0a Mon Sep 17 00:00:00 2001 From: jburel Date: Tue, 7 Nov 2023 00:53:49 +0000 Subject: [PATCH 03/14] Changes from upstream repositories: openmicroscopy --- .../omeroweb-install-rockylinux9-ice3.6.rst | 394 ++++++++++++++++ .../omeroweb-install-ubuntu2204-ice3.6.rst | 445 ++++++++++++++++++ 2 files changed, 839 insertions(+) create mode 100644 omero/sysadmins/unix/install-web/walkthrough/omeroweb-install-rockylinux9-ice3.6.rst create mode 100644 omero/sysadmins/unix/install-web/walkthrough/omeroweb-install-ubuntu2204-ice3.6.rst diff --git a/omero/sysadmins/unix/install-web/walkthrough/omeroweb-install-rockylinux9-ice3.6.rst b/omero/sysadmins/unix/install-web/walkthrough/omeroweb-install-rockylinux9-ice3.6.rst new file mode 100644 index 0000000000..0f3a917038 --- /dev/null +++ b/omero/sysadmins/unix/install-web/walkthrough/omeroweb-install-rockylinux9-ice3.6.rst @@ -0,0 +1,394 @@ +.. walkthroughs are generated using ansible, see +.. https://github.com/ome/omeroweb-install + +OMERO.web installation on Rocky Linux 9 and IcePy 3.6 +================================================ + +Please first read :doc:`../../server-rockylinux9-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. By default, Python 3.9 is installed. + + +**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:: + + cp nginx.repo /etc/yum.repos.d/ + + dnf -y install unzip + + dnf -y install python3 + + dnf -y install nginx + + +*Optional*: if you wish to use the Redis cache, install Redis:: + + dnf -y install redis + + systemctl enable redis.service + + systemctl start redis.service + + +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 https://github.com/glencoesoftware/zeroc-ice-py-rhel9-x86_64/releases/download/20230830/zeroc_ice-3.6.5-cp39-cp39-linux_x86_64.whl + + +Upgrade pip and install OMERO.web:: + + + /opt/omero/web/venv3/bin/pip install --upgrade pip + /opt/omero/web/venv3/bin/pip install omero-web + +Installing OMERO.web apps +------------------------- + + +A number of apps are available to add functionality to OMERO.web, such as `OMERO.figure `_ and `OMERO.iviewer `_. See the main website for a `list of released 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 WEBSESSION=True + export OMERODIR=/opt/omero/web/omero-web + + +Configure OMERO.web and create the NGINX OMERO configuration file to be included in a system-wide NGINX configuration by redirecting the output of the command ``omero web config nginx`` below into a file. If an attempt is made to access OMERO.web whilst it is not running, the generated NGINX configuration file will automatically display a maintenance page:: + + export PATH=/opt/omero/web/venv3/bin:$PATH + + + omero web config nginx --http "${WEBPORT}" --servername "${WEBSERVER_NAME}" > /opt/omero/web/omero-web/nginx.conf.tmp + +OMERO.web offers a number of configuration options. The configuration changes **will not be applied** until Gunicorn is restarted using ``omero web restart``. The Gunicorn workers are managed **separately** from other OMERO processes. You can check their status or stop them using ``omero web status`` or ``omero web stop``. + + - Session engine: + + - OMERO.web offers alternative session backends to automatically delete stale data using the cache session store backend, see :djangodoc:`Django cached session documentation ` for more details. + + - `Redis `_ requires `django-redis `_ in order to be used with OMERO.web. We assume that Redis has already been installed. To configure the cache, run:: + + omero config set omero.web.caches '{"default": {"BACKEND": "django_redis.cache. + RedisCache", "LOCATION": "redis://127.0.0.1:6379/0"}}' + + - After installing all the cache prerequisites set the following:: + + omero config set omero.web.session_engine django.contrib.sessions.backends.cache + + + - Use a prefix: + + By default OMERO.web expects to be run from the root URL of the webserver. + This can be changed by setting :property:`omero.web.prefix` and + :property:`omero.web.static_url`. For example, to make OMERO.web appear at + `http://example.org/omero/`:: + + omero config set omero.web.prefix '/omero' + omero config set omero.web.static_url '/omero/static/' + + and regenerate your webserver configuration. + + All configuration options can be found on various sections of + :ref:`web_index` developers documentation. For the full list, refer to + :ref:`web_configuration` properties. + + The most popular configuration options include: + + - Debug mode, see :property:`omero.web.debug`. + + - Customizing OMERO clients e.g. to add your own logo to the login page + (:property:`omero.web.login_logo`) or use an index page as an alternative + landing page for users (:property:`omero.web.index_template`). See + :doc:`/sysadmins/customization` for further information. + + - Enabling a public user see :doc:`/sysadmins/public`. + + +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 `_. For example to enable **debugging**, run the following command:: + + omero config set omero.web.wsgi_args -- "--log-level=DEBUG --error-logfile=/opt/omero/web/omero-web/var/log/error.log" + + + +Setting up CORS +--------------- + + +**The following steps are run as root.** + +Cross Origin Resource Sharing allows web applications hosted at other origins to access resources from your OMERO.web installation. This can be achieved using the `django-cors-headers `_ app with additional configuration of OMERO.web. See the `django-cors-headers `_ page for more details on the settings. + Since OMERO.web 5.14.0, the package `django-cors-headers` is installed by default. + + + +**The following steps are run as the omero-web system user.** + +Configure CORS. An ``index`` is used to specify the ordering of middleware classes. It is important to add the ``CorsMiddleware`` as the first class and ``CorsPostCsrfMiddleware`` as the last. You can specify allowed origins in a whitelist, or allow all, for example:: + + omero config append omero.web.middleware '{"index": 0.5, "class": "corsheaders.middleware.CorsMiddleware"}' + omero config append omero.web.middleware '{"index": 10, "class": "corsheaders.middleware.CorsPostCsrfMiddleware"}' + omero config set omero.web.cors_origin_whitelist '["https://hostname.example.com"]' + # or to allow all + omero config set omero.web.cors_origin_allow_all True + +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:: + + # Disable default server config + # Newer nginx versions: + if [ -f /etc/nginx/conf.d/default.conf ]; then + mv /etc/nginx/conf.d/default.conf /etc/nginx/conf.d/default.disabled + fi + # Older nginx versions: + sed -i.bak -re 's/( default_server.*)/; #\1/' /etc/nginx/nginx.conf + sed -i "/^\s\s\s\sserver/, /^\s\s\s\s}/ s|^|#|" /etc/nginx/nginx.conf + + cp /opt/omero/web/omero-web/nginx.conf.tmp /etc/nginx/conf.d/omeroweb.conf + + systemctl enable nginx + + systemctl start nginx + + +For production servers you may need to add additional directives to the configuration file, for example to enable `HTTPS `_. As an alternative to manually modifying the generated file you can generate a minimal configuration and include this in your own manually created NGINX file, such as :file:`/etc/nginx/conf.d/omero-web.conf`: + + :: + + omero web config nginx-location > /opt/omero/web/omero-web/omero-web-location.include + + +This requires more initial work but in the future you can automatically regenerate your OMERO.web configuration and your additional configuration settings will still apply. + + .. note:: + If you need help configuring your firewall rules, see the + :doc:`/sysadmins/server-security` page. + + + +Running OMERO.web +----------------- + + +Since OMERO.web 5.16.0, the package `whitenoise` is installed by default. + + +*Optional*: Install `Django Redis `_:: + + /opt/omero/web/venv3/bin/pip install 'django-redis==5.0.0' + +**The following steps are run as the omero-web system user.** + +*Optional*: Configure the cache:: + + omero config set omero.web.caches '{"default": {"BACKEND": "django_redis.cache.RedisCache","LOCATION": "redis://127.0.0.1:6379/0"}}' + omero config set omero.web.session_engine 'django.contrib.sessions.backends.cache' + +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 + + + +Maintaining OMERO.web +--------------------- + +**The following steps are run as the omero-web system user.** + +You can manage the sessions using the following configuration options and commands: + + - Session cookies :property:`omero.web.session_expire_at_browser_close`: + + - A boolean that determines whether to expire the session when the user + closes their browser. + See :djangodoc:`Django Browser-length sessions vs. persistent + sessions documentation ` + for more details. The default value is ``True``:: + + omero config set omero.web.session_expire_at_browser_close "True" + + - The age of session cookies, in seconds. The default value is ``86400``:: + + omero config set omero.web.session_cookie_age 86400 + + - Clear session: + + Each session for a logged-in user in OMERO.web is kept in the session + store. Stale sessions can cause the store to grow with time. OMERO.web + uses by default the OS file system as the session store backend and + does not automatically purge stale sessions, see + :djangodoc:`Django file-based session documentation ` for more details. It is therefore the responsibility of the OMERO + administrator to purge the session cache using the provided management command:: + + omero web clearsessions + + It is recommended to call this command on a regular basis, for example + as a :download:`daily cron job <../../omero-web-cron>`, see + :djangodoc:`Django clearing the session store documentation ` for more information. + + + +Troubleshooting +--------------- + +**The following steps are run as the omero-web system user.** + +In order to identify why OMERO.web is not available run ``omero web status``. Then consult NGINX :file:`error.log` and :file:`/opt/omero/web/omero-web/var/log/OMEROweb.log`. + + +Configuring Gunicorn advanced options +------------------------------------- + +OMERO.web deployment can be configured with sync and async workers. **Sync workers** are faster and recommended for a data repository with :ref:`download_restrictions`. If you wish to offer users the ability to download data then you have to use **async workers**. OMERO.web is able to handle multiple clients on a single worker thread switching context as necessary while streaming binary data from OMERO.server. Depending on the traffic and scale of the repository you should configure connections and speed limits on your server to avoid blocking resources. We recommend you run benchmark and performance tests. It is also possible to apply :ref:`download_restrictions` and offer alternative access to binary data. + + .. note:: + Handling streaming request/responses requires proxy buffering + to be turned off. For more details refer to + `Gunicorn deployment `_ + and + `NGINX configuration `_. + + .. note:: + :property:`omero.web.application_server.max_requests` should be set to 0 + + + See + `Gunicorn design `_ for more details. + + + +Experimental: Sync workers +~~~~~~~~~~~~~~~~~~~~~~~~~~ + +**The following steps are run as root.** + +Install :pypi:`futures`:: + + /opt/omero/web/venv3/bin/pip install futures + +**The following steps are run as the omero-web system user.** + +To find out more about the number of worker threads for handling requests, see `Gunicorn threads `_. Additional settings can be configured by changing the following properties:: + + omero config set omero.web.wsgi_worker_class + omero config set omero.web.wsgi_threads $(2-4 x NUM_CORES) + + + +Experimental: Async workers +~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +**The following steps are run as root.** + +Install `Gevent >= 0.13 `_:: + + /opt/omero/web/venv3/bin/pip install 'gevent>=0.13' + + + +**The following steps are run as the omero-web system user.** + +To find out more about the maximum number of simultaneous clients, see `Gunicorn worker-connections `_. Additional settings can be configured by changing the following properties:: + + omero config set omero.web.wsgi_worker_class gevent + omero config set omero.web.wsgi_worker_connections 1000 + omero config set omero.web.application_server.max_requests 0 + + + +SELinux +------- + +**The following steps are run as root.** + + +If you are running a system with `SELinux enabled `_ and are unable to access OMERO.web you may need to adjust the security policy:: + + if [ $(getenforce) != Disabled ]; then + dnf -y install policycoreutils-python-utils + setsebool -P httpd_read_user_content 1 + setsebool -P httpd_enable_homedirs 1 + semanage port -a -t http_port_t -p tcp 4080 + firewall-cmd --zone=public --add-port=4080/tcp --permanent + firewall-cmd --reload + fi + diff --git a/omero/sysadmins/unix/install-web/walkthrough/omeroweb-install-ubuntu2204-ice3.6.rst b/omero/sysadmins/unix/install-web/walkthrough/omeroweb-install-ubuntu2204-ice3.6.rst new file mode 100644 index 0000000000..cd1d0cf3ba --- /dev/null +++ b/omero/sysadmins/unix/install-web/walkthrough/omeroweb-install-ubuntu2204-ice3.6.rst @@ -0,0 +1,445 @@ +.. walkthroughs are generated using ansible, see +.. https://github.com/ome/omeroweb-install + +OMERO.web installation on Ubuntu 22.04 and IcePy 3.6 +==================================================== + +Please first read :doc:`../../server-ubuntu2204-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. By default, Python 3.10 is installed. + + +**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:: + + apt-get update + + apt-get -y install unzip + apt-get -y install python3 + apt-get -y install python3-venv + + apt-get -y install nginx + + +*Optional*: if you wish to use the Redis cache, install Redis:: + + apt-get -y install redis-server + + service redis-server start + + +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 https://github.com/glencoesoftware/zeroc-ice-py-ubuntu2204-x86_64/releases/download/20221004/zeroc_ice-3.6.5-cp310-cp310-linux_x86_64.whl + + +Upgrade pip and install OMERO.web:: + + + /opt/omero/web/venv3/bin/pip install --upgrade pip + /opt/omero/web/venv3/bin/pip install omero-web + +Installing OMERO.web apps +------------------------- + + +A number of apps are available to add functionality to OMERO.web, such as `OMERO.figure `_ and `OMERO.iviewer `_. See the main website for a `list of released 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 WEBSESSION=True + export OMERODIR=/opt/omero/web/omero-web + + +Configure OMERO.web and create the NGINX OMERO configuration file to be included in a system-wide NGINX configuration by redirecting the output of the command ``omero web config nginx`` below into a file. If an attempt is made to access OMERO.web whilst it is not running, the generated NGINX configuration file will automatically display a maintenance page:: + + export PATH=/opt/omero/web/venv3/bin:$PATH + + + omero web config nginx --http "${WEBPORT}" --servername "${WEBSERVER_NAME}" > /opt/omero/web/omero-web/nginx.conf.tmp + +OMERO.web offers a number of configuration options. The configuration changes **will not be applied** until Gunicorn is restarted using ``omero web restart``. The Gunicorn workers are managed **separately** from other OMERO processes. You can check their status or stop them using ``omero web status`` or ``omero web stop``. + + - Session engine: + + - OMERO.web offers alternative session backends to automatically delete stale data using the cache session store backend, see :djangodoc:`Django cached session documentation ` for more details. + + - `Redis `_ requires `django-redis `_ in order to be used with OMERO.web. We assume that Redis has already been installed. To configure the cache, run:: + + omero config set omero.web.caches '{"default": {"BACKEND": "django_redis.cache. + RedisCache", "LOCATION": "redis://127.0.0.1:6379/0"}}' + + - After installing all the cache prerequisites set the following:: + + omero config set omero.web.session_engine django.contrib.sessions.backends.cache + + + - Use a prefix: + + By default OMERO.web expects to be run from the root URL of the webserver. + This can be changed by setting :property:`omero.web.prefix` and + :property:`omero.web.static_url`. For example, to make OMERO.web appear at + `http://example.org/omero/`:: + + omero config set omero.web.prefix '/omero' + omero config set omero.web.static_url '/omero/static/' + + and regenerate your webserver configuration. + + All configuration options can be found on various sections of + :ref:`web_index` developers documentation. For the full list, refer to + :ref:`web_configuration` properties. + + The most popular configuration options include: + + - Debug mode, see :property:`omero.web.debug`. + + - Customizing OMERO clients e.g. to add your own logo to the login page + (:property:`omero.web.login_logo`) or use an index page as an alternative + landing page for users (:property:`omero.web.index_template`). See + :doc:`/sysadmins/customization` for further information. + + - Enabling a public user see :doc:`/sysadmins/public`. + + +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 `_. For example to enable **debugging**, run the following command:: + + omero config set omero.web.wsgi_args -- "--log-level=DEBUG --error-logfile=/opt/omero/web/omero-web/var/log/error.log" + + + +Setting up CORS +--------------- + + +**The following steps are run as root.** + +Cross Origin Resource Sharing allows web applications hosted at other origins to access resources from your OMERO.web installation. This can be achieved using the `django-cors-headers `_ app with additional configuration of OMERO.web. See the `django-cors-headers `_ page for more details on the settings. + Since OMERO.web 5.14.0, the package `django-cors-headers` is installed by default. + + + +**The following steps are run as the omero-web system user.** + +Configure CORS. An ``index`` is used to specify the ordering of middleware classes. It is important to add the ``CorsMiddleware`` as the first class and ``CorsPostCsrfMiddleware`` as the last. You can specify allowed origins in a whitelist, or allow all, for example:: + + omero config append omero.web.middleware '{"index": 0.5, "class": "corsheaders.middleware.CorsMiddleware"}' + omero config append omero.web.middleware '{"index": 10, "class": "corsheaders.middleware.CorsPostCsrfMiddleware"}' + omero config set omero.web.cors_origin_whitelist '["https://hostname.example.com"]' + # or to allow all + omero config set omero.web.cors_origin_allow_all True + +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 + rm /etc/nginx/sites-enabled/default + cp /opt/omero/web/omero-web/nginx.conf.tmp /etc/nginx/conf.d/omeroweb.conf + + service nginx start + + +For production servers you may need to add additional directives to the configuration file, for example to enable `HTTPS `_. As an alternative to manually modifying the generated file you can generate a minimal configuration and include this in your own manually created NGINX file, such as :file:`/etc/nginx/conf.d/omero-web.conf`: + + :: + + omero web config nginx-location > /opt/omero/web/omero-web/omero-web-location.include + + +This requires more initial work but in the future you can automatically regenerate your OMERO.web configuration and your additional configuration settings will still apply. + + .. note:: + If you need help configuring your firewall rules, see the + :doc:`/sysadmins/server-security` page. + + + +Running OMERO.web +----------------- + + +Since OMERO.web 5.16.0, the package `whitenoise` is installed by default. + + +*Optional*: Install `Django Redis `_:: + + /opt/omero/web/venv3/bin/pip install 'django-redis==5.0.0' + +**The following steps are run as the omero-web system user.** + +*Optional*: Configure the cache:: + + omero config set omero.web.caches '{"default": {"BACKEND": "django_redis.cache.RedisCache","LOCATION": "redis://127.0.0.1:6379/0"}}' + omero config set omero.web.session_engine 'django.contrib.sessions.backends.cache' + +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.** + +Should you wish to run OMERO.web automatically, a `init.d` file could be created. See below an example file `omero-web-init.d`:: + + #!/bin/bash + # + # /etc/init.d/omero-web + # Subsystem file for "omero" web + # + ### BEGIN INIT INFO + # Provides: omero-web + # Required-Start: $local_fs $remote_fs $network $time omero + # Required-Stop: $local_fs $remote_fs $network $time omero + # Default-Start: 2 3 4 5 + # Default-Stop: 0 1 6 + # Short-Description: OMERO.web + ### END INIT INFO + # + ### Redhat + # chkconfig: - 98 02 + # description: init file for OMERO.web + ### + + RETVAL=0 + prog=omero-web + + # Read configuration variable file if it is present + [ -r /etc/default/$prog ] && . /etc/default/$prog + + OMERO_USER=${OMERO_USER:-omero-web} + OMERO=/opt/omero/web/venv3/bin/omero + OMERODIR=/opt/omero/web/omero-web + VENVDIR=${VENVDIR:-/opt/omero/web/venv3} + + start() { + echo -n $"Starting $prog:" + su - ${OMERO_USER} -c ". ${VENVDIR}/bin/activate;OMERODIR=${OMERODIR} ${OMERO} web start" &> /dev/null && echo -n ' OMERO.web' + sleep 5 + RETVAL=$? + [ "$RETVAL" = 0 ] + echo + } + + stop() { + echo -n $"Stopping $prog:" + su - ${OMERO_USER} -c ". ${VENVDIR}/bin/activate;OMERODIR=${OMERODIR} ${OMERO} web stop" &> /dev/null && echo -n ' OMERO.web' + RETVAL=$? + [ "$RETVAL" = 0 ] + echo + } + + status() { + echo -n $"Status $prog:" + su - ${OMERO_USER} -c ". ${VENVDIR}/bin/activate;OMERODIR=${OMERODIR} ${OMERO} web status" + RETVAL=$? + } + + case "$1" in + start) + start + ;; + stop) + stop + ;; + restart) + stop + start + ;; + status) + status + ;; + *) + echo $"Usage: $0 {start|stop|restart|status}" + RETVAL=1 + esac + exit $RETVAL + +Copy the `init.d` file, then configure the service:: + + cp omero-web-init.d /etc/init.d/omero-web + chmod a+x /etc/init.d/omero-web + + update-rc.d -f omero-web remove + update-rc.d -f omero-web defaults 98 02 + + + +Start up services:: + + service redis-server start + + cron + service nginx start + service omero-web restart + + +Maintaining OMERO.web +--------------------- + +**The following steps are run as the omero-web system user.** + +You can manage the sessions using the following configuration options and commands: + + - Session cookies :property:`omero.web.session_expire_at_browser_close`: + + - A boolean that determines whether to expire the session when the user + closes their browser. + See :djangodoc:`Django Browser-length sessions vs. persistent + sessions documentation ` + for more details. The default value is ``True``:: + + omero config set omero.web.session_expire_at_browser_close "True" + + - The age of session cookies, in seconds. The default value is ``86400``:: + + omero config set omero.web.session_cookie_age 86400 + + - Clear session: + + Each session for a logged-in user in OMERO.web is kept in the session + store. Stale sessions can cause the store to grow with time. OMERO.web + uses by default the OS file system as the session store backend and + does not automatically purge stale sessions, see + :djangodoc:`Django file-based session documentation ` for more details. It is therefore the responsibility of the OMERO + administrator to purge the session cache using the provided management command:: + + omero web clearsessions + + It is recommended to call this command on a regular basis, for example + as a :download:`daily cron job <../../omero-web-cron>`, see + :djangodoc:`Django clearing the session store documentation ` for more information. + + + +Troubleshooting +--------------- + +**The following steps are run as the omero-web system user.** + +In order to identify why OMERO.web is not available run ``omero web status``. Then consult NGINX :file:`error.log` and :file:`/opt/omero/web/omero-web/var/log/OMEROweb.log`. + + +Configuring Gunicorn advanced options +------------------------------------- + +OMERO.web deployment can be configured with sync and async workers. **Sync workers** are faster and recommended for a data repository with :ref:`download_restrictions`. If you wish to offer users the ability to download data then you have to use **async workers**. OMERO.web is able to handle multiple clients on a single worker thread switching context as necessary while streaming binary data from OMERO.server. Depending on the traffic and scale of the repository you should configure connections and speed limits on your server to avoid blocking resources. We recommend you run benchmark and performance tests. It is also possible to apply :ref:`download_restrictions` and offer alternative access to binary data. + + .. note:: + Handling streaming request/responses requires proxy buffering + to be turned off. For more details refer to + `Gunicorn deployment `_ + and + `NGINX configuration `_. + + .. note:: + :property:`omero.web.application_server.max_requests` should be set to 0 + + + See + `Gunicorn design `_ for more details. + + + +Experimental: Sync workers +~~~~~~~~~~~~~~~~~~~~~~~~~~ + +**The following steps are run as root.** + +Install :pypi:`futures`:: + + /opt/omero/web/venv3/bin/pip install futures + +**The following steps are run as the omero-web system user.** + +To find out more about the number of worker threads for handling requests, see `Gunicorn threads `_. Additional settings can be configured by changing the following properties:: + + omero config set omero.web.wsgi_worker_class + omero config set omero.web.wsgi_threads $(2-4 x NUM_CORES) + + + +Experimental: Async workers +~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +**The following steps are run as root.** + +Install `Gevent >= 0.13 `_:: + + /opt/omero/web/venv3/bin/pip install 'gevent>=0.13' + + + +**The following steps are run as the omero-web system user.** + +To find out more about the maximum number of simultaneous clients, see `Gunicorn worker-connections `_. Additional settings can be configured by changing the following properties:: + + omero config set omero.web.wsgi_worker_class gevent + omero config set omero.web.wsgi_worker_connections 1000 + omero config set omero.web.application_server.max_requests 0 + + + From d2d44fb30c1e507c539a540843ac08346c71d36d Mon Sep 17 00:00:00 2001 From: Jean-Marie Burel Date: Tue, 7 Nov 2023 09:57:04 +0000 Subject: [PATCH 04/14] add rockylinux9 file --- omero/sysadmins/unix/server-rockylinux9-ice36.rst | 5 +++++ 1 file changed, 5 insertions(+) create mode 100644 omero/sysadmins/unix/server-rockylinux9-ice36.rst diff --git a/omero/sysadmins/unix/server-rockylinux9-ice36.rst b/omero/sysadmins/unix/server-rockylinux9-ice36.rst new file mode 100644 index 0000000000..e8e1b5feb3 --- /dev/null +++ b/omero/sysadmins/unix/server-rockylinux9-ice36.rst @@ -0,0 +1,5 @@ +.. walkthroughs are generated using a bash script, see +.. https://github.com/ome/omero-install + +OMERO.server installation on RHEL 9/RockyLinux 9 +================================================ \ No newline at end of file From 8a6d6399dbe0129e6b96352226b9dfa2bfc306af Mon Sep 17 00:00:00 2001 From: Jean-Marie Burel Date: Tue, 7 Nov 2023 09:57:14 +0000 Subject: [PATCH 05/14] add links --- omero/sysadmins/unix/install-web/web-deployment.rst | 2 ++ omero/sysadmins/unix/server-installation.rst | 1 + 2 files changed, 3 insertions(+) diff --git a/omero/sysadmins/unix/install-web/web-deployment.rst b/omero/sysadmins/unix/install-web/web-deployment.rst index f93499468b..f0c4c88cd4 100644 --- a/omero/sysadmins/unix/install-web/web-deployment.rst +++ b/omero/sysadmins/unix/install-web/web-deployment.rst @@ -63,8 +63,10 @@ Walkthroughs :hidden: walkthrough/omeroweb-install-centos7-ice3.6 + walkthrough/omeroweb-install-rockylinux9-ice3.6 walkthrough/omeroweb-install-ubuntu1804-ice3.6 walkthrough/omeroweb-install-ubuntu2004-ice3.6 + walkthrough/omeroweb-install-ubuntu2204-ice3.6 walkthrough/omeroweb-install-debian10-ice3.6 .. note:: Support for Apache deployment has been dropped in 5.3.0. diff --git a/omero/sysadmins/unix/server-installation.rst b/omero/sysadmins/unix/server-installation.rst index 25ba94ee60..f2da21689e 100644 --- a/omero/sysadmins/unix/server-installation.rst +++ b/omero/sysadmins/unix/server-installation.rst @@ -49,6 +49,7 @@ Since 5.6, a new :envvar:`OMERODIR` variable is used, you should first unset :en :hidden: server-centos7-ice36 + server-rockylinux9-ice36 server-ubuntu1804-ice36 server-ubuntu2004-ice36 server-ubuntu2204-ice36 From 1c916d62277059988d08a562f64f4b8ea32dacc0 Mon Sep 17 00:00:00 2001 From: Jean-Marie Burel Date: Tue, 7 Nov 2023 10:54:14 +0000 Subject: [PATCH 06/14] add postgresql version --- omero/sysadmins/unix/server-ubuntu2204-ice36.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/omero/sysadmins/unix/server-ubuntu2204-ice36.rst b/omero/sysadmins/unix/server-ubuntu2204-ice36.rst index 6562aa7069..0307c1dd41 100644 --- a/omero/sysadmins/unix/server-ubuntu2204-ice36.rst +++ b/omero/sysadmins/unix/server-ubuntu2204-ice36.rst @@ -34,7 +34,7 @@ Installing prerequisites **The following steps are run as root.** -Install Java |javaversion_recommended|, Ice |iceversion| and PostgreSQL: +Install Java |javaversion_recommended|, Ice |iceversion| and PostgreSQL 14: To install Java |javaversion_recommended| and other dependencies: From 92467e045df02846ceb362709256da82db963fe7 Mon Sep 17 00:00:00 2001 From: Jean-Marie Burel Date: Tue, 7 Nov 2023 10:56:40 +0000 Subject: [PATCH 07/14] initial text --- .../unix/server-rockylinux9-ice36.rst | 30 +++++++++++++++++-- 1 file changed, 28 insertions(+), 2 deletions(-) diff --git a/omero/sysadmins/unix/server-rockylinux9-ice36.rst b/omero/sysadmins/unix/server-rockylinux9-ice36.rst index e8e1b5feb3..8dc00b7a5d 100644 --- a/omero/sysadmins/unix/server-rockylinux9-ice36.rst +++ b/omero/sysadmins/unix/server-rockylinux9-ice36.rst @@ -1,5 +1,31 @@ .. walkthroughs are generated using a bash script, see .. https://github.com/ome/omero-install -OMERO.server installation on RHEL 9/RockyLinux 9 -================================================ \ No newline at end of file +OMERO.server installation on RHEL 9/Rocky Linux 9 +================================================= + +This is an example walkthrough for installing OMERO on RHEL 9/Rocky Linux 9, using +a dedicated local system user. 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.9. +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-rockylinux9-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 From be96dbe488d23c68fb34cb4cfbcdd6beb6393347 Mon Sep 17 00:00:00 2001 From: Jean-Marie Burel Date: Wed, 8 Nov 2023 13:30:39 +0000 Subject: [PATCH 08/14] remove file --- .../omeroweb-install-rockylinux9-ice3.6.rst | 394 ------------------ 1 file changed, 394 deletions(-) delete mode 100644 omero/sysadmins/unix/install-web/walkthrough/omeroweb-install-rockylinux9-ice3.6.rst diff --git a/omero/sysadmins/unix/install-web/walkthrough/omeroweb-install-rockylinux9-ice3.6.rst b/omero/sysadmins/unix/install-web/walkthrough/omeroweb-install-rockylinux9-ice3.6.rst deleted file mode 100644 index 0f3a917038..0000000000 --- a/omero/sysadmins/unix/install-web/walkthrough/omeroweb-install-rockylinux9-ice3.6.rst +++ /dev/null @@ -1,394 +0,0 @@ -.. walkthroughs are generated using ansible, see -.. https://github.com/ome/omeroweb-install - -OMERO.web installation on Rocky Linux 9 and IcePy 3.6 -================================================ - -Please first read :doc:`../../server-rockylinux9-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. By default, Python 3.9 is installed. - - -**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:: - - cp nginx.repo /etc/yum.repos.d/ - - dnf -y install unzip - - dnf -y install python3 - - dnf -y install nginx - - -*Optional*: if you wish to use the Redis cache, install Redis:: - - dnf -y install redis - - systemctl enable redis.service - - systemctl start redis.service - - -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 https://github.com/glencoesoftware/zeroc-ice-py-rhel9-x86_64/releases/download/20230830/zeroc_ice-3.6.5-cp39-cp39-linux_x86_64.whl - - -Upgrade pip and install OMERO.web:: - - - /opt/omero/web/venv3/bin/pip install --upgrade pip - /opt/omero/web/venv3/bin/pip install omero-web - -Installing OMERO.web apps -------------------------- - - -A number of apps are available to add functionality to OMERO.web, such as `OMERO.figure `_ and `OMERO.iviewer `_. See the main website for a `list of released 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 WEBSESSION=True - export OMERODIR=/opt/omero/web/omero-web - - -Configure OMERO.web and create the NGINX OMERO configuration file to be included in a system-wide NGINX configuration by redirecting the output of the command ``omero web config nginx`` below into a file. If an attempt is made to access OMERO.web whilst it is not running, the generated NGINX configuration file will automatically display a maintenance page:: - - export PATH=/opt/omero/web/venv3/bin:$PATH - - - omero web config nginx --http "${WEBPORT}" --servername "${WEBSERVER_NAME}" > /opt/omero/web/omero-web/nginx.conf.tmp - -OMERO.web offers a number of configuration options. The configuration changes **will not be applied** until Gunicorn is restarted using ``omero web restart``. The Gunicorn workers are managed **separately** from other OMERO processes. You can check their status or stop them using ``omero web status`` or ``omero web stop``. - - - Session engine: - - - OMERO.web offers alternative session backends to automatically delete stale data using the cache session store backend, see :djangodoc:`Django cached session documentation ` for more details. - - - `Redis `_ requires `django-redis `_ in order to be used with OMERO.web. We assume that Redis has already been installed. To configure the cache, run:: - - omero config set omero.web.caches '{"default": {"BACKEND": "django_redis.cache. - RedisCache", "LOCATION": "redis://127.0.0.1:6379/0"}}' - - - After installing all the cache prerequisites set the following:: - - omero config set omero.web.session_engine django.contrib.sessions.backends.cache - - - - Use a prefix: - - By default OMERO.web expects to be run from the root URL of the webserver. - This can be changed by setting :property:`omero.web.prefix` and - :property:`omero.web.static_url`. For example, to make OMERO.web appear at - `http://example.org/omero/`:: - - omero config set omero.web.prefix '/omero' - omero config set omero.web.static_url '/omero/static/' - - and regenerate your webserver configuration. - - All configuration options can be found on various sections of - :ref:`web_index` developers documentation. For the full list, refer to - :ref:`web_configuration` properties. - - The most popular configuration options include: - - - Debug mode, see :property:`omero.web.debug`. - - - Customizing OMERO clients e.g. to add your own logo to the login page - (:property:`omero.web.login_logo`) or use an index page as an alternative - landing page for users (:property:`omero.web.index_template`). See - :doc:`/sysadmins/customization` for further information. - - - Enabling a public user see :doc:`/sysadmins/public`. - - -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 `_. For example to enable **debugging**, run the following command:: - - omero config set omero.web.wsgi_args -- "--log-level=DEBUG --error-logfile=/opt/omero/web/omero-web/var/log/error.log" - - - -Setting up CORS ---------------- - - -**The following steps are run as root.** - -Cross Origin Resource Sharing allows web applications hosted at other origins to access resources from your OMERO.web installation. This can be achieved using the `django-cors-headers `_ app with additional configuration of OMERO.web. See the `django-cors-headers `_ page for more details on the settings. - Since OMERO.web 5.14.0, the package `django-cors-headers` is installed by default. - - - -**The following steps are run as the omero-web system user.** - -Configure CORS. An ``index`` is used to specify the ordering of middleware classes. It is important to add the ``CorsMiddleware`` as the first class and ``CorsPostCsrfMiddleware`` as the last. You can specify allowed origins in a whitelist, or allow all, for example:: - - omero config append omero.web.middleware '{"index": 0.5, "class": "corsheaders.middleware.CorsMiddleware"}' - omero config append omero.web.middleware '{"index": 10, "class": "corsheaders.middleware.CorsPostCsrfMiddleware"}' - omero config set omero.web.cors_origin_whitelist '["https://hostname.example.com"]' - # or to allow all - omero config set omero.web.cors_origin_allow_all True - -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:: - - # Disable default server config - # Newer nginx versions: - if [ -f /etc/nginx/conf.d/default.conf ]; then - mv /etc/nginx/conf.d/default.conf /etc/nginx/conf.d/default.disabled - fi - # Older nginx versions: - sed -i.bak -re 's/( default_server.*)/; #\1/' /etc/nginx/nginx.conf - sed -i "/^\s\s\s\sserver/, /^\s\s\s\s}/ s|^|#|" /etc/nginx/nginx.conf - - cp /opt/omero/web/omero-web/nginx.conf.tmp /etc/nginx/conf.d/omeroweb.conf - - systemctl enable nginx - - systemctl start nginx - - -For production servers you may need to add additional directives to the configuration file, for example to enable `HTTPS `_. As an alternative to manually modifying the generated file you can generate a minimal configuration and include this in your own manually created NGINX file, such as :file:`/etc/nginx/conf.d/omero-web.conf`: - - :: - - omero web config nginx-location > /opt/omero/web/omero-web/omero-web-location.include - - -This requires more initial work but in the future you can automatically regenerate your OMERO.web configuration and your additional configuration settings will still apply. - - .. note:: - If you need help configuring your firewall rules, see the - :doc:`/sysadmins/server-security` page. - - - -Running OMERO.web ------------------ - - -Since OMERO.web 5.16.0, the package `whitenoise` is installed by default. - - -*Optional*: Install `Django Redis `_:: - - /opt/omero/web/venv3/bin/pip install 'django-redis==5.0.0' - -**The following steps are run as the omero-web system user.** - -*Optional*: Configure the cache:: - - omero config set omero.web.caches '{"default": {"BACKEND": "django_redis.cache.RedisCache","LOCATION": "redis://127.0.0.1:6379/0"}}' - omero config set omero.web.session_engine 'django.contrib.sessions.backends.cache' - -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 - - - -Maintaining OMERO.web ---------------------- - -**The following steps are run as the omero-web system user.** - -You can manage the sessions using the following configuration options and commands: - - - Session cookies :property:`omero.web.session_expire_at_browser_close`: - - - A boolean that determines whether to expire the session when the user - closes their browser. - See :djangodoc:`Django Browser-length sessions vs. persistent - sessions documentation ` - for more details. The default value is ``True``:: - - omero config set omero.web.session_expire_at_browser_close "True" - - - The age of session cookies, in seconds. The default value is ``86400``:: - - omero config set omero.web.session_cookie_age 86400 - - - Clear session: - - Each session for a logged-in user in OMERO.web is kept in the session - store. Stale sessions can cause the store to grow with time. OMERO.web - uses by default the OS file system as the session store backend and - does not automatically purge stale sessions, see - :djangodoc:`Django file-based session documentation ` for more details. It is therefore the responsibility of the OMERO - administrator to purge the session cache using the provided management command:: - - omero web clearsessions - - It is recommended to call this command on a regular basis, for example - as a :download:`daily cron job <../../omero-web-cron>`, see - :djangodoc:`Django clearing the session store documentation ` for more information. - - - -Troubleshooting ---------------- - -**The following steps are run as the omero-web system user.** - -In order to identify why OMERO.web is not available run ``omero web status``. Then consult NGINX :file:`error.log` and :file:`/opt/omero/web/omero-web/var/log/OMEROweb.log`. - - -Configuring Gunicorn advanced options -------------------------------------- - -OMERO.web deployment can be configured with sync and async workers. **Sync workers** are faster and recommended for a data repository with :ref:`download_restrictions`. If you wish to offer users the ability to download data then you have to use **async workers**. OMERO.web is able to handle multiple clients on a single worker thread switching context as necessary while streaming binary data from OMERO.server. Depending on the traffic and scale of the repository you should configure connections and speed limits on your server to avoid blocking resources. We recommend you run benchmark and performance tests. It is also possible to apply :ref:`download_restrictions` and offer alternative access to binary data. - - .. note:: - Handling streaming request/responses requires proxy buffering - to be turned off. For more details refer to - `Gunicorn deployment `_ - and - `NGINX configuration `_. - - .. note:: - :property:`omero.web.application_server.max_requests` should be set to 0 - - - See - `Gunicorn design `_ for more details. - - - -Experimental: Sync workers -~~~~~~~~~~~~~~~~~~~~~~~~~~ - -**The following steps are run as root.** - -Install :pypi:`futures`:: - - /opt/omero/web/venv3/bin/pip install futures - -**The following steps are run as the omero-web system user.** - -To find out more about the number of worker threads for handling requests, see `Gunicorn threads `_. Additional settings can be configured by changing the following properties:: - - omero config set omero.web.wsgi_worker_class - omero config set omero.web.wsgi_threads $(2-4 x NUM_CORES) - - - -Experimental: Async workers -~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -**The following steps are run as root.** - -Install `Gevent >= 0.13 `_:: - - /opt/omero/web/venv3/bin/pip install 'gevent>=0.13' - - - -**The following steps are run as the omero-web system user.** - -To find out more about the maximum number of simultaneous clients, see `Gunicorn worker-connections `_. Additional settings can be configured by changing the following properties:: - - omero config set omero.web.wsgi_worker_class gevent - omero config set omero.web.wsgi_worker_connections 1000 - omero config set omero.web.application_server.max_requests 0 - - - -SELinux -------- - -**The following steps are run as root.** - - -If you are running a system with `SELinux enabled `_ and are unable to access OMERO.web you may need to adjust the security policy:: - - if [ $(getenforce) != Disabled ]; then - dnf -y install policycoreutils-python-utils - setsebool -P httpd_read_user_content 1 - setsebool -P httpd_enable_homedirs 1 - semanage port -a -t http_port_t -p tcp 4080 - firewall-cmd --zone=public --add-port=4080/tcp --permanent - firewall-cmd --reload - fi - From 5114b6fd32ea9cecc9b7d95f4f8f0fc85d6599ff Mon Sep 17 00:00:00 2001 From: Jean-Marie Burel Date: Wed, 8 Nov 2023 13:33:44 +0000 Subject: [PATCH 09/14] add omero-web installation for rockylinux9 --- .../omeroweb-install-rockylinux9-ice3.6.rst | 394 ++++++++++++++++++ 1 file changed, 394 insertions(+) create mode 100644 omero/sysadmins/unix/install-web/walkthrough/omeroweb-install-rockylinux9-ice3.6.rst diff --git a/omero/sysadmins/unix/install-web/walkthrough/omeroweb-install-rockylinux9-ice3.6.rst b/omero/sysadmins/unix/install-web/walkthrough/omeroweb-install-rockylinux9-ice3.6.rst new file mode 100644 index 0000000000..cd98a68b46 --- /dev/null +++ b/omero/sysadmins/unix/install-web/walkthrough/omeroweb-install-rockylinux9-ice3.6.rst @@ -0,0 +1,394 @@ +.. walkthroughs are generated using ansible, see +.. https://github.com/ome/omeroweb-install + +OMERO.web installation on Rocky Linux 9 and IcePy 3.6 +===================================================== + +Please first read :doc:`../../server-rockylinux9-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. By default, Python 3.9 is installed. + + +**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:: + + cp nginx.repo /etc/yum.repos.d/ + + dnf -y install unzip + + dnf -y install python3 + + dnf -y install nginx + + +*Optional*: if you wish to use the Redis cache, install Redis:: + + dnf -y install redis + + systemctl enable redis.service + + systemctl start redis.service + + +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 https://github.com/glencoesoftware/zeroc-ice-py-rhel9-x86_64/releases/download/20230830/zeroc_ice-3.6.5-cp39-cp39-linux_x86_64.whl + + +Upgrade pip and install OMERO.web:: + + + /opt/omero/web/venv3/bin/pip install --upgrade pip + /opt/omero/web/venv3/bin/pip install omero-web + +Installing OMERO.web apps +------------------------- + + +A number of apps are available to add functionality to OMERO.web, such as `OMERO.figure `_ and `OMERO.iviewer `_. See the main website for a `list of released 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 WEBSESSION=True + export OMERODIR=/opt/omero/web/omero-web + + +Configure OMERO.web and create the NGINX OMERO configuration file to be included in a system-wide NGINX configuration by redirecting the output of the command ``omero web config nginx`` below into a file. If an attempt is made to access OMERO.web whilst it is not running, the generated NGINX configuration file will automatically display a maintenance page:: + + export PATH=/opt/omero/web/venv3/bin:$PATH + + + omero web config nginx --http "${WEBPORT}" --servername "${WEBSERVER_NAME}" > /opt/omero/web/omero-web/nginx.conf.tmp + +OMERO.web offers a number of configuration options. The configuration changes **will not be applied** until Gunicorn is restarted using ``omero web restart``. The Gunicorn workers are managed **separately** from other OMERO processes. You can check their status or stop them using ``omero web status`` or ``omero web stop``. + + - Session engine: + + - OMERO.web offers alternative session backends to automatically delete stale data using the cache session store backend, see :djangodoc:`Django cached session documentation ` for more details. + + - `Redis `_ requires `django-redis `_ in order to be used with OMERO.web. We assume that Redis has already been installed. To configure the cache, run:: + + omero config set omero.web.caches '{"default": {"BACKEND": "django_redis.cache. + RedisCache", "LOCATION": "redis://127.0.0.1:6379/0"}}' + + - After installing all the cache prerequisites set the following:: + + omero config set omero.web.session_engine django.contrib.sessions.backends.cache + + + - Use a prefix: + + By default OMERO.web expects to be run from the root URL of the webserver. + This can be changed by setting :property:`omero.web.prefix` and + :property:`omero.web.static_url`. For example, to make OMERO.web appear at + `http://example.org/omero/`:: + + omero config set omero.web.prefix '/omero' + omero config set omero.web.static_url '/omero/static/' + + and regenerate your webserver configuration. + + All configuration options can be found on various sections of + :ref:`web_index` developers documentation. For the full list, refer to + :ref:`web_configuration` properties. + + The most popular configuration options include: + + - Debug mode, see :property:`omero.web.debug`. + + - Customizing OMERO clients e.g. to add your own logo to the login page + (:property:`omero.web.login_logo`) or use an index page as an alternative + landing page for users (:property:`omero.web.index_template`). See + :doc:`/sysadmins/customization` for further information. + + - Enabling a public user see :doc:`/sysadmins/public`. + + +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 `_. For example to enable **debugging**, run the following command:: + + omero config set omero.web.wsgi_args -- "--log-level=DEBUG --error-logfile=/opt/omero/web/omero-web/var/log/error.log" + + + +Setting up CORS +--------------- + + +**The following steps are run as root.** + +Cross Origin Resource Sharing allows web applications hosted at other origins to access resources from your OMERO.web installation. This can be achieved using the `django-cors-headers `_ app with additional configuration of OMERO.web. See the `django-cors-headers `_ page for more details on the settings. + Since OMERO.web 5.14.0, the package `django-cors-headers` is installed by default. + + + +**The following steps are run as the omero-web system user.** + +Configure CORS. An ``index`` is used to specify the ordering of middleware classes. It is important to add the ``CorsMiddleware`` as the first class and ``CorsPostCsrfMiddleware`` as the last. You can specify allowed origins in a whitelist, or allow all, for example:: + + omero config append omero.web.middleware '{"index": 0.5, "class": "corsheaders.middleware.CorsMiddleware"}' + omero config append omero.web.middleware '{"index": 10, "class": "corsheaders.middleware.CorsPostCsrfMiddleware"}' + omero config set omero.web.cors_origin_whitelist '["https://hostname.example.com"]' + # or to allow all + omero config set omero.web.cors_origin_allow_all True + +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:: + + # Disable default server config + # Newer nginx versions: + if [ -f /etc/nginx/conf.d/default.conf ]; then + mv /etc/nginx/conf.d/default.conf /etc/nginx/conf.d/default.disabled + fi + # Older nginx versions: + sed -i.bak -re 's/( default_server.*)/; #\1/' /etc/nginx/nginx.conf + sed -i "/^\s\s\s\sserver/, /^\s\s\s\s}/ s|^|#|" /etc/nginx/nginx.conf + + cp /opt/omero/web/omero-web/nginx.conf.tmp /etc/nginx/conf.d/omeroweb.conf + + systemctl enable nginx + + systemctl start nginx + + +For production servers you may need to add additional directives to the configuration file, for example to enable `HTTPS `_. As an alternative to manually modifying the generated file you can generate a minimal configuration and include this in your own manually created NGINX file, such as :file:`/etc/nginx/conf.d/omero-web.conf`: + + :: + + omero web config nginx-location > /opt/omero/web/omero-web/omero-web-location.include + + +This requires more initial work but in the future you can automatically regenerate your OMERO.web configuration and your additional configuration settings will still apply. + + .. note:: + If you need help configuring your firewall rules, see the + :doc:`/sysadmins/server-security` page. + + + +Running OMERO.web +----------------- + + +Since OMERO.web 5.16.0, the package `whitenoise` is installed by default. + + +*Optional*: Install `Django Redis `_:: + + /opt/omero/web/venv3/bin/pip install 'django-redis==5.0.0' + +**The following steps are run as the omero-web system user.** + +*Optional*: Configure the cache:: + + omero config set omero.web.caches '{"default": {"BACKEND": "django_redis.cache.RedisCache","LOCATION": "redis://127.0.0.1:6379/0"}}' + omero config set omero.web.session_engine 'django.contrib.sessions.backends.cache' + +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 + + + +Maintaining OMERO.web +--------------------- + +**The following steps are run as the omero-web system user.** + +You can manage the sessions using the following configuration options and commands: + + - Session cookies :property:`omero.web.session_expire_at_browser_close`: + + - A boolean that determines whether to expire the session when the user + closes their browser. + See :djangodoc:`Django Browser-length sessions vs. persistent + sessions documentation ` + for more details. The default value is ``True``:: + + omero config set omero.web.session_expire_at_browser_close "True" + + - The age of session cookies, in seconds. The default value is ``86400``:: + + omero config set omero.web.session_cookie_age 86400 + + - Clear session: + + Each session for a logged-in user in OMERO.web is kept in the session + store. Stale sessions can cause the store to grow with time. OMERO.web + uses by default the OS file system as the session store backend and + does not automatically purge stale sessions, see + :djangodoc:`Django file-based session documentation ` for more details. It is therefore the responsibility of the OMERO + administrator to purge the session cache using the provided management command:: + + omero web clearsessions + + It is recommended to call this command on a regular basis, for example + as a :download:`daily cron job <../../omero-web-cron>`, see + :djangodoc:`Django clearing the session store documentation ` for more information. + + + +Troubleshooting +--------------- + +**The following steps are run as the omero-web system user.** + +In order to identify why OMERO.web is not available run ``omero web status``. Then consult NGINX :file:`error.log` and :file:`/opt/omero/web/omero-web/var/log/OMEROweb.log`. + + +Configuring Gunicorn advanced options +------------------------------------- + +OMERO.web deployment can be configured with sync and async workers. **Sync workers** are faster and recommended for a data repository with :ref:`download_restrictions`. If you wish to offer users the ability to download data then you have to use **async workers**. OMERO.web is able to handle multiple clients on a single worker thread switching context as necessary while streaming binary data from OMERO.server. Depending on the traffic and scale of the repository you should configure connections and speed limits on your server to avoid blocking resources. We recommend you run benchmark and performance tests. It is also possible to apply :ref:`download_restrictions` and offer alternative access to binary data. + + .. note:: + Handling streaming request/responses requires proxy buffering + to be turned off. For more details refer to + `Gunicorn deployment `_ + and + `NGINX configuration `_. + + .. note:: + :property:`omero.web.application_server.max_requests` should be set to 0 + + + See + `Gunicorn design `_ for more details. + + + +Experimental: Sync workers +~~~~~~~~~~~~~~~~~~~~~~~~~~ + +**The following steps are run as root.** + +Install :pypi:`futures`:: + + /opt/omero/web/venv3/bin/pip install futures + +**The following steps are run as the omero-web system user.** + +To find out more about the number of worker threads for handling requests, see `Gunicorn threads `_. Additional settings can be configured by changing the following properties:: + + omero config set omero.web.wsgi_worker_class + omero config set omero.web.wsgi_threads $(2-4 x NUM_CORES) + + + +Experimental: Async workers +~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +**The following steps are run as root.** + +Install `Gevent >= 0.13 `_:: + + /opt/omero/web/venv3/bin/pip install 'gevent>=0.13' + + + +**The following steps are run as the omero-web system user.** + +To find out more about the maximum number of simultaneous clients, see `Gunicorn worker-connections `_. Additional settings can be configured by changing the following properties:: + + omero config set omero.web.wsgi_worker_class gevent + omero config set omero.web.wsgi_worker_connections 1000 + omero config set omero.web.application_server.max_requests 0 + + + +SELinux +------- + +**The following steps are run as root.** + + +If you are running a system with `SELinux enabled `_ and are unable to access OMERO.web you may need to adjust the security policy:: + + if [ $(getenforce) != Disabled ]; then + dnf -y install policycoreutils-python-utils + setsebool -P httpd_read_user_content 1 + setsebool -P httpd_enable_homedirs 1 + semanage port -a -t http_port_t -p tcp 4080 + firewall-cmd --zone=public --add-port=4080/tcp --permanent + firewall-cmd --reload + fi + From c64cfd4a5da45bba301b9301a837c2d8bb15f4c0 Mon Sep 17 00:00:00 2001 From: Jean-Marie Burel Date: Wed, 8 Nov 2023 13:35:56 +0000 Subject: [PATCH 10/14] update rocky9 walkthrough --- .../unix/walkthrough/walkthrough_rocky9.sh | 44 ++++++++++++------- 1 file changed, 27 insertions(+), 17 deletions(-) diff --git a/omero/sysadmins/unix/walkthrough/walkthrough_rocky9.sh b/omero/sysadmins/unix/walkthrough/walkthrough_rocky9.sh index 73c0a7efc7..cd41ce7120 100644 --- a/omero/sysadmins/unix/walkthrough/walkthrough_rocky9.sh +++ b/omero/sysadmins/unix/walkthrough/walkthrough_rocky9.sh @@ -7,21 +7,25 @@ yum -y install epel-release yum -y install unzip wget bc # install Java -yum -y install java-11-openjdk +dnf -y install java-11-openjdk # install dependencies - -yum -y install python3 -yum -y install openssl +dnf -y install python unzip bzip2 wget bc openssl #end-step01 # install Ice #start-recommended-ice -dnf config-manager --set-enabled crb -yum -y install bzip2 expat libdb-cxx +if grep -q "Rocky" /etc/redhat-release; then + dnf -y install 'dnf-command(config-manager)' + dnf config-manager --set-enabled crb +fi +if grep -q "Red Hat" /etc/redhat-release; then + subscription-manager repos --enable codeready-builder-for-rhel-9-$(arch)-rpms +fi +dnf -y install expat libdb-cxx cd /tmp -wget https://github.com/sbesson/zeroc-ice-rockylinux9-x86_64/releases/download/202307018/Ice-3.6.5-rockylinux9-x86_64.tar.gz -tar xf Ice-3.6.5-rockylinux9-x86_64.tar.gz +wget https://github.com/glencoesoftware/zeroc-ice-rhel9-x86_64/releases/download/20230928/Ice-3.6.5-rhel9-x86_64.tar.gz +tar xf Ice-3.6.5-rhel9-x86_64.tar.gz mv Ice-3.6.5 /opt/ice-3.6.5 echo /opt/ice-3.6.5/lib64 > /etc/ld.so.conf.d/ice-x86_64.conf ldconfig @@ -29,18 +33,15 @@ ldconfig # install Postgres +dnf install -y https://download.postgresql.org/pub/repos/yum/reporpms/EL-9-x86_64/pgdg-redhat-repo-latest.noarch.rpm +dnf -qy module disable postgresql +dnf -y install postgresql15-server postgresql15 +PGSETUP_INITDB_OPTIONS=--encoding=UTF8 /usr/pgsql-15/bin/postgresql-15-setup initdb -yum -y install postgresql-server postgresql - -PGSETUP_INITDB_OPTIONS=--encoding=UTF8 /usr/bin/postgresql-setup --initdb - -sed -i.bak -re 's/^(host.*)ident/\1md5/' /var/lib/pgsql/data/pg_hba.conf - +sed -i.bak -re 's/^(host.*)ident/\1md5/' /var/lib/pgsql/15/data/pg_hba.conf +sed -i 's/ ident/ trust/g' /var/lib/pgsql/15/data/pg_hba.conf systemctl start postgresql - systemctl enable postgresql - -sed -i 's/ ident/ trust/g' /var/lib/pgsql/data/pg_hba.conf #end-step01 #start-step02: As root, create a local omero-server system user and directory for the OMERO repository @@ -114,3 +115,12 @@ chmod go-rwx $OMERODIR/etc $OMERODIR/var # Optionally restrict access to the OMERO data directory # chmod go-rwx "$OMERO_DATA_DIR" #end-step07 +#start-step08: As root, configure +cp omero-server-systemd.service /etc/systemd/system/omero-server.service + +systemctl daemon-reload + +systemctl enable omero-server.service +firewall-cmd --zone=public --add-port=4064/tcp --permanent +firewall-cmd --reload +#end-step08 From 8d6a3684b2f13907e3b312e84751da777109ed52 Mon Sep 17 00:00:00 2001 From: Jean-Marie Burel Date: Wed, 8 Nov 2023 13:52:27 +0000 Subject: [PATCH 11/14] add rockylinux to list --- omero/sysadmins/unix/install-web/web-deployment.rst | 8 ++++++-- 1 file changed, 6 insertions(+), 2 deletions(-) diff --git a/omero/sysadmins/unix/install-web/web-deployment.rst b/omero/sysadmins/unix/install-web/web-deployment.rst index f0c4c88cd4..ac30312f8b 100644 --- a/omero/sysadmins/unix/install-web/web-deployment.rst +++ b/omero/sysadmins/unix/install-web/web-deployment.rst @@ -52,11 +52,15 @@ Walkthroughs :doc:`walkthrough/omeroweb-install-ubuntu1804-ice3.6` Instructions for installing OMERO.web from scratch on Ubuntu 18.04 with Ice 3.6. -**Upcoming:** - :doc:`walkthrough/omeroweb-install-ubuntu2004-ice3.6` Instructions for installing OMERO.web from scratch on Ubuntu 20.04 with Ice 3.6. +:doc:`walkthrough/omeroweb-install-rockylinux9-ice3.6` + Instructions for installing OMERO.web from scratch on RHEL 9/Rocky Linux 9 with Ice 3.6. + +:doc:`walkthrough/omeroweb-install-ubuntu2204-ice3.6` + Instructions for installing OMERO.web from scratch on Ubuntu 22.04 with Ice 3.6. + .. toctree:: :maxdepth: 1 :titlesonly: From dca0350a6e6c4838d3dfe5e8883712e350a73254 Mon Sep 17 00:00:00 2001 From: Jean-Marie Burel Date: Wed, 8 Nov 2023 15:07:21 +0000 Subject: [PATCH 12/14] add rockylinux to list of platforms --- omero/sysadmins/unix/server-installation.rst | 4 ++++ 1 file changed, 4 insertions(+) diff --git a/omero/sysadmins/unix/server-installation.rst b/omero/sysadmins/unix/server-installation.rst index f2da21689e..4ea7c71c12 100644 --- a/omero/sysadmins/unix/server-installation.rst +++ b/omero/sysadmins/unix/server-installation.rst @@ -32,6 +32,10 @@ Since 5.6, a new :envvar:`OMERODIR` variable is used, you should first unset :en Instructions for installing OMERO.server from scratch on Ubuntu 20.04 with Ice 3.6 and Python 3.8. +:doc:`server-rockylinux9-ice36` + Instructions for installing OMERO.server from scratch on + RHEL 9/Rocky Linux 9 with Ice 3.6 and Python 3.9. + :doc:`server-ubuntu2204-ice36` Instructions for installing OMERO.server from scratch on Ubuntu 22.04 with Ice 3.6 and Python 3.10. From 287aa823cd239e0df156c3fdbcb0a3195100a89a Mon Sep 17 00:00:00 2001 From: Jean-Marie Burel Date: Wed, 8 Nov 2023 15:10:01 +0000 Subject: [PATCH 13/14] reorganise --- .../unix/install-web/web-deployment.rst | 20 +++++++---------- omero/sysadmins/unix/server-installation.rst | 22 +++++++------------ 2 files changed, 16 insertions(+), 26 deletions(-) diff --git a/omero/sysadmins/unix/install-web/web-deployment.rst b/omero/sysadmins/unix/install-web/web-deployment.rst index ac30312f8b..aeaaaa42a4 100644 --- a/omero/sysadmins/unix/install-web/web-deployment.rst +++ b/omero/sysadmins/unix/install-web/web-deployment.rst @@ -43,24 +43,20 @@ Walkthroughs **Recommended:** -: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-debian10-ice3.6` - Instructions for installing OMERO.web from scratch on Debian 10 with Ice 3.6. - -:doc:`walkthrough/omeroweb-install-ubuntu1804-ice3.6` - Instructions for installing OMERO.web from scratch on Ubuntu 18.04 with Ice 3.6. - -:doc:`walkthrough/omeroweb-install-ubuntu2004-ice3.6` - Instructions for installing OMERO.web from scratch on Ubuntu 20.04 with Ice 3.6. - :doc:`walkthrough/omeroweb-install-rockylinux9-ice3.6` Instructions for installing OMERO.web from scratch on RHEL 9/Rocky Linux 9 with Ice 3.6. :doc:`walkthrough/omeroweb-install-ubuntu2204-ice3.6` Instructions for installing OMERO.web from scratch on Ubuntu 22.04 with Ice 3.6. +**Supported:** + +: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-ubuntu2004-ice3.6` + Instructions for installing OMERO.web from scratch on Ubuntu 20.04 with Ice 3.6. + .. toctree:: :maxdepth: 1 :titlesonly: diff --git a/omero/sysadmins/unix/server-installation.rst b/omero/sysadmins/unix/server-installation.rst index 4ea7c71c12..8e7cdd299c 100644 --- a/omero/sysadmins/unix/server-installation.rst +++ b/omero/sysadmins/unix/server-installation.rst @@ -16,30 +16,24 @@ Since 5.6, a new :envvar:`OMERODIR` variable is used, you should first unset :en **Recommended:** -:doc:`server-centos7-ice36` +:doc:`server-rockylinux9-ice36` Instructions for installing OMERO.server from scratch on - CentOS 7 with Ice 3.6 and Python 3.6. + RHEL 9/Rocky Linux 9 with Ice 3.6 and Python 3.9. -:doc:`server-debian10-ice36` +:doc:`server-ubuntu2204-ice36` Instructions for installing OMERO.server from scratch on - Debian 10 with Ice 3.6 and Python 3.7. + Ubuntu 22.04 with Ice 3.6 and Python 3.10. + +**Supported:** -:doc:`server-ubuntu1804-ice36` +:doc:`server-centos7-ice36` Instructions for installing OMERO.server from scratch on - Ubuntu 18.04 with Ice 3.6 and Python 3.6. + CentOS 7 with Ice 3.6 and Python 3.6. :doc:`server-ubuntu2004-ice36` Instructions for installing OMERO.server from scratch on Ubuntu 20.04 with Ice 3.6 and Python 3.8. -:doc:`server-rockylinux9-ice36` - Instructions for installing OMERO.server from scratch on - RHEL 9/Rocky Linux 9 with Ice 3.6 and Python 3.9. - -:doc:`server-ubuntu2204-ice36` - Instructions for installing OMERO.server from scratch on - Ubuntu 22.04 with Ice 3.6 and Python 3.10. - **Development:** :doc:`server-install-homebrew` From 921687128b914a273e172e39842c4c4b7077d8e0 Mon Sep 17 00:00:00 2001 From: Jean-Marie Burel Date: Wed, 8 Nov 2023 15:45:08 +0000 Subject: [PATCH 14/14] add instruction for rhel 9/rocky 9 --- .../unix/server-rockylinux9-ice36.rst | 123 ++++++++++++++++++ 1 file changed, 123 insertions(+) diff --git a/omero/sysadmins/unix/server-rockylinux9-ice36.rst b/omero/sysadmins/unix/server-rockylinux9-ice36.rst index 8dc00b7a5d..bb366be62f 100644 --- a/omero/sysadmins/unix/server-rockylinux9-ice36.rst +++ b/omero/sysadmins/unix/server-rockylinux9-ice36.rst @@ -29,3 +29,126 @@ either use your own values, or alternatively create :file:`settings.env` for exa .. literalinclude:: walkthrough/settings.env :start-after: Substitute + +Installing prerequisites +------------------------ + +**The following steps are run as root.** + +Install Java |javaversion_recommended|, Ice |iceversion| and PostgreSQL 15: + +To install Java |javaversion_recommended| and other dependencies: + +.. literalinclude:: walkthrough/walkthrough_rocky9.sh + :start-after: #start-step01 + :end-before: #end-step01 + +To install Ice |iceversion|: + +.. literalinclude:: walkthrough/walkthrough_rocky9.sh + :start-after: #start-recommended-ice + :end-before: #end-recommended-ice + +To install PostgreSQL 15: + +.. literalinclude:: walkthrough/walkthrough_rocky9.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_rocky9_deps.sh + `_ + +Create a local omero-server system user, and a directory for the OMERO repository: + +.. literalinclude:: walkthrough/walkthrough_rocky9.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_rocky9.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 the dependencies required by the server using ``pip``: + +.. literalinclude:: walkthrough/walkthrough_rocky9.sh + :start-after: #start-step03bis + :end-before: #end-step03bis + +Download and unzip OMERO.server: + +.. literalinclude:: walkthrough/walkthrough_rocky9.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_rocky9.sh + :start-after: #end-release-ice36 + :end-before: #end-step04-pre + +Configuring the OMERO.server +---------------------------- + +**The following steps are run as the omero-server system user.** (``su - omero-server``) + +The variable ``OMERODIR`` set in :download:`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 database and the location of the data directory: + +.. literalinclude:: walkthrough/walkthrough_rocky9.sh + :start-after: #end-copy-omeroscript + :end-before: #end-step04 + +.. include:: ciphers + +.. literalinclude:: walkthrough/walkthrough_rocky9.sh + :start-after: #start-seclevel + :end-before: #end-seclevel + +Running the 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 ` +is available. + +Copy the ``systemd.service`` file and configure the service: + +.. literalinclude:: walkthrough/walkthrough_rocky9.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_rocky9.sh + :start-after: #start-step07 + :end-before: #end-step07