feat(docker): run Handle server as a separate service (not embedded)

[MatusBeke]

What

Runs the DSpace Handle server as a separate service instead of the one embedded
in the backend. This is the "take the Handle server out of the backend, keep only
the standalone one" change on the deployment side.

Adds one file — docker/docker-compose-handle.yml — an overlay that:

1. Stops the backend from starting the embedded Handle server — overrides the
   dspace entrypoint with the same script as docker-compose-rest.yml but with the
   /dspace/bin/start-handle-server line removed.
2. Enables the remote-resolver endpoints — handle.remote-resolver.enabled = true
   (/server/listprefixes, /listhandles, /resolve).
3. Adds a standalone dspace-handle-server service (image from
   dataquest-dev/docker-handle-server) that resolves through the backend REST API,
   waits for the backend on startup, and never touches the database.

client -> dspace-handle-server(:8000) --HTTP /server/resolve--> dspace (backend) -> dspacedb

Usage

Include the overlay last (its entrypoint override must win; the network ipam from
docker-compose-rest.yml is preserved):

docker compose -p d7 \
  -f docker/docker-compose.yml \
  -f docker/docker-compose-rest.yml \
  -f docker/docker-compose-handle.yml up -d

Ports/endpoint are configurable via .env (HANDLE_HTTP_PORT, HANDLE_NATIVE_PORT,
DSPACE_HANDLE_ENDPOINT, DSPACE_HANDLE_IMAGE).

Tested

• docker compose config merges cleanly: backend entrypoint no longer contains
  start-handle-server, resolver is enabled, the standalone service is added, and the
  network subnet from docker-compose-rest.yml is preserved.
• The equivalent stack was run live: with the embedded server disabled, the standalone
  Handle server loaded all prefixes from the backend and resolved handles
  (responseCode: 1), verified in real time (a handle inserted into Postgres was
  immediately resolvable through the standalone server).

Related

• dataquest-dev/docker-handle-server#3 — makes that image clone-and-run friendly
  (default remote-resolver config.dct, .env.example, LF fix). This overlay works
  with the current published image regardless, patching the config at container start.

Notes / follow-ups

• Opt-in overlay — default behaviour (embedded Handle server) is unchanged unless this
  file is included.
• Per-deployment Handle keys / prefix registration on handle.net remain deployment steps.

[Copilot]

Pull request overview

This PR introduces a Docker Compose overlay to run the CNRI Handle server as a standalone service, while configuring the DSpace backend to use the remote-resolver REST endpoints instead of starting the embedded Handle server.

Changes:

• Adds docker/docker-compose-handle.yml overlay that disables embedded Handle startup by overriding the backend entrypoint.
• Enables remote-resolver endpoints via handle.remote-resolver.enabled = true (env override).
• Adds a dspace-handle-server service that waits for the backend and resolves through the backend REST API.

Suppressed comments (2)

docker/docker-compose-handle.yml:37

• This overlay stops the embedded Handle server, but (unless overridden here) the dspace service will still publish the embedded Handle ports inherited from docker-compose-rest.yml. That leaves unused ports exposed and will conflict once dspace-handle-server publishes the replacement ports (Compose will fail with “port is already allocated”). Override dspace.ports in this overlay to only publish the backend + debug ports.

  dspace:
    environment:
      handle__P__remote__D__resolver__P__enabled: 'true'
    entrypoint:
      - /bin/bash

docker/docker-compose-handle.yml:60

• Defaulting HANDLE_HTTP_PORT to 8000 will conflict with the backend’s published debug port (800${INSTANCE}, typically 8000 when INSTANCE=0). Use a non-conflicting default (and ideally align with the embedded Handle HTTP port previously exposed by docker-compose-rest.yml: 8010 for INSTANCE=0).

      - published: ${HANDLE_HTTP_PORT:-8000}
        target: 8000
        host_ip: ${HOST_IP:-127.0.0.1}

---

💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.