Local Development

Documentation Version

This guide is written for Recogito Studio v1.5.0 and later. If you’re working with an earlier version, some steps may differ.

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.

Overview

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 on localhost:4321.

Config Tool

Web-based configuration management tool for policies, roles, and branding. Runs on localhost:5173.

Local Services & Ports

• Supabase API: http://localhost:54321
• Supabase Database: localhost:54322
• Supabase Studio: http://localhost:54323
• Email Testing (Mailpit): http://localhost:54324
• Client Application: http://localhost:4322 (may vary if port is in use)
• Config Tool: http://localhost:5173 (optional)

Prerequisites

Before starting, ensure you have the following installed:

Required Software

• Docker Desktop - For running Supabase services
• Node.js (v18 or later) and npm - For running the client and config tool
• Git - For cloning repositories
• Supabase CLI - For local Supabase development

Install Supabase CLI

macOS:

brew install supabase/tap/supabase

Linux:

brew install supabase/tap/supabase

Windows:

scoop bucket add supabase https://github.com/supabase/scoop-bucket.git
scoop install supabase

Verify installation:

supabase --version

Install Docker

Download and install Docker Desktop for your platform.

Verify Docker is running:

docker --version

Setup Process

Phase 1: Database Setup (recogito-server)

1. Clone the recogito-server repository

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

2. Start Supabase locally

   supabase start

   This command will:

   • Download required Docker images
   • Start all Supabase services
   • Display access credentials and URLs

   Note the output, especially:

   • API URL: http://localhost:54321
   • DB URL: postgresql://postgres:postgres@localhost:54322/postgres
   • Studio URL: http://localhost:54323
   • anon key: Your anonymous API key
   • service_role key: Your service role key

3. Run database migrations

   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

4. Install server dependencies

   npm install

   This installs the packages needed for setup scripts.

5. Create environment file

   cp .env.example .env
   nano .env

   Update the following values:

   SUPABASE_HOST=http://localhost:54321
   SUPABASE_SERVICE_KEY=<service_role_key from step 2>
   
   # Test user passwords (all using same password for simplicity)
   ORG_ADMIN_PW=password123
   PROFESSOR_PW=password123
   STUDENT_PW=password123
   TUTOR_PW=password123
   READER_PW=password123
   INVITE_PW=password123
   
   # Group IDs from default config
   ORG_ADMIN_GROUP_ID='350abe76-937b-4a9b-9600-9b1f856db250'
   PROFESSOR_GROUP_ID='f918b2f8-f587-4ee1-9f2d-35b3aed0b1e6'
   STUDENT_GROUP_ID='f2e37e37-3b36-4833-b88d-f58e5c018ef5'
   TUTOR_GROUP_ID='f2e37e37-3b36-4833-b88d-f58e5c018ef5'
   READER_GROUP_ID='f2e37e37-3b36-4833-b88d-f58e5c018ef5'

6. Populate database with roles and groups

   export SUPABASE_HOST=http://localhost:54321
   export SUPABASE_SERVICE_KEY=<service_role_key from step 2>
   node create-default-groups.js -f config.json

   Important Step

   This step is required before creating test 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.

7. Create test users and run tests

   Recogito Server has a number of Jest tests that are in the jest/tests/projects.test.ts file. These tests verify some base functionality.

   To simplify the process going forward, modify the run_tests.sh file to be executable:

   chmod +x run_tests.sh

   Then execute the tests from the root directory of the repository:

   ./run_tests.sh

   The test script will create a number of test users that you can use locally to access the client and test fuctionality.

   This creates test accounts for development:

   • professor@example.com → Org Professor (can create projects)
   • student@example.com → Org Readers (read-only)
   • tutor@example.com → Org Readers (read-only)
   • reader@example.com → Org Readers (read-only)
   • invited@example.com → Org Readers (read-only)

   Why This Step Matters

   Without group assignments, test users cannot access projects or perform any actions in the application. This step is required to enable role-based testing.

8. Verify Supabase Studio

   Open http://localhost:54323 in your browser. You should see:

   • All tables populated in the Database section
   • Test users in the Authentication section
   • Policies applied to tables

Phase 2: Configuration Tool Setup (recogito-config)

1. Clone the recogito-config repository

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

2. Install dependencies

   npm install

3. Create environment file

   Create a .env file:

   VITE_SERVICE_KEY=<service_role_key from Supabase start>

4. Start the config tool

   npm run dev

   The config tool will be available at http://localhost:5173

5. Generate configuration file

   • Open http://localhost:5173 in your browser
   • The Policies tab will auto-load from your local Supabase database
   • Click Load Config and upload dafault-config.json (from the repo)
   • Review and customize:
     • Roles: Define permission sets
     • Default Groups: Org/Project/Layer group templates
     • Admin: Set admin email and groups
     • Branding: Customize platform appearance
     • Authentication: Configure auth methods
     • Dynamic Text: Multi-language content
   • Click Save Config when ready
   • Enter metadata (project name, author, version)
   • Download the generated config.json file

Phase 3: Client Application Setup (recogito-client)

1. Clone the recogito-client repository

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

2. Switch to Node adapter for local development

   mv astro.config.mjs astro.config.netlify.mjs
   mv astro.config.node.mjs astro.config.mjs

   Critical Step

   The default Astro configuration uses the Netlify adapter, which breaks local development with Vite module resolution errors. You must swap to the Node adapter before installing dependencies.

   • astro.config.node.mjs → Use for local development

   • astro.config.netlify.mjs → Use for Netlify deployment only

   If you see console errors like “Failed to load module script” or “DEFINES is not defined”, you’re using the wrong adapter.

3. Install dependencies

   npm install

4. Create environment file

   cp .env.example .env
   nano .env

   Update with your local Supabase values:

   # Supabase connection
   PUBLIC_SUPABASE=http://127.0.0.1:54321
   PUBLIC_SUPABASE_API_KEY=<anon_key from step 2>
   SUPABASE_SERVICE_KEY=<service_role_key from step 2>
   
   # IIIF Configuration (optional - can use defaults for basic setup)
   PUBLIC_IIIF_CONFIGURATION="IIIF_CLOUD"
   
   # Room secret for realtime features
   ROOM_SECRET=local-dev-room-secret-change-in-production
   
   # IIIF Server (can leave as examples for basic local dev)
   IIIF_URL=http://www.example.com/iiif/public/resources
   IIIF_KEY=your-iiif-server-api-key
   IIIF_PROJECT_ID=iiif-project-uuid-for-this-app
   
   # Mail - Using local Mailpit (available at http://127.0.0.1:54324)
   MAIL_HOST=127.0.0.1
   MAIL_PORT=1025
   MAIL_USERNAME=
   MAIL_PASSWORD=
   MAIL_FROM_ADDRESS=noreply@recogito.local
   
   # Optional features
   PUBLIC_ENABLE_USER_INVITE=TRUE

5. 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:

   cp /path/to/downloaded/config.json src/config.json

   Or use the default from the server repo:

   cp ../recogito-server/config.json src/config.json

6. Start the development server

   npm run dev

   The client will be available at http://localhost:4322 (or 4321 if that port is free).

   Note

   The dev server may use port 4322 if 4321 is already in use. Check the terminal output for the actual port.

7. Access the application

   • Open the URL shown in the terminal (typically http://localhost:4322)
   • You should see the Recogito Studio login page
   • Sign in with a test user:
     • Email: professor@example.com
     • Password: password123

Verification & Testing

Test Authentication

1. Navigate to http://localhost:4322 (or the port shown in your terminal)
2. Sign in with test credentials:
   • Email: professor@example.com
   • Password: password123
3. You should be redirected to /en/projects

Test Project Creation

1. Click Create Project
2. Enter project details
3. Create the project
4. Verify it appears in your project list

Test Document Upload

1. Open a project
2. Upload a test document (text, image, or PDF)
3. Verify the document appears in the project

Test Annotation

1. Open a document
2. Select text or draw on an image
3. Create an annotation
4. Verify it saves and persists

Access Development Tools

• Supabase Studio: http://localhost:54323 - View database, auth, storage
• Email Testing: http://localhost:54324 - View emails sent by the system
• Database: Connect directly at postgresql://postgres:postgres@localhost:54322/postgres

Development Workflow

Making Database Changes

1. Make changes via Supabase Studio (http://localhost:54323)
2. Generate a migration:

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

3. Reset the database to apply:

   supabase db reset

Updating Configuration

1. Make changes in the config tool (http://localhost:5173)
2. Save and download the new config.json
3. Copy to recogito-client/src/config.json
4. Restart the client dev server

Running Tests

For server-side database tests:

cd recogito-server/jest
npm test

Troubleshooting

Login form not appearing

Issue: Sign-in page loads but shows only branding/header/footer, no login form. Browser console shows errors like “Failed to load module script” or “DEFINES is not defined”

Cause: Using Netlify adapter instead of Node adapter

Solution:

1. Stop the dev server (Ctrl+C)
2. Swap the Astro configs:

   cd recogito-client
   mv astro.config.mjs astro.config.netlify.mjs
   mv astro.config.node.mjs astro.config.mjs

3. Clear caches:

   rm -rf node_modules/.vite .astro

4. Restart: npm run dev

Test user creation fails

Issue: Error “Cannot read properties of undefined (reading ‘id’)” when running create-test-users.js

Cause: Database doesn’t have roles and groups yet

Solution: Run create-default-groups.js BEFORE create-test-users.js:

cd recogito-server
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

Invalid email or password

Issue: Login fails with correct test user email

Cause: Test users exist from previous session with different passwords

Solution: Reset the database completely:

cd recogito-server
supabase db reset
node create-default-groups.js -f config.json
node create-test-users.js -f config.json
node assign-test-user-groups.js -f config.json

Or update passwords for existing users via Supabase Studio (http://localhost:54323) → Authentication → Users.

Supabase won’t start

Issue: Docker containers fail to start

Solutions:

• Ensure Docker Desktop is running
• Check ports 54321-54326 are not in use
• Run supabase stop then supabase start again

Client can’t connect to Supabase

Issue: API errors or authentication failures

Solutions:

• Verify PUBLIC_SUPABASE=http://127.0.0.1:54321 and PUBLIC_SUPABASE_API_KEY in .env
• Check Supabase is running: supabase status
• Ensure you’re using the correct anon key from supabase start output

Database schema is empty

Issue: No tables in Supabase Studio

Solutions:

• Run supabase db reset from the recogito-server directory
• Check for migration errors in the output
• Verify you’re in the correct directory when running the command

WebSocket connection warnings

Issue: Browser console shows WebSocket connection to ‘ws://127.0.0.1:54321/realtime/v1/websocket’ failed

Impact: Non-blocking - application works normally

Solution: This warning can be ignored for basic local development. It relates to realtime collaboration features and doesn’t affect core functionality like login, project creation, or annotation.

Stopping the Development Environment

Stop individual services

Client:

# Press Ctrl+C in the terminal running npm run dev

Config Tool (if running):

# Press Ctrl+C in the terminal running npm run dev

Supabase:

cd recogito-server
supabase stop

Restart services

Supabase:

cd recogito-server
supabase start

Client:

cd recogito-client
npm run dev

Next Steps

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

Common Development Tasks

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
node assign-test-user-groups.js -f config.json

Add a new test user manually

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

1. Go to Authentication → Users
2. Click Add user
3. Enter email and password
4. Assign to appropriate group in the database

View real-time logs

Supabase logs:

cd recogito-server
supabase logs

Client logs: Check the terminal running npm start or browser console

Export database for testing

cd recogito-server
supabase db dump -f backup.sql

Import database from backup

cd recogito-server
supabase db reset
psql postgresql://postgres:postgres@localhost:54322/postgres < backup.sql

Additional Resources

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