Self-hosting

Deploy it with Docker

The downloader ships as a multi-arch container image (linux/amd64 and linux/arm64), listening on port 7000. Give it the services below and a handful of environment variables.

What you'll need

RO-Crate API

The source the app reads collections, items and files from.

API reference →

OIDC provider

An identity provider for single sign-on (issuer, client id & secret).

AWS S3 bucket

Stores the generated zip files that users download.

AWS SES

Sends the notification email containing the presigned download link.

Quick start

Put your configuration in a .env file (see the variables below) and run the image:

docker run

docker run -d \
  --name downloader \
  -p 7000:7000 \
  --env-file .env \
  ghcr.io/crate-works/downloader:latest

Then open http://localhost:7000.

Required environment variables

Variable	Description	Format
ROCRATE_API_BASE_URL	RO-Crate API endpoint	URL
OIDC_ISSUER	OIDC provider issuer URL	URL
OIDC_CLIENT_ID	OIDC client identifier	String
OIDC_CLIENT_SECRET	OIDC client secret	String
OIDC_REDIRECT_URI	OIDC callback URL	URL
SESSION_SECRET	Session encryption key	String (min 32 chars)
S3_BUCKET	S3 bucket for zip files	String
EMAIL_FROM	Sender email address	Email

AWS credentials are also required — provide AWS_ACCESS_KEY_ID and AWS_SECRET_ACCESS_KEY, or attach an IAM role if you run on AWS infrastructure.

Optional environment variables

Variable	Default	Description
NODE_ENV	development	Environment mode (development, production, test)
PORT	7000	Server port
OIDC_SCOPES	public openid profile email	OIDC scopes to request
AWS_REGION	ap-southeast-2	AWS region

Docker Compose

A complete compose.yaml with secrets pulled from your environment:

compose.yaml

services:
  downloader:
    image: ghcr.io/crate-works/downloader:latest
    ports:
      - '7000:7000'
    environment:
      - NODE_ENV=production
      - ROCRATE_API_BASE_URL=https://api.example.com
      - OIDC_ISSUER=https://idp.example.com
      - OIDC_CLIENT_ID=${OIDC_CLIENT_ID}
      - OIDC_CLIENT_SECRET=${OIDC_CLIENT_SECRET}
      - OIDC_REDIRECT_URI=https://app.example.com/api/auth/callback
      - SESSION_SECRET=${SESSION_SECRET}
      - S3_BUCKET=${S3_BUCKET}
      - EMAIL_FROM=noreply@example.com
      - AWS_REGION=ap-southeast-2
      - AWS_ACCESS_KEY_ID=${AWS_ACCESS_KEY_ID}
      - AWS_SECRET_ACCESS_KEY=${AWS_SECRET_ACCESS_KEY}
    restart: unless-stopped

Health check

The container is healthy when the root path responds:

bash

curl http://localhost:7000/

For the full architecture, build instructions and contribution guide, see the project README on GitHub.