Local Development

This guide walks you through setting up a complete local development environment for Recogito Studio. Unlike the self-hosting guide which covers production deployment, this setup is optimized for development and testing.

Components

A local development environment consists of three main components:

Recogito Server

Supabase-based backend with PostgreSQL database, authentication, and storage. Runs locally via Supabase CLI.

Recogito Client

Astro/React frontend application for the user interface. Runs locally via Vite.

Config Tool

Optional web-based configuration management tool for policies, roles, and branding. Runs locally via Vite.

Required Software

Before starting, ensure you have the following installed:

Node.js (v18 or later) and npm
Git
Docker Desktop
Supabase CLI

Additional Requirements

There may be some additional requirements depending on how you intend to use your local setup.

IIIF service: When uploading and annotating images, Recogito Studio works primarily with IIIF. It is designed to integrate with IIIF Cloud, which can be easily run in a Docker container.
- Performant Software offers managed IIIF hosting through our IIIF Cloud instances; contact us for more information.
- Recogito Studio also supports external IIIF manifests out of the box.
- Finally, it is also possible to use a direct file upload to Supabase storage and then use your own IIIF service to transform images locally, but that is not currently well-supported and you may encounter issues.
Mail server: Recogito Studio will attempt to send transactional emails (invites, password reset, etc) through a configured outgoing mail server. You can use something like Mailpit or Ethereal Email, or set up an actual outbound mail account through a service like Postmark.
Trigger.dev: Required for running background jobs like project import/export and the NER plugin.

Setup Process

Phase 1: Database Setup (`recogito-server`)

Clone the recogito-server repository

git clone https://github.com/recogito/recogito-server.git
cd recogito-server

Start Supabase locally

Ensure Docker Desktop is running. Then:
Terminal window
```
supabase start
```
This command will:
- Download required Docker images
- Start all Supabase services
- Display access credentials and URLs
Note the output, especially:
- API URL: Local Supabase API access
- Database URL: Postgres database
- Studio URL: Supabase Studio, which allows local DB/auth/storage management through a GUI
- Publishable key or anon key: Your anonymous API key
- Secret key or service_role key: Your service role key
Run database migrations
Terminal window
```
supabase db reset
```
This will:
- Create all database tables
- Set up Row-Level Security policies
- Install database functions and triggers
- Apply all migrations
- Populate the policies table
(Optional) Generate a custom configuration with the config tool

If you want to customize roles, groups, authentication, branding, or dynamic text, Recogito Studio offers a configuration tool that can be run separately to generate a config.json.
If the default configuration is sufficient (it is for most development environments), you can skip this step.

To use the config tool, clone the repository from GitHub and install and run with NPM:
Terminal window
```
cd ..
git clone https://github.com/recogito/recogito-config.git
cd recogito-config
npm install
```
Copy the environment variables example file and populate with your own Supabase values:
Terminal window
```
cp .env.example .env
nano .env
```
Terminal window
```
VITE_SUPABASE_API_URL=<API URL from supabase start>
VITE_SUPABASE_SERVICE_KEY=<secret key from supabase start>
```
Then start the config tool:
Terminal window
```
npm start
```
This will serve the config tool from localhost:5174.

For more details on the available options, see the Configuration Tool Reference →.
Install dependencies and configure environment

From the root of the recogito-server repo, run:
Terminal window
```
npm install
```
This installs the packages needed for setup scripts. Then, prepare environment variables:
Terminal window
```
cp .env.example .env
nano .env
```
Update the following values:
Terminal window
```
SUPABASE_HOST=API URL from step 2
SUPABASE_SERVICE_KEY=secret key from step 2

# Test user passwords (all can use the same password for simplicity)
ORG_ADMIN_PW=password
PROFESSOR_PW=password
STUDENT_PW=password
TUTOR_PW=password
READER_PW=password
INVITE_PW=password
```
You can leave the group IDs alone if you skipped step 4, or based your configuration on the default-config.json. If you created custom groups, these values must be populated by UUIDs of Organization Groups.
Populate database with roles and groups

Run the following commands to populate the databse with default groups, roles, users, etc.
Terminal window
```
node create-default-groups.js -f config.json
node create-test-users.js -f config.json
```
If you created a custom configuration in step 4, use that JSON file instead of config.json.
Important Step
This step is required before creating users. It populates the database with:
- Roles (Org Admin, Org Professor, Project Admin, Layer Admin, etc.)
- Organization groups
- Project and layer default groups
- An admin user (admin@example.com)
The supabase db reset command only runs migrations - it doesn’t populate roles and groups from config.json.

Phase 2: Client Application Setup (`recogito-client`)

Install the application

Clone the recogito-client repository:
Terminal window
```
cd ..
git clone https://github.com/recogito/recogito-client.git
cd recogito-client
```
And install with NPM:
Terminal window
```
npm install
```

Create environment file

cp .env.example .env
nano .env

Update with your local values:

   ###############################################################################
   # Public variables
   # (Variables beginning with PUBLIC_ are exposed to both server and client)
   ###############################################################################

   # Supabase connection
   PUBLIC_SUPABASE="https://your-project.supabase.co"
   PUBLIC_SUPABASE_API_KEY="your-anonymous-key"

   # IIIF (image server) configuration
   PUBLIC_IIIF_CONFIGURATION="IIIF_CLOUD"  # or "SUPABASE_CANTALOUPE"
   # PUBLIC_IIIF_CANTALOUPE_PATH="/iiif"  # uncomment if using SUPABASE_CANTALOUPE

   # Optional – Enable email/password invites from the UI
   # When TRUE, Org Admins can invite email/password users from the User Management UI
   PUBLIC_ENABLE_USER_INVITE=TRUE

   # Optional - Usersnap feedback form
   # PUBLIC_USERSNAP_GLOBAL_API_KEY="usersnap-global-api-key"
   # PUBLIC_USERSNAP_PROJECT_API_KEY="usersnap-project-api-key"

   # Optional – External help/FAQ page
   # PUBLIC_HELP_REDIRECT="https://help.example.com"

   ###############################################################################
   # Server-only secrets
   # (Never exposed to browser)
   ###############################################################################

   # Secret 'salt' to compute the realtime room identifiers
   ROOM_SECRET="your-room-secret"

   # Secret service key for server-side Supabase clients
   SUPABASE_SERVICE_KEY="your-supabase-service-key"

   # Optional: Server-only Supabase URL.
   # Use this if your Astro server runs in an environment where it must reach
   # Supabase using a different URL (e.g. internal/private network, Docker, VPC).
   # If not set, PUBLIC_SUPABASE is used for both server and client.
   # SUPABASE_SERVERCLIENT_URL="http://supabase:8000"

   ###############################################################################
   # Trigger.dev (Background jobs, import/export, NER plugin)
   ###############################################################################
   TRIGGER_SECRET_KEY=<your secret key>
   TRIGGER_SERVER_URL=http://localhost:3040/
   # TASK_PAYLOAD_OFFLOAD_THRESHOLD=5242880

   ###############################################################################
   # IIIF Cloud (image server) configuration
   ###############################################################################
   IIIF_URL="http://www.example.com/iiif/public/resources"
   IIIF_KEY=<your iiif cloud api key>
   IIIF_PROJECT_ID=<iiif cloud project uuid for this app>

   ###############################################################################
   # Email - Used for transactional emails: invites, notifications, etc.
   ###############################################################################
   MAIL_HOST=<your email host>
   MAIL_PORT=<your email port>
   MAIL_USERNAME=<your email username>
   MAIL_PASSWORD=<your email password>
   MAIL_FROM_ADDRESS=<the from address for emails>
   # Base64-encoded 256-bit key (e.g. generated with: openssl rand -base64 32)
   INVITE_CRYPTO_KEY=<base64 encoded 256-bit cryptographic key>

Deploy configuration file (optional)

The client repository includes a default src/config.json that works for basic setup. You can use it as-is, or:

Copy the config.json you generated with the config tool:
Terminal window
```
cp /path/to/downloaded/config.json src/config.json
```
Or use the default from the server repo:
Terminal window
```
cp ../recogito-server/config.json src/config.json
```
Start the development server
Terminal window
```
npm start
```
The client will be available at http://localhost:4321 (or another port if that port is in use).
Access the application
- Open the URL shown in the terminal (typically http://localhost:4321)
- You should see the Recogito Studio login page
- Sign in with a test user:
  - Email: admin@example.com
  - Password: password (or whatever you set in Phase 1 step 5 for ORG_ADMIN_PW)

Building

If you would like to build and run the application as a standalone service, using Node, run:

npm run build-node

Then you may start the service using:

node ./dist/server/entry.mjs

This will use the Node adapter for Astro (astro.config.node.mjs). Building with npm run build instead will use the Netlify adapter (via astro.config.mjs), meaning the build output may only be usable on Netlify.

Next Steps

Architecture Documentation - Understand the codebase
Self-Hosting Guide - Deploy to production
SDK Guide - Build plugins
Environment Variables - Full configuration reference

FAQs

How do I reset the database completely?

cd recogito-server
supabase db reset
export SUPABASE_HOST=http://localhost:54321
export SUPABASE_SERVICE_KEY=<your-service-key>
node create-default-groups.js -f config.json
node create-test-users.js -f config.json

How do I add a new user?

Use Supabase Studio (typically http://localhost:54323):

Go to Authentication → Users
Click Add user
Enter email and password
Choose to auto-accept rather than sending an email

Then, log in as an Org Admin, and navigate to the profile menu (top right) → Users. From there you can assign the new user to a group.

How do I make changes to the database schema?

Make changes in the SQL editor via Supabase Studio (typically http://localhost:54323)

Generate a migration:

cd recogito-server
supabase db diff -f <migration_name>

Migrate the database to apply:
Terminal window
```
supabase migration up
```

Additional Resources

Supabase Local Development - Official Supabase CLI docs
Astro Documentation - Client framework docs
Recogito GitHub Organization - Source code repositories