jama-CERTIC 0.6.1

APIs et interfaces de stockage de médias.

Jamā (जमा)

Jamā is a Django-based media repository application developed at CERTIC, Université de Caen Normandie. It provides APIs and user interfaces for storing, organizing, enriching, and serving collections of media resources.

It is packaged as jama-CERTIC and installs a jama command, which behaves like a standard Django management command entry point.

Features

• Projects, collections, resources, files, metadata, and access control.
• JSON-RPC API and web UI.
• Chunked file uploads and hash-based source-file storage.
• Background media processing with Django Tasks and django-tasks-db.
• IIIF tiled image generation for image and document resources.
• HLS generation for videos.
• OCR and ExifTool metadata extraction.
• Optional ARK identifier integration.
• Project snapshot export and restore commands.
• Optional PostgreSQL/PostGIS deployment; SQLite is available for small or test instances.

Requirements

Jamā requires Python 3.13 and Django 6.

Some features depend on external command-line tools that must be installed on the host system:

• ImageMagick (convert) for image conversion.
• Poppler (pdftoppm, pdftotext) for PDF processing.
• libvips (vips) for IIIF tiled image generation.
• Tesseract for OCR.
• ExifTool for technical metadata extraction.
• FFmpeg/FFprobe for video processing and HLS generation.

For production deployments, use a real web server, a separate task worker, and PostgreSQL when the instance will handle significant traffic or concurrent use.

Installation

pip install jama-CERTIC

Initialize the database and create an administrator account:

jama migrate
jama createsuperuser

Start a development server:

jama runserver

By default, Jamā stores persistent data under $HOME/.jama/.

Background Tasks

Jamā uses Django Tasks with the database backend provided by django-tasks-db. Start at least one worker to process media jobs such as IIIF tiling, OCR, HLS generation, ExifTool extraction, ARK assignment, and bulk metadata updates:

jama db_worker

Recurring tasks are registered and run through django-crontask:

jama crontask --no-heartbeat

In production, run the web process, one or more db_worker processes, and the cron process separately, for example with systemd.

Configuration

At startup, Jamā reads environment variables and also loads an env file from JAMA_VAR_DIR. If the file does not exist, Jamā creates it automatically with documented defaults.

Important variables include:

JAMA_VAR_DIR="$HOME/.jama"
JAMA_SECRET="change-me"
JAMA_SITE="http://localhost:8000/"
JAMA_STATIC_ROOT="$HOME/.jama/static"

JAMA_DB_ADAPTER="sqlite"          # use another value for PostgreSQL
JAMA_SQLITE_DB_PATH="$HOME/.jama/db.sqlite3"
JAMA_DB_HOST="localhost"
JAMA_DB_PORT="5432"
JAMA_DB_NAME="django"
JAMA_DB_USER="django"
JAMA_DB_PASSWORD="django"

JAMA_FILES_DIR="$HOME/.jama/media_source_files"
JAMA_IIIF_DIR="$HOME/.jama/iiif"
JAMA_IIIF_PROCESSING_DIR="$HOME/.jama/processing"
JAMA_IIIF_ENDPOINT="http://localhost/iip/IIIF="
JAMA_HLS_DIR="$HOME/.jama/hls"
JAMA_HLS_ENDPOINT="http://localhost:8000/hls/"

See configuration.md in the source repository for the complete list of supported settings.

Useful Commands

jama --help
jama collectstatic
jama listprojects
jama newjamaproject "Project title"
jama addlocalfiles /path/to/files username PROJECT_ID --extensions .jpg .tif
jama ensureiiif
jama snapshotproject PROJECT_ID /path/to/snapshot --include-files
jama restoreproject /path/to/snapshot "Restored project"

The jama repl command starts a Django-aware interactive shell with commonly used Jamā models and helpers imported.

Project Snapshots

Jamā can export a project as a restorable snapshot. A snapshot is a directory containing NDJSON data files and a manifest.json file.

List projects and their identifiers:

jama listprojects

Export database data only:

jama snapshotproject PROJECT_ID /path/to/snapshot

Export database data and original source files:

jama snapshotproject PROJECT_ID /path/to/snapshot --include-files

Restore a snapshot into a new project:

jama restoreproject /path/to/snapshot "Restored project"

Replace an existing project while keeping its identifier:

jama restoreproject /path/to/snapshot "Existing project" --replace-in-place

When --replace-in-place is used, Jamā creates a safety snapshot before replacing the project. Source files are optional in snapshots; without --include-files, the database rows are restored but the original files must already be present in Jamā storage for media resources to be fully usable.

Derived IIIF and HLS files are not included in snapshots. They are regenerated after restore when the source files are available. Annotations are not included in the current snapshot format.

IIIF Notes

Jamā generates tiled image files and expects an IIIF-compatible image server to serve them. IIPImage and Cantaloupe are typical choices. The exact JAMA_IIIF_ENDPOINT, path separator, and WebP settings depend on the chosen server.

For Cantaloupe 5.x, a common configuration is:

JAMA_USE_WEBP=0
JAMA_IIIF_PATH_SEPARATOR="%2F"
JAMA_IIIF_ENDPOINT="http://localhost:8182/iiif/2/"

Documentation and Source

The project repository is:

https://git.unicaen.fr/certic/jama

The source repository contains additional documentation, configuration details, and example systemd units.