From 531a7a32ab5c44a7d65a216dd2ad618abed410ac Mon Sep 17 00:00:00 2001 From: Daniel Matthews Date: Tue, 26 Mar 2024 10:58:27 +0000 Subject: [PATCH] Add README.md --- roles/omero_server/README.md | 122 +++++++++++++++++++++++++++++++++++ 1 file changed, 122 insertions(+) create mode 100644 roles/omero_server/README.md diff --git a/roles/omero_server/README.md b/roles/omero_server/README.md new file mode 100644 index 00000000..327f008f --- /dev/null +++ b/roles/omero_server/README.md @@ -0,0 +1,122 @@ +# Installs and configures OMERO.server + +This role has been adapted from the +[ome.omero_server](https://github.com/ome/ansible-role-omero-server/tree/master) +role maintained by the OME team. The reasons for maintaining a separate role +here are: + +1. The OME role no longer supports EL `8` OS variants +2. There is a [bug in the OME + role](https://github.com/ome/ansible-role-omero-server/issues/72) which stops + a database backup working when OMERO.server is upgraded + +If running EL `9` and you set `omero_server_release` to `latest` it is +recommended that you use the `ome.omero_server` role in place of this one. + +## Dependencies + +A PostgreSQL server installed using `mirsg.infrastructure.postgresql` is +required. + +This role is also dependent on a number of other OME roles. Due to the lack of +support for EL `8` OS variants in newer versions of those roles, the versions of +these dependencies are pinned here (see the collection +[requirements.yml](../../meta/requirements.yml) file): + +| Role | Version | +| ---------------------- | ------- | +| ome.omero_web | 4.0.1 | +| ome.omero_user | 0.3.1 | +| ome.selinux_utils | 2.0.2 | +| ome.omero_common | 0.4.0 | +| ome.python3_virtualenv | 0.2.0 | +| ome.ice | 4.3.0 | + +Note that these roles themselves have dependencies on other OME roles. + +## Role Variables + +All variables are optional, see defaults/main.yml for the full list + +### OMERO.server version + +`omero_server_release`: The OMERO release, e.g. 5.6.0. Defaults to `5.6.0`. + +`omero_server_dbhost`: Database host `omero_server_dbuser`: Database user +`omero_server_dbname`: Database name `omero_server_dbpassword`: Database +password `omero_server_rootpassword`: OMERO root password, defaults to `omero`. +This is only used when initialising a new database. + +### OMERO.server configuration + +`omero_server_config_set`: A dictionary of config-key: value which will be used +for the initial OMERO.server configuration, default empty. value can be a +string, or an object (list, dictionary) that will be automatically converted to +quoted JSON. Note configuration can also be done pre/post installation using the +server/config conf.d style directory. OMERO system user, group, permissions, and +data directory. You may need to change these for in-place imports. + +`omero_server_system_user`: OMERO.server system user, default omero-server. +`omero_server_system_user_manage`: Create or update the OMERO.server system user +if necessary, default True. `omero_server_system_uid`: OMERO system user ID +(default automatic) `omero_server_system_umask`: OMERO system user umask, may +need to be changed for in-place imports `omero_server_system_managedrepo_group`: +OMERO system group for the ManagedRepository `omero_server_datadir_mode`: +Permissions for OMERO data directories apart from ManagedRepository +`omero_server_datadir_managedrepo_mode`: Permissions for OMERO ManagedRepository +`omero_server_datadir`: OMERO data directory, default /OMERO +`omero_server_datadir_managedrepo`: OMERO ManagedRepository directory +`omero_server_selfsigned_certificates`: Generate self-signed certificates +instead of using anonymous ciphers, default True, use this if your system does +not support insecure ciphers + +### OMERO.server systemd configuration + +`omero_server_systemd_setup`: Create and start the omero-server systemd service, +default True `omero_server_systemd_limit_nofile`: Systemd limit for number of +open files (default ignore) `omero_server_systemd_after`: A list of strings with +additional service names to appear in systemd unit file "After" statements. +Default empty/none. `omero_server_systemd_requires`: A list of strings with +additional service names to appear in systemd unit file "Requires" statements. +Default empty/none. `omero_server_systemd_environment`: Dictionary of additional +environment variables. Python virtualenv + +`omero_server_python_addons`: List of additional Python packages to be installed +into virtualenv. Alternatively you can install packages into +/opt/omero/server/venv3 independently from this role. Backups + +`omero_server_database_backupdir`: Dump the OMERO database to this directory +before upgrading, default empty (disabled) + +### Configuring OMERO.server + +This role regenerates the OMERO configuration file using the configuration files +and helper script in `/opt/omero/server/config`. omero_server_config_set can be +used for simple configurations, for anything more complex consider creating one +or more configuration files under: `/opt/omero/server/config/` with the +extension .omero. + +Manual configuration changes (omero config ...) will be lost following a restart +of omero-server with systemd, you can disable this by setting +omero_server_always_reset_config: false. Manual configuration changes will never +be copied during an upgrade. + +See ome/design#70 for a proposal to add support for a conf.d style directory +directly into OMERO. + +### Example Playbook + +```yaml +# Install or upgrade to a particular version, with an external database +- hosts: localhost + roles: + - role: mirsg.infrastructure.omero_server + vars: + omero_server_release: "5.6.0" + omero_server_dbhost: postgres.example.org + omero_server_dbuser: db_user + omero_server_dbname: db_name + omero_server_dbpassword: db_password + # Version required for the psql client + postgresql_version: "13" +```