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 client domain (https://client.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

Upgrading

Note: Run these commands from your base project directory (the folder containing your recogito-studio repository) so the relative paths match up.

Note: Check the latest release for any version-specific upgrade notes that may be missing from this guide, such as new required environment variables.

1. Update repositories

To upgrade a self-hosted instance, pull the latest revision of the self-hosting recogito-studio repo to the server running the docker container.

# fresh clone
git clone --single-branch --branch main --depth 1 https://github.com/recogito/recogito-studio

# or, if you already have it checked out
cd recogito-studio
git checkout main
git pull

In addition, pull the most recent, stable versions of the recogito-client and recogito-server repositories from GitHub.

cd ..

# fresh clones
git clone --single-branch --branch main --depth 1 https://github.com/recogito/recogito-client
git clone --single-branch --branch main --depth 1 https://github.com/recogito/recogito-server

# or, if you already have them checked out
cd recogito-client
git checkout main
git pull

cd ../recogito-server
git checkout main
git pull

cd ..

2. Update client config.json

Replace the default client configuration file with your live environment’s custom config.json.

If you have made any manual configuration changes (such as branding), ensure those are propagated here.

rm -f ./recogito-client/src/config.json
cp ./recogito-studio/docker/config/config.json ./recogito-client/src/config.json
cd ./recogito-client

3. Update .env

Ensure all environment variables from ./docker/.env.example are in ./docker/.env, as new required variables may have been added since your install.

Copy your live .env file into the client code directory and export the variables to the shell. This is critical because the build process needs to read these variables (like SITE_URL) to securely configure the frontend.

rm -f .env
cp ../recogito-studio/docker/.env .env
set -a && source .env && set +a

4. Build the Docker image

Instruct Docker to build a new image named recogito-studio-client:latest from scratch. The --no-cache flag ensures no outdated code or configurations accidentally carry over into the new build.

docker build --no-cache -t recogito-studio-client:latest .
cd ..

5. Update server config.json

Because the backend runs on a pre-built Supabase Postgres image, upgrading the server primarily means updating the database schema to match the latest application requirements.

The first step is to ensure the server config.json has all of the latest Roles and Policies, which should be up to date from the latest version of the recogito-studio repo.

rm -f ./recogito-server/config.json
cp ./recogito-studio/docker/config/config.json ./recogito-server/config.json
cd ./recogito-server

6. Update the server schema

Download the necessary Node.js packages required to run the migration scripts locally.

npm install

Then, use the Supabase CLI tool to push any new SQL schema changes directly into your running PostgreSQL database.

PGSSLMODE=disable npx supabase db push --db-url postgresql://postgres:$POSTGRES_PASSWORD@localhost:$POSTGRES_PORT/postgres --include-all

Finally, run the create-default-groups.js script. This reads your config.json and automatically updates the PostgreSQL database roles and access policies to match the latest configuration.

node ./create-default-groups.js -f ./config.json
cd ..

7. Server restart and cleanup

With the new frontend image built and the database fully up to date, the final step is to swap out the old live application for the new one.

Instruct Docker Compose to specifically target the client container. It will gracefully shut down the old container and immediately spin up a new one using the fresh recogito-studio-client:latest image.

cd ./recogito-studio/docker
docker compose -f ./docker-compose.yml -f ./docker-compose.client.yml up -d --force-recreate client
cd ../..

Feel free to delete the recogito-client and recogito-server repositories, as they are no longer needed.

rm -rf ./recogito-client/
rm -rf ./recogito-server/

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