omeka-s: a publishing system for collections that share a pool

The idea, and who it is for

The readme's description is two sentences, and the second one is the whole design.

Omeka S is a web publication system for universities, galleries, libraries, archives and museums. It consists of a local network of independently curated exhibits sharing a collaboratively built pool of items, media and their metadata.

So it is not one big site with everybody's content in it. It is many sites, each run by the people who own the collection, each with its own front end, its own design and its own editorial decisions, all drawing items from a shared pool that is built collaboratively.

That is a genuinely different architecture from the usual content management arrangement, and it solves a problem that museums and libraries actually have. A national archive with fifty partner institutions does not want one institution to curate everything, and it does not want fifty disconnected catalogues either. The pool is the collaboration; the local exhibit is the local voice.

And the pool is not just a pile of files. The repository's topic tags include linked data, and the dependency list includes a library for reading and writing resource description formats, which is what turns a shared pool into a shared description. The front end also includes two deep-zoom image viewers, which is the tool you need for a manuscript or a map that should be examined at high resolution rather than looked at.

The institution behind it is a non-profit corporation for digital scholarship based in Virginia, and the readme is careful about its legal position. The source code is under the copyleft licence, the name is a registered trademark, third-party copyright in the distribution is noted where it applies, and all rights not expressly granted are reserved. That is a more precise statement than most projects make about the difference between the code and the name, and it matters for a system that institutions deploy under their own brands.

Two install routes, and the steps they share

The install section gives two procedures, and reading them together tells you how the project expects to be deployed.

The first is from the source repository, and it is the longer one. It assumes a JavaScript runtime and its package manager are installed, it clones the repository into the web server's document root, and then it runs a first-time setup that is two commands: one to install the dependencies and one to run an initialisation task.

$ npm install
$ npx gulp init

Then there is a step that is the part everybody forgets on a first install: open the database configuration file and enter the database user name, password, database name and host, and note that the user and the database have to exist before that step rather than after it. Then the files directory has to be writable by the web server, and then you open the site in a browser to finish.

The second route is a release archive, and it is much shorter: download the first asset listed on the releases page, edit the same database configuration file, make the same directory writable, and open the site. No JavaScript toolchain, no initialisation task.

So the difference is whether you want the source or the artefact, and the three steps they share are the same three: the database credentials, the writable directory, and the browser.

That last one is a nice piece of design. The installation is not finished by a command; it is finished by loading the site, and the site then walks the administrator through the remaining configuration. Which means the same completion flow serves both routes, and a person who installs from a release and a person who installs from the source end up in the same place.

And the readme points out where the application code lives, under a directory named for the application, next to the modules and the themes. That is the extension model in one sentence: the core is an application, the plugins are modules, and the appearance is a theme.

Updating, and the four directories to save

The update section opens with a warning in italics that is worth taking literally: make a backup copy of your entire site and its database.

Then there are two procedures again, and the second one is the more interesting because it is a complete recipe for replacing a web application without losing what matters.

The source route is four steps. Pull the changes, using the branch that carries the latest releases rather than the development branch. Run a task that makes sure the dependencies are up to date. Compare the local configuration file against the distributed version of it, because some defaults may have changed and you may have to reconcile them, for instance a path particular to your server or the development mode settings. And then open the site and run the migrations that are needed.

That third step is the one that catches people. The distributed configuration file is the template, and the local one is yours, and a version bump can change the template in ways your copy has not absorbed. The readme says to compare them, and gives two examples of what might differ. A system that ships a diffable template for its configuration and tells you to compare it is doing the right thing, because the alternative, a configuration file that the update silently overwrites, loses every local setting.

The release route is longer and more physical. Download the archive. Copy the configuration directory, and the modules and themes directories, and the files directory. Remove all the application files and replace them with the ones from the archive. Put back your configuration file and the three directories you copied. And then run the migrations.

So the rule is: everything the application owns is disposable and comes from the archive, and four things are yours and are saved and restored by hand. The files directory in particular holds the uploaded media, and the modules and themes directories hold the local customisations, which are exactly the things a careless update destroys.

The readme does not say that last part explicitly, but the shape of the procedure says it: the four saved directories are the four that are not reproducible from the archive.

The build system, and the front end

The front end is built with a task runner, and the manifest shows the whole toolchain in one place.

The build dependencies are the pipeline itself: the task runner and its command line, a stylesheet compiler with a post-processor plugin, a renamer, a search and replace step, a zip step, a minifier for arguments, a glob helper, a post-processor, a prefixer, and a date formatting library. The last one is a small curiosity worth noting, because a date library in a build toolchain usually means the build stamps something with a date.

There is a task to create the release archive, which stores the result in a build directory, and a flag that omits the development dependencies of the PHP side so the package is smaller and suitable for end users. And the readme says the official releases follow exactly the same process, from a new clean checkout. That is a good practice: the artefact that people download is produced by the same command that a contributor can run, so there is no separate release machine whose configuration nobody else can reproduce.

The runtime dependencies are the interesting part, because they say what the interface is made of. Two of them are the deep-zoom image viewers, and having both is normal: one is the older and more capable of the pair and the other is the newer, and shipping both means the site can choose per use case. Then there is a dropdown library, a tree widget, a gallery, a sortable list library, a small table library, and a version comparison helper, which is there for the migration logic that has to decide whether a stored record needs upgrading.

The browsers list is short and conservative: the versions used by more than a small share of traffic, and the versions used by more than a small share in one country. Which tells you the project optimises for the institutions it serves rather than for the widest possible audience, which is the right trade for a cultural heritage system used by a few thousand organisations and their visitors.

And the whole front end is built with a stylesheet preprocessor and a grid system from that era, which is worth a sentence in itself: a system that universities deploy and keep for a decade is not going to have its asset pipeline rewritten every two years, so the toolchain ages with the installations.

The libraries, the standards and the legal position

The libraries section lists five and says, honestly, that these are among others.

A framework for the application layer, an object relational mapper, a library for reading and writing resource description formats, the test framework, and a JavaScript library. The third of those is the one that matters for this project, because it is what lets the shared pool be described in a way that other systems can consume, and it is why the linked data tag is on the repository rather than being aspirational.

The development standards section names three commitments. The coding style follows a published guide from the framework's own project, which is a good choice because it means the code reads like the surrounding ecosystem. The branching model is git-flow, which is a heavyweight model by today's standards and a sensible one for a project with many maintainers and long-lived branches. And the version scheme is semantic versioning, second edition.

The copyright section is the most careful paragraph in the readme. The code is copyright a non-profit corporation for digital scholarship and is distributed under the copyleft licence, with the full text in the licence file. The name is a registered trademark of that corporation. Third-party copyright in the distribution is noted where it applies. And all rights not expressly granted are reserved.

Read together, those four statements say something particular. The copyleft licence guarantees that anyone who modifies and redistributes the software releases the modifications. The trademark protects the name, which is what an institution puts on its own site. The third-party note handles the libraries whose licences require attribution. And the reservation of rights covers everything else, which in a project that also has documentation, a user manual and a brand is not nothing.

It is a mature position for a project that has been running for more than a decade, and it is the kind of legal clarity that makes an institution comfortable deploying it.

The repository, and the file layout

The top level of the repository is the deployment itself, and every entry has a job.

There is the entry point for the web server and the bootstrap file it includes, and a command line configuration file so that the same code can be driven from a terminal. There is the application directory, the modules directory, the themes directory, and the configuration directory, which together are the three extension points the readme mentions. There is the files directory, which holds the uploaded media and which the install instructions insist must be writable by the web server. There is a logs directory.

Then there are the files that a maintainer touches rather than a deployer. The composer manifests, which pin the PHP dependencies. The package manifests, which pin the front end ones. The build file for the task runner. And a set of configuration templates: a distributed Apache configuration file whose local counterpart is not checked in, and a coding standard configuration with its own module directory, which is how a project that enforces a published style guide does it without asking every contributor to install the tool in the right way.

And there is a directory whose name is a shorthand everybody in open source recognises. It is the configuration for a hosted translation service, and its presence says that the interface is translated and the translations are maintained somewhere with a workflow around them, rather than in a file that only one person can edit.

So the layout is the deployment, the extension points, the build, and the housekeeping. There is no separate development environment in the tree, no container file, and no infrastructure configuration, because this is a system that goes into an existing web host's document root, with a database that somebody creates by hand. That is a deliberate choice about what this software is: an application you install into a server you already have, not a service you run in a platform.

Editorial conclusion

Omeka S fits an institution that wants to present its own collections with its own editorial voice while sharing the underlying data with a network of peers, and it fits a developer extending a system with a documented module and theme model. It does not fit a project that needs a modern content management system with a rich plugin ecosystem. Verify first which of the two install routes you want, because the one from source is the one that continues to be maintained, and that you keep a copy of the four directories the update procedure tells you to save, because the release route replaces everything else in the tree and those four are what you put back afterwards.

Frequently asked questions

Official sources

1. Issues
2. License: GPL-3.0
3. omeka/omeka-s on GitHub
4. README
5. Releases