OMERO Plus Essentials AMI installation

Thanks for your interest in subscribing to OMERO Plus Essentials. On this page you will find usage instructions, outlining the required resources, for an advanced AMI based installation. It is expected you will have experience with AWS nomenclature and infrastructure resources before continuing. If you do not, you may find the CloudFormation based installation much more appealing.

Before you install OMERO Plus Essentials

You will need the following:

1. An AWS account
2. IAM Permissions to provision the resources detailed below. The AdministratorAccess policy is sufficient. (OMERO Plus Essentials requires a VPC and subnet(s), security groups, load balancer, EC2 instance, database and storage for your images.
3. The ability to create DNS entries, such as CNAME records, for your organization’s domain.
4. An SSL certificate in your desired AWS region to secure the domain where your users will access your OMERO Plus Essentials instance in AWS Certificate Manager. You may either create a new certificate, or import an existing certificate.

Using AWS

If this is your first time using AWS, follow Amazon’s instructions for creating your AWS account.

When configuring OMERO Plus Essentials, you’ll have the option to select the domain where OMERO Plus Essentials will be deployed. Register a domain name following these instructions.

Now you are ready to make your purchase via AWS Marketplace! Scroll down to our contact form below to receive the private offer.

AMI setup

AWS Secrets Manager

Create the following secrets in AWS Secrets Manager:

• omero-plus-essentials-db-master
  • Description: This is the password for the PostgreSQL master account. OMERO Plus Essentials will use this to talk to the database.
• omero-plus-essentials-root
  • Description: This is the password for the OMERO Plus Essentials application ‘root’ account.

VPC and Subnet

• Create a VPC and subnets: choose the option for “VPC and more” when creating a VPC.
• Set the name tag auto generation as omero-plus-essentials.
• Set preferred IPv4 CIDR block: Glencoe Software recommends 10.0.0.0/16.
• Choose whether to associate an Amazon-provided IPv6 CIDR block with the VPC. Glencoe Software’s CloudFormation does this.
• Choose the number of Availability Zones (AZ) in which to provision subnets:
  • The VPC is created in the currently selected region. There are always at least 2 availability zones regardless of the region. Glencoe recommends choosing at least 2 AZs, if not the maximum allowed in the region. The same number of public subnets should be created. Glencoe Software’s CloudFormation does not create private subnets.
• NAT Gateways: None
• VPC Endpoints: None
• Enable DNS hostnames and DNS resolution.

Security groups

Create the following:

With the following inbound/outbound rules:

EC2 (initial creation)

• Select the OMERO Plus Essentials AMI.
• Select from the supported EC2 instance types.
• Optionally, select a keypair for SSH access. Glencoe Software’s CloudFormation uses InstanceConnect.
• Choose the VPC created above and the OmeroPlusSecurityGroup
• Storage
  • 8 GB root volume is sufficient
  • Add a second 50 GB EBS volume (gp2 is recommended) for software and logs.

The OMERO Plus Essentials AMI is based on the Ubuntu 22.04 LTS AMI from Canonical. Consequently, the default username is ubuntu and the OMERO Plus application itself runs as omero.

Instance Connect (optional)

• Create EC2 Instance Connect Endpoint.
• Select the omero-plus-essentials VPC when creating this endpoint.

Load Balancer

• Create a Network Load Balancer named omero-plus-essentials
• Select the omero-plus-essentials VPC and a single availability zone (use the same AZ when creating RDS)
• Choose Dualstack IP address type and internet-facing type
• Select the LoadBalancerSecurityGroup
• The following listeners should be added:
  • TLS:443
    • Forward to: http (this Instance target will need to be created)
  • TCP:4064
    • Forward to: ice-ssl (this Instance target will need to be created)
• Apply the recommended security policy
• Choose the available certificate for essentials.<region>.<domain name> from ACM

Redis OSS cache

Redis is used for session management for OMERO Plus. To replicate the behavior of Glencoe’s CloudFormation, perform the following:

• Design your own cache and disable cluster mode.
• Multi-AZ and Auto-failover can be disabled.
• Use engine version 7.1, port 6379, node type cache.t3.small, with the default.redis7 parameter group. Zero replicas are needed.
• Create a new subnet group called redissubnetgroup and select the VPC created for omero-plus-essentials.
• Encryption and backups can be enabled if desired.

RDS

• Choose PostgreSQL (Glencoe’s CloudFormation uses the latest version of 17.x)
• Create a single-AZ DB instance deployment (1 instance) OR Multi-AZ DB instance deployment (2 instances) according to your preference
• See Secrets Manager section - if DB master username/password has already been created, provide it. Otherwise, create it now.
• Use existing DB subnet group and do not provide public access
• Choose the VPC Security Group: OmeroPlusDbSecurityGroup

Image Data Storage

• Creat an Elastic File System instance
  • Name this omero-binary-repository.
  • Choose to either store data across multiple Availability Zones or within a single Availability Zone.
  • Glencoe Software’s CloudFormation sets the following:
    • Regional
    • Lifecycle management:
      • Transition into Infrequent Access (IA): None
      • Transition into Archive: None
      • Transition into Standard: None
    • No encryption of data at rest
    • Throughput mode: Bursting
    • Performance mode: General Purpose
  • Choose the omero-plus-essentials VPC created previously
  • Glencoe’s CloudFormation creates a single mount target for a single AZ and subnet.
  • Apply the OmeroPlusBinaryRepositorySecurityGroup to the relevant Mount target(s).

Route53

• A public domain name should have been registered as instructed here: https://www.glencoesoftware.com/products/omeroplus/essentials/getting-started/
• Create two hosted zones:
  • Private: omero-plus-hosted.internal
  • Public: <domain name previously registered> (this should already have been created in step one)
• Associate the omero-plus-essentials VPC to the new private hosted zone.
• The following additional 5 records should be created in the private zone:

• The following record should be created in the public zone:

IAM

Create an instance profile with the following policy (replace ARNs for secrets):

{
    "Version": "2012-10-17",
    "Statement": [
        {
            "Action": [
                "license-manager:GetLicense",
                "license-manager:ListReceivedLicenses"
            ],
            "Resource": "*",
            "Effect": "Allow"
        },
        {
            "Action": "secretsmanager:GetSecretValue",
            "Resource": "<omero-plus-essentials-db-master secret ARN>",
            "Effect": "Allow"
        },
        {
            "Action": "secretsmanager:GetSecretValue",
            "Resource": "<omero-plus-essentials-root secret ARN>",
            "Effect": "Allow"
        }
    ]
}

EC2 (final configuration)

• Run the following as root user unless otherwise specified:
  • Mount EFS and make omero:omero binary repository available at /OMERO:

    • Create the following file /etc/systemd/system/data.mount (NOTE: replace File System ID and AWS Region with the appropriate values):

      [Unit]
      Description=OMERO Binary Repository - EFS filesystem
      Before=remote-fs.target
      After=network.target
      
      [Mount]
      Where=/data
      What=<File System ID>.efs.<AWS Region>.amazonaws.com:/
      Type=nfs4
      Options=nfsvers=4.1,rsize=1048576,wsize=1048576,hard,timeo=600,retrans=2,noresvport
      
      [Install]
      WantedBy=remote-fs.target
      

    • Run systemctl daemon-reload && systemctl enable --now data.mount
    • Run mkdir -m 0755 -p /data/OMERO.repo && chown omero:omero /data/OMERO.repo
  • Set environment variables in /etc/profile.d/omero-plus-essentials.sh
    • PGHOST (default: db.omero-plus-hosted.internal if using Route53)
    • PGUSER (default: omero)
    • PGDATABASE (default: omero)
    • OMERO_DB_PASSWORD_SECRET_ID (from Secrets Manager)
    • OMERO_ADMIN_SECRET_ID (from Secrets Manager)
    • AWS_REGION
    • REDIS_ADDRESS (default to redis.omero-plus-hosted.internal)
  • Set hostnames in /etc/hosts if not using Route53:

    127.0.0.1 web.omero-plus-hosted.internal
    127.0.0.1 ms.omero-plus-hosted.internal
    127.0.0.1 server.omero-plus-hosted.internal
    <RDS IP Address> db.omero-plus-hosted.internal
    <Redis IP Address> redis.omero-plus-hosted.internal
    

  • As omero user run:
    • setup/initdb
    • omero certificates
    • setup/web
    • setup/ms
  • Symlink omero from /etc/nginx/sites-available into /etc/nginx/sites-enabled
  • Start systemd services (systemctl start <service>):
    • omero-server
    • omero-ms-thumnbail
    • omero-ms-image-region
    • omero-ms-pixel-buffer
    • nginx
    • omero-web

Example:

# cat /etc/profile.d/omero-plus-essentials.sh
export PGHOST=db.omero-plus-hosted.internal
export PGUSER=omero
export PGDATABASE=omero
export OMERO_DB_PASSWORD_SECRET_ID="arn:aws:secretsmanager:us-east-2:537124958230:secret:omero-plus-essentials-db-master-VMHWkV"
export OMERO_ADMIN_SECRET_ID="arn:aws:secretsmanager:us-east-2:537124958230:secret:omero-plus-essentials-root-0YW8P2"
export AWS_REGION=us-east-2
export REDIS_ADDRESS=redis.omero-plus-hosted.internal