Uwazi Document Collections on AWS User Guide
Overview
This image runs Uwazi, the open source platform from HURIDOCS for building and publishing structured document collections. Human rights defenders, legal teams, investigative journalists and researchers use Uwazi 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.
The stack runs on one instance. A browser reaches nginx on ports 80 and 443, nginx proxies to the Uwazi Node.js application on port 3000, and the application stores its data in three 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.
Uwazi ships a documented default administrator (admin / change this password). This image never ships that credential live: the default password is overwritten during the build, and on the first boot of every deployed instance an administrator account is rotated 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 are generated on first boot as well.
Two dedicated EBS volumes ship with the image and are 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 allowing 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.
- Recommended instance size: m5.large (2 vCPU, 8 GB RAM) for small collections and evaluation; 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 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, and give the instance two to three minutes on first boot 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 AMI id for each OS variant is shown on the listing's launch page.
Connecting to your instance
Connect over SSH as the default login user for your operating system variant. The table below lists the login user per variant; use your private key and the instance's public IP.
| OS variant | SSH login user |
|---|---|
| Ubuntu 24.04 | ubuntu |
ssh -i /path/to/your-key.pem ubuntu@<public-ip>
Retrieving the administrator login
The administrator username and the per instance password are written to a root only file on first boot. Read it over SSH:
sudo cat /root/uwazi-credentials.txt
You will see 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) has been 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 library
After signing in you land on the library, the central view of your collection. Every record is shown as a card, with a search box and faceted filters on the right. Full text search runs across the metadata and the extracted text of every uploaded document, powered by Elasticsearch.
Use the search box for keyword search, the filters panel to narrow by template, publication status and any metadata property, and Create entity or Upload PDF(s) to create to add records.
Working with records
Open a record to see its detail view: primary documents, supporting files and its relationships to other records. From here you can add a PDF (which is OCR processed and made searchable), attach supporting files, edit metadata, share the record, or relate it to other entities in your collection.
Administration
The settings area (the gear icon, top right) is where you shape your collection. It requires the per instance administrator login; 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 you can reference from template properties.
- Relationship types define the kinds of connection 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:
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 (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
The application and its backing services are managed with systemd and docker:
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. 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 for a domain that resolves to 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
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/uwaziEBS volume or copy the directory. - Search index: the Elasticsearch index can always be rebuilt from MongoDB, so database and file backups are sufficient for recovery.
- EBS snapshots: the simplest full backup is an EBS snapshot of both data volumes.
Support
Every deployment is backed by cloudimg engineers, available around the clock by email and live chat.
- Email: support@cloudimg.co.uk
- 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. Use of them does not imply any affiliation with or endorsement by them.