Installation documentation

[Rdornier]

Hello,

During the installation process of omero-zarr-pixel-buffer, I realised that only installing the jar file wasn't sufficient. I also had to manually install all the dependencies declared in the build.gradle file, as well as the blosc library, in order to make it work.

In the current documentation, this was not obiously mentionned (see this post).

Having an Installation section in the README would help to know what needs to be installed.
On the other hand, one option, which could also be nice, is to have the possibility to create a jar-with-dependencies, so that we just have to install omero-zarr-pixel-buffer and blosc library.

Thanks,
Rémy.

[sbesson]

@Rdornier thanks for starting this important discussion.

Having an Installation section in the README would help to know what needs to be installed.

Absolutely. The README has so far been focused on describing how OME-Zarr is expected stored in the OMERO database but it would benefit from an installation section. This is particularly important as this library gets used while it is currently not a core component of OMERO.server.

I also had to manually install all the dependencies declared in the build.gradle file, as well as the blosc library, in order to make it work.

For libblosc, the standard caveat is that the library name will depend on the Linux distribution. A good starting point would be to enumerate the package names for RHEL/Ubuntu which are the officially supported system.
On the Java side, the full dependency tree of omero-zarr-pixel-buffer (as reported by ./gradlew dependencies) should be available via the Java class path of the server.

On the other hand, one option, which could also be nice, is to have the possibility to create a jar-with-dependencies, so that we just have to install omero-zarr-pixel-buffer and blosc library.

Although this is technically sound, I am not favourable to this proposal in particular in the context a production deployment. As a single file, uber-JAR/fat JAR offers obvious deployment advantages but the embedding of the underlying dependencies creates real issues from a support/maintenance perspective. In addition, it makes it possible for the same dependencies to be shipped with different incompatible versions and be the source of runtime/loading issues.

To be complete, the way Glencoe solves this deployment issue is by declaring officially the omero-zarr-pixel-buffer as an extension of theOMERO.server bundle used by OMERO Plus. Adding the dependency to ivy.xml under https://github.com/ome/openmicroscopy/ allows the build system/Ivy dependency mechanism to resolve all the dependencies and copy them as individual JARs under lib/server

  <dependencies>
    <dependency org="org.openmicroscopy" name="omero-blitz" rev="${versions.omero-blitz}"/>
    <dependency org="org.openmicroscopy" name="omero-gateway" rev="${versions.omero-gateway}"/>
    <!-- runtime dependencies from dsl/ivy.xml -->
    <dependency org="janino" name="janino" rev="${versions.janino}"/>
    <!-- Useful for globally overriding the Bio-Formats version, empty version is ignored by default -->
    <dependency org="ome" name="formats-gpl" rev="${versions.bioformats}"/>
    <!-- Extensions for bundling into the release -->
    <dependency org="com.glencoesoftware.omero" name="omero-zarr-pixel-buffer" rev="${versions.omero-zarr-pixel-buffer}"/>

[Rdornier]

@sbesson Thanks for your message.

For libblosc, the standard caveat is that the library name will depend on the Linux distribution. A good starting point would be to enumerate the package names for RHEL/Ubuntu which are the officially supported system.

I think it's a good idea, yes. I updated the PR ome#10 with the links to blosc libraries

Although this is technically sound, I am not favourable to this proposal in particular in the context a production deployment. As a single file, uber-JAR/fat JAR offers obvious deployment advantages but the embedding of the underlying dependencies creates real issues from a support/maintenance perspective. In addition, it makes it possible for the same dependencies to be shipped with different incompatible versions and be the source of runtime/loading issues.

Yes, you're right. Having a fat-jar in a production environment is not ideal but it can be useful to make tests under a different environment for fast deployement. I didn't replace the jar by the fat jar generation, but simply added it as an option.

To be complete, the way Glencoe solves this deployment issue is by declaring officially the omero-zarr-pixel-buffer as an extension of theOMERO.server bundle used by OMERO Plus. Adding the dependency to ivy.xml under https://github.com/ome/openmicroscopy/ allows the build system/Ivy dependency mechanism to resolve all the dependencies and copy them as individual JARs under lib/server

Thanks for sharing ; that's indeed a better idea for production. If I understand correctly, this declaration has to be added in OMERO.sever package (in a later release) ; it's not something that we can add as a config or equivalent, right ?