Deployment guide

Uwazi

Overview

Uwazi is an open-source platform from HURIDOCS for building and publishing structured document collections. Human rights defenders, legal teams, investigative journalists and researchers use it to turn scattered documents, case files and archives into a structured, fully searchable library. You define your own entity templates, upload documents with OCR-aware full-text search, relate records to one another, and choose what to publish to a public library.

This SecureAnyCloud image runs Uwazi 1.229.82 with its full backing stack on a single AWS instance, on Ubuntu 24.04.

What you get:

A browser-facing nginx on ports 80 and 443, proxying to the Uwazi Node.js application on port 3000
Three backing containers, published to the loopback interface only: MongoDB 7.0 (a single-node replica set) on port 27017, Elasticsearch 8.18 with the ICU analysis plugin on port 9200, and Redis 6.0 (the job queue) on port 6379. None of the database, search or queue ports are reachable from the network.
No live default credential. Uwazi ships a documented default administrator account (admin / change this password). This image overwrites the default password during the build, and on the first boot of every deployed instance it rotates the administrator account to a password unique to that instance, written to /root/uwazi-credentials.txt with mode 0600.
A fresh session secret and a self-signed TLS certificate, both generated on first boot
Two dedicated EBS volumes, mounted by filesystem UUID: the Docker data root at /var/lib/docker, holding the MongoDB datastore and the Elasticsearch index, and the application tier at /opt/uwazi, holding the Uwazi bundle and your uploaded documents. Both are independently resizable and separate from the operating system disk.

Prerequisites

An AWS account subscribed to the Uwazi listing on AWS Marketplace
An EC2 key pair in your target region for SSH access
A security group that allows inbound TCP 22 (SSH), 80 (HTTP) and 443 (HTTPS) from the addresses you will use. The database, search and queue ports need no inbound rule and should stay closed.
An instance size of m5.large (2 vCPU, 8 GB RAM) for small collections and evaluation, or m5.xlarge (4 vCPU, 16 GB RAM) for active collections with heavy indexing. Elasticsearch reserves a 2 GB heap.

Launching the instance

From the AWS Marketplace console

Open the Uwazi listing and choose Continue to Subscribe, then Continue to Configuration.
Select the region and the Uwazi 1.229.82 on Ubuntu 24.04 delivery option, then choose Continue to Launch.
Choose an instance type of m5.large or larger, your key pair, and a security group with ports 22, 80 and 443 open.
Launch the instance. Allow two to three minutes on first boot for the instance to rotate its administrator password and start the stack.

From the AWS CLI

aws ec2 run-instances \
  --image-id <ami-id-from-listing> \
  --instance-type m5.large \
  --key-name <your-key-pair> \
  --security-group-ids <sg-with-22-80-443> \
  --block-device-mappings '[{"DeviceName":"/dev/sda1","Ebs":{"VolumeSize":30,"VolumeType":"gp3"}}]' \
  --tag-specifications 'ResourceType=instance,Tags=[{Key=Name,Value=uwazi}]'

The listing's launch page shows the AMI id for each OS variant.

Connecting to your instance

Connect over SSH with your private key and the instance's public IP. For the Ubuntu 24.04 variant, the SSH login user is ubuntu.

ssh -i /path/to/your-key.pem ubuntu@<public-ip>

Retrieving the administrator login

On first boot, the administrator username and a per-instance password are written to a root-only file. Read it over SSH:

sudo cat /root/uwazi-credentials.txt

The file shows the site URL, the administrator username (admin) and the password generated for this instance:

uwazi.url=http://<public-ip>/ uwazi.url.https=https://<public-ip>/ (self-signed; browser will warn) UWAZI_ADMIN_USERNAME=admin UWAZI_ADMIN_PASSWORD=<generated-per-instance>

The default Uwazi password (change this password) is removed and does not authenticate.

Signing in

Browse to http://<public-ip>/ and sign in with the username and password from the credentials file.

The image serves HTTPS on port 443 with a self-signed certificate, so browsers show a warning there. See Enabling trusted HTTPS below.

The library

After you sign in, you land on the library, the central view of your collection. Every record appears as a card, with a search box and faceted filters on the right. Elasticsearch powers full-text search across the metadata and the extracted text of every uploaded document.

Use the search box for keyword search, and the filters panel to narrow results by template, publication status and any metadata property. Choose Create entity or Upload PDF(s) to create to add records.

Working with records

Open a record to see its detail view, with its primary documents, supporting files and relationships to other records. From here you can add a PDF, which is OCR-processed and made searchable. You can also attach supporting files, edit metadata, share the record, or relate it to other entities in your collection.

Administration

Open the settings area (the gear icon, top right) to shape your collection. It requires the per-instance administrator login, and there is no default administrator.

Key sections:

Templates (under Metadata) define your data model. Create an entity type and add properties (text, date, select, relationship, geolocation and more) so records match your domain.
Thesauri hold controlled vocabularies that you can reference from template properties.
Relationship types define the kinds of connection that records can have.
Users & Groups manage who can access the instance and what they can do.
Collection controls the public library: whether the collection is published, the landing page and the site name.
Languages and Translations run Uwazi as a multilingual collection.

The dedicated data volumes

The image ships two EBS data volumes, each on its own filesystem and mounted by UUID. List them:

df -h /var/lib/docker /opt/uwazi

Filesystem Size Mounted on /dev/nvme2n1 40G /var/lib/docker /dev/nvme1n1 30G /opt/uwazi

/var/lib/docker holds the MongoDB datastore and the Elasticsearch index, which are the containers' data. /opt/uwazi holds the application bundle and the local file store for uploaded documents.

To grow either tier, expand the EBS volume in the AWS console, then extend the filesystem with sudo resize2fs <device>.

Managing the services

systemd and docker manage the application and its backing services:

systemctl status uwazi uwazi-infra nginx

sudo docker ps

uwazi-elasticsearch uwazi-elastic-icu:8.18.0 Up uwazi-redis redis:6.0.19 Up uwazi-mongo mongo:7.0 Up

uwazi-infra.service brings up the Elasticsearch, MongoDB and Redis containers; uwazi.service runs the Node.js application; nginx.service is the reverse proxy. Run a quick health check:

curl -sS -o /dev/null -w 'GET / -> %{http_code}\n' http://localhost/

Enabling trusted HTTPS

The image serves HTTPS on port 443 with a self-signed certificate generated per instance, so browsers show a warning. To use a trusted certificate, point a domain at the instance, install certbot and obtain a Let's Encrypt certificate:

sudo snap install --classic certbot
sudo certbot --nginx -d <your-domain>

certbot edits the nginx configuration in place and sets up automatic renewal.

Backup and maintenance

Database. Back up MongoDB from inside its container, for example with sudo docker exec uwazi-mongo mongodump --archive=/data/db/uwazi.dump --db=uwazi, then copy the archive off the instance.
Uploaded files. The local file store lives under /opt/uwazi/data. Snapshot the /opt/uwazi EBS volume or copy the directory.
Search index. You can always rebuild the Elasticsearch index from MongoDB, so database and file backups are enough for recovery.
EBS snapshots. The simplest full backup is an EBS snapshot of both data volumes.

Support

SecureAnyCloud engineers back every deployment and are available around the clock by email and live chat.

Email: sales@secureanycloud.com
Critical issues (service down, data loss risk): one hour average response
Support covers deployment and sizing, MongoDB and Elasticsearch administration and backup, TLS termination, Uwazi upgrades and performance tuning.

Uwazi is a trademark of HURIDOCS. All product and company names are trademarks or registered trademarks of their respective holders. Their use does not imply any affiliation with or endorsement by them.

Deploy on AWS

Launch Uwazi on AWS with 24/7 support from SecureAnyCloud.

View on Marketplace

Need Help?

Our support team is available 24/7.

sales@secureanycloud.com

Deploy on AWS