alt text is a open-source solution for building and sharing document collections. Used by human rights and humanitarian organisations. It can also be a public website

It is a flexibile systems where

  • Entity (eg Leadership) has properties (eg Gender)
  • Entity has primary documents and or supporting files (eg photo)
  • Entity has have relationships to other Entities (eg State Entity - Ghana)

  • Template describes an Entity (eg Gender - drop down, Tenure as UN Secretary-General - date, State - relationship)
  • Thesauri - custom lists eg Gender - Male, Female, N/A
  • Relationship Types - (eg Leadership is related to another Entity called State) is the screenshot demo above

Dev version

update 5th Feb 24 - have given up using Dev as very slow to start up, and getting lock up errors when starting. My test environment on an ubuntu server is more reliable.

Runs Docker for all dependencies.

I had to install on my bare metal WSL instance

Node using then

nvm install 20


npm install --global yarn - 10.3.0

git clone
cd uwazi

# docker spinning up Mongo, Redis, S3, Elasticsearch
./run start

# install - can take a while
# 437s (on desktop)
yarn install

# 1. careful this does a blank state
#yarn blank-state

# 2. if you've done a pull to update a current install

# 64 seconds
yarn migrate 
# 38 seconds
yarn reindex

# spin up dev environment 
# many minutes
# sometimes it totally locks ups needing a wsl --shutdown
# try again a few times and it generally works
yarn hot

# http://localhost:3000/
# u: admin
# p: change this password now

# webpack-server (ie don't need filewatch)
yarn webpack-server

alt text

Running application locally.

alt text

Terminal showing output of yarn hot

Updating Problems

alt text

When updating the codebase I’ve had segfaults in the terminal which required a reboot. Also no errors, but terminals have all become unresponsive and can’t restart a terminal. Full reboot required.

While waiting for yarn hot to start, I can’t save from other processes in WSL.

Perhaps for testing using the production branch may be more stable.

Perhaps try production settings if more stable.

# open as admin
# takes 30 secs to shutdown
# sometimes need to do twice before it works
wsl --shutdown

[nodemon] app crashed - waiting for file changes before starting…

alt text

After doing a run start (is docker wasn’t up) I tried to run.. and it locked up wsl. Tried again and it worked.

Test and Prod shows beginning of build script.

See main notes in OneNote section uwazi20 Sys Admin guide

Run as a systemd service to survive a reboot

cd /etc/systemd/system/
sudo vim uwazi.service

Description=uwazi backend service for your-instance


ExecStart=/home/dave/.nvm/versions/node/v20.11.0/bin/node server.js




sudo systemctl daemon-reload
sudo systemctl enable uwazi.service
sudo systemctl start uwazi.service

It should survive a reboot now.

Migrating Data

As I’ve got multiple instances (including hosted where I’ve got no shell access), here is how I easily move the structure and data between instances:


Add thesaurus, name it, then import



Relationship Types

  • Content-Case
  • Content-Source

Templates (Entities)

Drag and drop (+ button is better) the desired properties. Make sure they are named exactly the same. Do and save 1 at a time (I’ve seen it crash out and lose changes)

Do this first and get a successful save before doing property attributes


Make sure date format is set to the same as the original instance.

  • Sources
  • Cases
  • Content

API Automation

I’ve been asked to integrate the with Uwazi. Essentially when a new link is archived, and when a tickbox is checked, then it should be automatically imported into Uwazi. is a handy wrapper to help in authentication and adding entities. API documentation

I can create a new entity:

I want to search for an entity based on a parameter

/api/templates - can give me the mongoid’s of Content or CASES

CSV manual import export


Prod is an open issue I’ve submitted about dependency versions of Mongo which stopped a bare metal install