Self-Hosting Guide

Recogito-Studio is ready for self-hosting and these instructions detail the steps necessary for deployment on Ubuntu Linux, v24 (although many earlier versions will also work as well). The deployment strategy utilizes Docker, Docker Compose, and Nginx.

In the example below we will install Recogito Studio on a Digital Ocean Droplet. Digital Ocean is a well-regarded cloud hosting platform known for its ease of use and competitive pricing, but the instructions are easily translated to other cloud platforms or on-premises data centers.

System Architecture

Components

RS Supabase

Most of the Supabase processes, plus MinIO for object storage, and Cantaloupe as a IIIF server.

RS Client

The client application of Recogito Studio, written in Astro JS.

Postgres

Postgres server with Supabase Vector process and pgAdmin for database management.

Portainer

Container management tool for managing and monitoring the Docker environment.

Optional Components

• Trigger.dev - Background job system (required for plugin-ner)
• Stanford CoreNLP - Natural Language Processor (required for plugin-ner)

Required Domains

A full setup requires five DNS records pointing to your instance’s public IP:

• https://server.example.com - Main server
• https://client.example.com - Client application
• https://portainer.example.com - Container management
• https://pgadmin.example.com - Database administration
• https://minio.example.com - Object storage

For optional plugin-ner:

• https://trigger.example.com - Trigger.dev dashboard

System Requirements

• Operating System: Ubuntu Linux v24 (recommended)
• Memory: Minimum 4GB
• Storage: 50GB+ recommended
• Network: Public IP address with DNS access

Installation Steps

1. Create and Secure Your Server

Create a Digital Ocean Droplet

1. Start Droplet Creation

Begin by creating a new droplet in your Digital Ocean account.

2. Choose Operating System

Choose Ubuntu (latest version) as your operating system and select appropriate region and datacenter.

3. Configure Droplet Specifications

Choose Basic shared CPU, Regular SSD with minimum: 4GB Memory, 2 CPUs, 80GB SSD.

4. Select Authentication Method

Choose your preferred authentication method and enable automatic backups (recommended for production).

5. Finalize Droplet Creation

Review your settings and create the droplet.

6. Droplet Created Successfully

Once created, note the IPv4 address for your new droplet.

Set Up Non-Root User and Firewall

Connect to your server:

ssh root@your_server_ip

Update the system:

apt update
apt upgrade

Create a new user with sudo privileges:

adduser recogito
usermod -aG sudo recogito

Configure UFW firewall:

ufw app list
ufw allow OpenSSH
ufw enable
ufw status

Best practice is to not utilize the root login except in special circumstances. Go ahead and exit the instance and SSH in with the new recogito user.

exit
ssh recogito@your_server_ip

2. Install Nginx

Install and configure the web server:

sudo apt update
sudo apt install nginx

Adjust firewall for web traffic:

sudo ufw allow 'Nginx Full'
sudo ufw status

Verify Nginx is running:

systemctl status nginx

Test by navigating to http://your_server_ip - you should see the Nginx welcome page.

3. Install Dependencies

Git

Verify Git is installed:

git --version

Docker

Install via SNAP:

sudo snap install docker

NPM

Install Node Package Manager:

sudo apt install npm

4. Clone and Configure Recogito Studio

Clone the repository:

git clone --depth 1 https://github.com/recogito/recogito-studio.git
cd ./recogito-studio

Copy and edit environment variables:

cp ./docker/.env.example ./docker/.env
nano ./docker/.env

5. Critical Environment Variables

Update these required values in your .env file:

Security Passwords

• POSTGRES_PASSWORD: Secure password (12+ characters, alphanumeric)
• DASHBOARD_PASSWORD: Supabase dashboard password
• ORG_ADMIN_PW: Initial superuser password (admin@example.com)

JWT Configuration

Generate JWT secret:

openssl rand -base64 36

Use Supabase JWT Generator:

• JWT_SECRET: Generated secret above
• ANON_KEY: Generate with ANON_KEY payload
• SERVICE_ROLE_KEY: Generate with SERVICE_KEY payload

URLs and Access

• SITE_URL: Your server domain (https://server.example.com)
• ROOM_SECRET: Generate with openssl rand -base64 24
• MINIO_ROOT_USER/PASSWORD: MinIO dashboard credentials
• PGADMIN_ADMIN_EMAIL/PASSWORD: pgAdmin web access

6. Configure Nginx Routes

Copy and customize Nginx configuration files:

Client Configuration

You will need 5 URLs for this setup

• A client URL for accessing the Recogito Studio client
• A server URL for API calls
• A MinIO URL for accessing the MinIO dashboard
• A pgAdmin URL for accessing pgAdmin
• A Portainer URL for accessing the Portainer UI

sudo cp ./nginx.client.example.com /etc/nginx/sites-available/<your client url>
sudo nano /etc/nginx/sites-available/<your client url>

Replace client.example.com with your actual client domain.

Server Configuration

sudo cp ./nginx.server.example.com /etc/nginx/sites-available/<your server url>
sudo nano /etc/nginx/sites-available/<your server url>

Update:

• server_name with your server URL
• Access-Control-Allow-Origin headers with your client URL

Support Services

Repeat for remaining services:

sudo cp ./nginx.minio.example.com /etc/nginx/sites-available/minio.[yourdomain].com
sudo cp ./nginx.pgadmin.example.com /etc/nginx/sites-available/pgadmin.[yourdomain].com
sudo cp ./nginx.portainer.example.com /etc/nginx/sites-available/portainer.[yourdomain].com

Update nginx.conf

Add WebSocket support to /etc/nginx/nginx.conf:

sudo nano /etc/nginx/nginx.conf

Add to http block:

map $http_upgrade $connection_upgrade {
    default upgrade;
    '' close;
}

Enable Sites

Create symbolic links:

sudo ln -s /etc/nginx/sites-available/<your server url> /etc/nginx/sites-enabled/
sudo ln -s /etc/nginx/sites-available/<your client url> /etc/nginx/sites-enabled/
sudo ln -s /etc/nginx/sites-available/<your pgAdmin url> /etc/nginx/sites-enabled/
sudo ln -s /etc/nginx/sites-available/<your MinIO url> /etc/nginx/sites-enabled/
sudo ln -s /etc/nginx/sites-available/<your Portainer url> /etc/nginx/sites-enabled/

Test and restart:

sudo nginx -t
sudo systemctl restart nginx

7. SSL Certificates with Let’s Encrypt

Install Certbot:

sudo snap install core; sudo snap refresh core
sudo snap install --classic certbot
sudo ln -s /snap/bin/certbot /usr/bin/certbot

Generate certificates for each domain:

sudo certbot --nginx -d <your client url>
sudo certbot --nginx -d <your server url>
sudo certbot --nginx -d <your pgAdmin url>
sudo certbot --nginx -d <your MinIO url>
sudo certbot --nginx -d <your portainer url>

Verify auto-renewal:

sudo systemctl status snap.certbot.renew.service
sudo certbot renew --dry-run

8. Run Installation

Execute the installation script:

sudo bash ./install-self-hosted-docker.sh

Respond “Yes” to database push when prompted.

Testing Your Installation

Test Client Access

Navigate to your client URL (https://client.example.com). You should see the Recogito Studio interface.

Sign in with:

• Username: admin@example.com
• Password: Value from ORG_ADMIN_PW in your .env file

Test Studio Access

Navigate to your server URL (https://server.example.com) for Supabase studio access:

• Username: supabase
• Password: Value from DASHBOARD_PASSWORD in your .env file

Additional Resources

• Recogito Studio SDK - For adding plugins
• Plugin NER - Named Entity Recognition plugin
• Supabase Documentation - Platform usage details

What’s Next

Future documentation will cover:

• Configuration and UI customization
• SMTP setup for notifications
• Logging with Logflare integration
• External Postgres database configuration
• Production hardening and monitoring