Skip to content

Local DSA Old Version (Forked Version)

Jump to bottom
Mohamed E. Masoud edited this page Jun 3, 2026 · 2 revisions

Running HistoJS with a Local Digital Slide Archive (DSA)

Why Use a Local DSA?

Several public DSA servers previously used by HistoJS are no longer available. Running a local DSA instance ensures that HistoJS remains fully functional and independent of external servers.

This guide describes the exact steps used to successfully run HistoJS with a local DSA instance based on this forked repository.

Prerequisites

Install:

sudo apt update
sudo apt install git docker.io python3-pip

Add your user to the Docker group:

sudo usermod -aG docker $USER
newgrp docker

Verify Docker:

docker --version
docker ps

Clone the forked old DSA Repository

git clone  https://github.com/Mmasoud1/digital_slide_archive.git
cd digital_slide_archive/ansible

Compatibility Fix for Modern Docker Python SDK

Older versions of DSA expect:

docker.version

to be a version string.

Modern Docker SDK versions expose:

docker.__version__

instead.

Open:

ansible/deploy_docker.py

Find:

if not (LooseVersion('1.9') <= LooseVersion(docker.version)):

Replace with:

if not (LooseVersion('1.9') <= LooseVersion(docker.__version__)):

This modification is required for modern Python and Docker installations.

Start DSA

From:

cd digital_slide_archive/ansible

Run:

python3 deploy_docker.py start

The first startup may take several minutes while Docker images are downloaded and configured.

When complete, open:

http://localhost:8080

Default credentials:

Username: admin
Password: password

Enable CORS for HistoJS

HistoJS communicates with DSA through the Girder API.

Without CORS enabled, browsers will block requests and HistoJS will show:

No JSON response for request
Cross-Origin Request Blocked
Access-Control-Allow-Origin missing

To fix this:

  1. Login as admin.
  2. Open:
Admin Console
→ Settings
→ Advanced Settings
  1. Locate:
CORS Allowed Origins
  1. Set:
*
  1. Click:
Save

After saving, HistoJS should immediately be able to communicate with DSA.

Configure HistoJS

Add the local DSA endpoint:

http://localhost:8080/api/v1

Example host entry:

Name: Local DSA
Path: http://localhost:8080/api/v1
image

(Optional) Verify DSA API

Test:

curl http://localhost:8080/api/v1/system/version

Expected output:

{
  "release": "...",
  "serverStartDate": "..."
}

Stop DSA

python3 deploy_docker.py stop

Restart DSA

python3 deploy_docker.py restart

Remove DSA Containers

python3 deploy_docker.py rm

This removes the containers but preserves data stored in:

~/.dsa

Persistent Data Location

By default DSA stores:

~/.dsa/

including:

~/.dsa/assetstore
~/.dsa/db
~/.dsa/logs

These directories should be backed up regularly.

Backup Working DSA Data

Create a backup:

tar -czvf dsa_backup.tar.gz ~/.dsa

Restore:

tar -xzvf dsa_backup.tar.gz -C ~

Backup Docker Images

To preserve a known working DSA installation:

docker save \
dsarchive/dsa_girder:latest \
dsarchive/dsa_worker:latest \
mongo:latest \
rabbitmq:management \
memcached:latest \
-o dsa_images.tar

Restore later:

docker load -i dsa_images.tar

This guarantees future availability even if images disappear from Docker Hub.

Recommended Long-Term Preservation

Keep:

  1. Forked DSA repository.
  2. Docker image archive (docker save).
  3. ~/.dsa backup.
  4. This installation guide.

With these four items, a fully working HistoJS + DSA environment can be restored even if public DSA servers are no longer available.

Clone this wiki locally