Metadata-Version: 2.4
Name: jama-CERTIC
Version: 0.6.5
Summary: APIs et interfaces de stockage de médias.
Project-URL: Repository, https://git.unicaen.fr/certic/jama
Author-email: Mickaël Desfrênes <mickael.desfrenes@unicaen.fr>
Maintainer-email: Mickaël Desfrênes <mickael.desfrenes@unicaen.fr>
License-Expression: CECILL-B
License-File: LICENSE.txt
Requires-Python: <4.0,>=3.13
Requires-Dist: ark-client-certic>=0.2.0
Requires-Dist: bpython>=0.25
Requires-Dist: django-auth-cli-certic>=0.1.6
Requires-Dist: django-cors-headers>=4.7.0
Requires-Dist: django-crontask>=1.1.3
Requires-Dist: django-modshib-certic>=0.5.6
Requires-Dist: django-revproxy>=0.13.0
Requires-Dist: django-stubs>=6.0.4
Requires-Dist: django-tasks-db>=0.12.0
Requires-Dist: django-vite>=2.1.3
Requires-Dist: django>=6.0.3
Requires-Dist: fusepy>=3.0.1
Requires-Dist: gunicorn>=25.3.0
Requires-Dist: jama-client-certic>=0.0.34
Requires-Dist: markdown2>=2.4.3
Requires-Dist: numpy>=2.1.3
Requires-Dist: opencv-python-headless>=4.6.0
Requires-Dist: openpyxl>=3.1.2
Requires-Dist: psycopg2-binary>=2.9.10
Requires-Dist: pyexiftool>=0.5.3
Requires-Dist: pymemcache>=4.0.0
Requires-Dist: pytesseract>=0.3.10
Requires-Dist: python-dotenv>=1.0.0
Requires-Dist: pyvips>=2.2.1
Requires-Dist: rich>=14.0.0
Requires-Dist: unidecode>=1.3.4
Description-Content-Type: text/markdown

# 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

```bash
pip install jama-CERTIC
```

Initialize the database and create an administrator account:

```bash
jama migrate
jama createsuperuser
```

Start a development server:

```bash
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:

```bash
jama db_worker
```

Recurring tasks are registered and run through `django-crontask`:

```bash
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:

```bash
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

```bash
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:

```bash
jama listprojects
```

Export database data only:

```bash
jama snapshotproject PROJECT_ID /path/to/snapshot
```

Export database data and original source files:

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

Restore a snapshot into a new project:

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

Replace an existing project while keeping its identifier:

```bash
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:

```bash
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.
