DSpace: the Java backend behind institutional repositories

The repository is the backend, not the whole product

The first thing to get right is what this code is. The README describes DSpace as open source software that is a turnkey repository application, and the README says it is used by more than 2,000 organizations and institutions worldwide to provide durable access to digital resources.

What lives in this repository is the backend. It is Java based and it provides a REST API along with other machine based interfaces, and the README names OAI-PMH and SWORD as examples of those. The REST contract itself is versioned separately, in the DSpace/RestContract repository, which is a detail worth noticing, because a contract that lives in its own repository is a contract that is meant to be read by the other side of the integration.

The user interface is a separate project. The frontend is built on the REST API and lives in the dspace-angular repository, and it has its own releases, its own issue tracker and its own documentation. The Downloads section of the README lists the two release feeds separately, backend and frontend, which tells you the two are versioned and shipped independently.

So when you evaluate DSpace, you are evaluating a service with an API, not a website. The interface can be replaced, the API can be integrated with something else, and the machine interfaces exist precisely so that other systems can talk to the collection without going through the interface at all.

Three major lines released on the same afternoon

The release history is unusual and worth reading carefully.

The three most recent releases are DSpace 8.5, DSpace 9.4 and DSpace 10.1, and all three were published on 2026-09-14 within about two hours of each other. That is not three versions of one line, it is three major lines that are all still being released from the same source tree.

For an institution, that is a choice rather than an inconvenience. A repository service holds years of deposited content, metadata and configured workflows, so the upgrade path matters more here than in most software. The README points to a wiki page listing all past releases together with their current levels of support, which is the document to read before choosing a line, and it also points to per release documentation in the documentation wiki.

The default branch is main and the last push was on 2026-10-15, so the shared source is active. The version numbers in the repository metadata carry the label Backend / REST API Only, which is a reminder that the release artefact is the service and the API, not a user interface bundle.

The topic tags confirm the shape of the thing, namely dspace, java, open-access, open-source, repository and rest-api. This is infrastructure for institutions that hold scholarly and cultural material and need to expose it durably, and the audiences that decide to run it are usually library or repository staff rather than individual developers.

PostgreSQL and a servlet container are not optional

The README is unusually direct about prerequisites, and it is worth reading before anything else because it is the part that decides whether this fits your infrastructure.

As a Java web application, DSpace requires a database, PostgreSQL, and a servlet container, usually Tomcat, in order to function. The README points to the installation instructions in the documentation wiki for those and all other prerequisites.

That is the honest cost of the platform. This is not a static site with a search index, it is a stateful Java service with a relational store, and the operational surface that comes with it, a JVM, a servlet container, a database server, upgrades that need to be planned, is the price of the features an institutional repository needs, namely durable deposits, metadata, harvesting interfaces and a permission model.

The compose file makes the shape of that stack concrete, because it names the services. The database is reached through a jdbc:postgresql://dspacedb:5432/dspace URL and a Solr service appears as http://dspacesolr:8983/solr, so a search index is part of the deployment as well. The compose file also declares a custom network with a fixed subnet, 172.23.0.0/16, with the comment that defining it makes it easy to trust requests from host to container, and that the same value has to be reflected in the proxies.trusted.ipranges configuration if you change it.

The four Dockerfiles and the two compose files at the repository root, Dockerfile, Dockerfile.cli, Dockerfile.dependencies, Dockerfile.test, docker-compose.yml and docker-compose-cli.yml, exist to make that stack reproducible for development and for continuous integration.

The __P__ override syntax in the compose environment

One detail in the compose file is worth learning before you write any configuration, because it explains how the whole deployment is configured.

The environment section of the dspace service carries a comment that says the syntax below may look odd, but it is how to override dspace.cfg settings via env variables. The mapping is __P__ becomes a dot and __D__ becomes a dash, so dspace__P__dir becomes dspace.dir and google__D__metadata becomes google-metadata. The reason for the encoding is that environment variable names cannot contain dots, and DSpace's own configuration is a properties file with dotted keys.

The consequence is that a deployment can be reconfigured without editing a file inside the image. The commented examples show dspace__P__dir set to /dspace, dspace__P__server__P__url set to http://localhost:8080/server and dspace__P__ui__P__url set to http://localhost:4000.

The same trick carries values that are not DSpace settings. The database URL is written as db__P__url with a default value, the Solr endpoint as solr__P__server, and there is a comment that the db.url must point at the dspacedb image to make sure the right database is used.

One value is not a default but a requirement. The SSR URL is set to the container name so that the UI can contact the container directly in production mode, with a comment explaining that this is necessary because the Angular compose file uses production mode by default. If you change that URL and the interface cannot reach the backend, this line is the reason and the fix.

The service names, dspacedb and dspacesolr, are also part of the contract with the configuration, since the same names appear in the URLs.

The Dockerfile deliberately skips the verification checks

The main Dockerfile is a two stage build, and the first stage is the interesting one because of what it switches off.

The build stage starts from the dependency image, copies the source and runs a Maven package with a set of flags set as an environment variable. The comment above the flags explains them: they ensure that the test environment is skipped and that all code verification checks are skipped, and the comment says these flags speed up the compilation as much as reasonably possible.

ENV MAVEN_FLAGS="-P-test-environment -Denforcer.skip=true -Dcheckstyle.skip=true -Dlicense.skip=true -Dxml.skip=true"
RUN mvn --no-transfer-progress package ${MAVEN_FLAGS} && \
  mv /app/dspace/target/${TARGET_DIR}/* /install && \
  mvn clean

Read the list of what is skipped. The enforcer is skipped, which is the plugin that normally checks that the build environment satisfies the required versions. Checkstyle is skipped, so the code style rules in checkstyle.xml and checkstyle-suppressions.xml are not applied to the image build. The licence check is skipped, which is the plugin that verifies the license headers, and the repository root holds a LICENSE.header file for that purpose. XML validation is skipped as well.

None of that is a criticism of the project, it is the standard trade for a container build, where you want speed and where the same checks run in the continuous integration pipeline instead. But it does mean the image is not the place where those rules are enforced, and it is a useful reminder that the checks exist elsewhere in the toolchain.

The rest of the file is equally pragmatic. The default JDK version is 21, and it is an argument so a different one can be passed at build time. The build output is moved into an /install directory, and the server webapp is then removed from the image to keep it small, which tells you the container is expected to run the API rather than the traditional web application.

Tests are disabled by default and switched on with skip flags

The testing section explains something that trips people up the first time they run the build.

By default, in DSpace, unit tests and integration tests are disabled. They do run automatically, but in GitHub Actions, for all pull requests and code commits. So the local build is fast and the pipeline is where the tests happen.

Turning them on locally is a matter of inverting the skip flags. To run both suites:

mvn install -DskipUnitTests=false -DskipIntegrationTests=false

To run only the unit tests, which the README attributes to the maven-surefire-plugin:

mvn test -DskipUnitTests=false

To run only the integration tests, via the maven-failsafe-plugin:

mvn install -DskipIntegrationTests=false

The single test invocations are the part that saves the most time in a large codebase. Unit tests are selected with -Dtest=[full.package.testClassName] and integration tests with -Dit.test=[full.package.testClassName], and in both cases the README insists on -DfailIfNoTests=false, with a comment explaining that it is required to skip tests in other modules. A single test method can be selected with a # suffix, for example -Dtest=[full.package.testClassName]#[testMethodName].

To run only the tests of one module, the README gives a two step recipe, since other modules have to be installed into your ~/.m2 first. You run mvn clean install in the source root, then move into a module subdirectory such as dspace-server-webapp and run the test command from there.

The Docker boundary and the machine interfaces

Two limits define the shape of an adoption decision, and they point in opposite directions.

The first is the container story, and the README states it without hedging: at this time, there are no production ready Docker images for DSpace. What there are are quick start Docker Compose scripts for development or testing purposes, with a pointer to the compose README in the dspace source tree. The images in the repository are build inputs for that quick start, not a supported deployment product. If your plan is to run the service in containers in production, that plan needs another answer, and the installation instructions in the documentation wiki are where to look.

The second is the alternative to building an integration. The backend exposes a REST API, but it also provides other machine based interfaces such as OAI-PMH and SWORD. The difference in approach matters for anyone wiring a collection into other systems. A REST integration is a modern API with a versioned contract, rich enough to drive the Angular frontend and to carry the full object model of an item, its metadata and its permissions. OAI-PMH is a harvesting protocol for metadata records, narrow and standardised, which is what a library aggregator or a discovery layer speaks. SWORD is a deposit protocol, for pushing packages into the repository from elsewhere.

So a repository that only needs to be harvested or to receive deposits does not need a REST client at all, and a service that needs to drive the user interface does. The three interfaces sit at different levels of ambition, and picking the right one is the difference between an integration that works and one that fights the platform.

For help, the README points at three public mailing lists, one for general discussion and announcements, one for technical support and one for developers, plus the DSpace tag on Stack Overflow, and a network of registered service providers for teams that would rather hire someone to install, upgrade, customise or host the platform.

Editorial conclusion

Adopt DSpace if you are running an institutional repository or a digital asset collection that has to expose its holdings to harvesters and to a modern web interface, and if you have someone who can own the Java, PostgreSQL and Tomcat stack. Do not adopt it on the assumption that the Docker images will carry a production deployment, because the README states plainly that production ready images do not exist, and do not adopt it for a small collection that a static site and a file store would serve. Verify first which of the maintained release lines you will run, that the REST contract version matches the frontend you pair it with, and that the installer steps for your release in the documentation wiki are the ones you follow.

Frequently asked questions

Official sources

1. DSpace/DSpace on GitHub
2. License: BSD-3-Clause
3. Project website
4. README
5. Releases