### Start Recogito Studio Services

Source: https://github.com/recogito/recogito-studio/blob/main/_autodocs/deployment-and-operations.md

Start all the necessary Recogito Studio services using Docker Compose in detached mode.

```bash
cd docker
docker-compose up -d
```

--------------------------------

### Example PostgreSQL Connection String

Source: https://github.com/recogito/recogito-studio/blob/main/_autodocs/configuration.md

An example of a PostgreSQL connection string, showing the format: postgres://username:password@host:port/database.

```text
postgres://postgres:secretpassword@db.example.com:5432/postgres
```

--------------------------------

### Realtime WebSocket Connection Example

Source: https://github.com/recogito/recogito-studio/blob/main/_autodocs/endpoints.md

Example of how to establish a WebSocket connection for realtime database change notifications. Replace `<SUPABASE_ANON_KEY>` with your actual API key.

```bash
wss://your-domain/realtime/v1/?apikey=<SUPABASE_ANON_KEY>
```

--------------------------------

### Display Example Environment Variables

Source: https://github.com/recogito/recogito-studio/blob/main/README.md

View the example environment variables file to compare with your live .env file and identify any new required variables before upgrading.

```sh
cat ./docker/.env.example
```

--------------------------------

### Example Route Configuration

Source: https://github.com/recogito/recogito-studio/blob/main/_autodocs/kong-gateway.md

Demonstrates the configuration of a specific route with properties like name, strip_path, paths, and methods.

```yaml
routes:
  - name: auth-v1-all
    strip_path: true
    paths:
      - /auth/v1/
    methods:
      - GET
      - POST
```

--------------------------------

### Serve an Image via IIIF

Source: https://github.com/recogito/recogito-studio/blob/main/_autodocs/README.md

This is an example of an HTTP GET request to serve an image using the IIIF protocol. It includes the necessary authorization header.

```http
GET /iiif/2/documents/file.jpg/full/max/0/default.jpg
Authorization: Bearer $SUPABASE_ANON_KEY
```

--------------------------------

### Install Certbot for SSL/TLS Certificates

Source: https://github.com/recogito/recogito-studio/blob/main/_autodocs/deployment-and-operations.md

Install Certbot and its Nginx plugin to obtain and manage Let's Encrypt SSL/TLS certificates for your Recogito Studio domain. Includes commands for obtaining certificates and testing auto-renewal.

```bash
sudo apt-get install certbot python3-certbot-nginx
sudo certbot certonly --nginx -d recogito.example.com -d api.example.com
sudo certbot renew --dry-run  # Test renewal
```

--------------------------------

### Example Request for service_role Consumer

Source: https://github.com/recogito/recogito-studio/blob/main/_autodocs/kong-gateway.md

Illustrates how to access /pg/tables using the service_role consumer's API key for full administrative access.

```bash
curl -H "Authorization: Bearer $SUPABASE_SERVICE_KEY" \
  http://localhost:8000/pg/tables
```

--------------------------------

### Grant Execution Permissions to Upgrade Script

Source: https://github.com/recogito/recogito-studio/blob/main/README.md

Make the upgrade script executable before running it for the first time. This is a one-time setup step.

```sh
chmod +x upgrade.sh
```

--------------------------------

### Copy and Customize Environment File

Source: https://github.com/recogito/recogito-studio/blob/main/_autodocs/deployment-and-operations.md

Copy the example environment file and customize it with your specific secrets and URLs. Ensure critical variables like database passwords and API keys are generated securely.

```bash
cp docker/.env.example docker/.env
```

```bash
# Secrets - generate strong values
POSTGRES_PASSWORD=$(openssl rand -base64 32)
JWT_SECRET=$(openssl rand -base64 32)
ANON_KEY=<generate with JWT tool>
SERVICE_ROLE_KEY=<generate with JWT tool>
DASHBOARD_USERNAME=<secure username>
DASHBOARD_PASSWORD=$(openssl rand -base64 32)
VAULT_ENC_KEY=$(openssl rand -base64 32)

# URLs - set to your domain
SITE_URL=https://recogito.example.com
API_EXTERNAL_URL=https://api.example.com
```

```bash
SMTP_HOST=mail.example.com
SMTP_PORT=587
SMTP_USER=noreply@example.com
SMTP_PASS=<app-specific-password>
SMTP_SENDER_NAME="Recogito Studio"
MAIL_FROM_ADDRESS=noreply@example.com
```

--------------------------------

### Example Project Response

Source: https://github.com/recogito/recogito-studio/blob/main/_autodocs/api-resources.md

This JSON object illustrates a project's data. It includes its ID, creation and update timestamps, name, description, owner, and public visibility status.

```json
{
  "id": "proj-123",
  "created_at": "2024-01-10T08:00:00Z",
  "name": "Medieval Manuscripts",
  "description": "Digitization and annotation project",
  "owner_id": "user-456",
  "is_public": false,
  "organization_id": "org-789"
}
```

--------------------------------

### API Success Response Example

Source: https://github.com/recogito/recogito-studio/blob/main/_autodocs/README.md

Example structure of a successful API response, including common fields like id, created_at, and name.

```json
{
  "id": "uuid",
  "created_at": "2024-01-15T10:30:00Z",
  "name": "Example"
}
```

--------------------------------

### Example cURL Invocations for Edge Functions

Source: https://github.com/recogito/recogito-studio/blob/main/_autodocs/edge-functions.md

Shows how to invoke Edge Functions using cURL, with examples for both unauthenticated and JWT-verified requests.

```bash
# Without JWT verification
curl -X POST http://localhost:8000/functions/v1/hello \
  -H "Authorization: Bearer $ANON_KEY"
```

```bash
# With JWT verification enabled (VERIFY_JWT=true)
curl -X POST http://localhost:8000/functions/v1/custom-function \
  -H "Authorization: Bearer $JWT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"key": "value"}'
```

--------------------------------

### Restart Supabase and Postgres Containers

Source: https://github.com/recogito/recogito-studio/blob/main/backup-and-restore.md

Starts the Supabase and Postgres Docker containers, initializing a new Postgres DB with default Supabase configuration.

```sh
sudo docker compose -f ./docker/docker-compose.yml -f ./docker/docker-compose.postgres.yml up -d
```

--------------------------------

### Strip Path Example

Source: https://github.com/recogito/recogito-studio/blob/main/_autodocs/kong-gateway.md

Illustrates how the `strip_path` property affects the request received by the backend service.

```text
Client Request:    GET /auth/v1/user
Kong removes:      /auth/v1
Backend receives:  GET /user
Backend response:  {...}
Kong returns:      {...}
```

--------------------------------

### IIIF Image Retrieval Examples

Source: https://github.com/recogito/recogito-studio/blob/main/_autodocs/endpoints.md

Examples of how to retrieve image metadata and images using the IIIF API. Supports both v2 and v3 protocols.

```http
GET /iiif/2/documents/file.jpg/full/max/0/default.jpg
```

```http
GET /iiif/3/documents/file.jpg/full/max/0/default.webp
```

--------------------------------

### List Targets by Annotation

Source: https://github.com/recogito/recogito-studio/blob/main/_autodocs/api-resources.md

Example of how to retrieve target records associated with a specific annotation ID.

```bash
GET /rest/v1/targets?annotation_id=eq.{ann-id}
```

--------------------------------

### Ruby Logging Example

Source: https://github.com/recogito/recogito-studio/blob/main/_autodocs/cantaloupe-delegate.md

Demonstrates how to log messages to Docker stdout using `puts` within the delegate script. This is useful for debugging and monitoring the script's execution flow.

```ruby
puts "Pre-authorizing request"
puts "Getting resource info for identifier: #{context['identifier']}"
puts "Constructed URI: #{uri}"
puts "resource_accessible response code #{response.code}"
```

--------------------------------

### Clone Recogito Studio Repository

Source: https://github.com/recogito/recogito-studio/blob/main/docker/self-hosting-recogito-studio.md

Clone the official Recogito Studio GitHub repository to your hosting instance to begin the self-hosting setup.

```bash
git clone https://github.com/recogito/recogito-studio.git
```

--------------------------------

### Example cURL Invocation for Hello World Function

Source: https://github.com/recogito/recogito-studio/blob/main/_autodocs/edge-functions.md

Demonstrates how to invoke the 'Hello World' Edge Function using cURL and shows the expected response.

```bash
# Basic invocation
curl -X POST http://localhost:8000/functions/v1/hello \
  -H "Authorization: Bearer $ANON_KEY"

# Response
"Hello from Edge Functions!"

# With verbose output
curl -v -X POST http://localhost:8000/functions/v1/hello \
  -H "Authorization: Bearer $ANON_KEY" \
  -H "Content-Type: application/json"
```

--------------------------------

### GraphQL Request Body Example

Source: https://github.com/recogito/recogito-studio/blob/main/_autodocs/endpoints.md

Example of a GraphQL query to retrieve document IDs and names. This is used with the GraphQL API endpoint.

```json
{
  "query": "{ documents { id, name } }"
}
```

--------------------------------

### GraphQL Response Body Example

Source: https://github.com/recogito/recogito-studio/blob/main/_autodocs/endpoints.md

Example of a successful GraphQL response containing document data. This is the expected format for queries to the GraphQL API.

```json
{
  "data": { "documents": [...] }
}
```

--------------------------------

### Paginate Documents with Limit and Offset

Source: https://github.com/recogito/recogito-studio/blob/main/_autodocs/api-resources.md

Demonstrates basic pagination for retrieving documents using `limit` to control the number of results and `offset` to specify the starting point.

```bash
GET /rest/v1/documents?limit=10&offset=0
GET /rest/v1/documents?limit=10&offset=10  # Next page
```

--------------------------------

### Example Target Response with FragmentSelector

Source: https://github.com/recogito/recogito-studio/blob/main/_autodocs/api-resources.md

A sample JSON response for a target record, demonstrating the use of a FragmentSelector for specifying a region within a media source.

```json
{
  "id": "target-123",
  "annotation_id": "ann-456",
  "selector_type": "FragmentSelector",
  "selector_value": {
    "type": "FragmentSelector",
    "conformsTo": "http://www.w3.org/TR/media-frags/",
    "value": "xywh=100,50,400,300"
  },
  "source": "https://example.com/image1.jpg"
}
```

--------------------------------

### Hello World Function

Source: https://github.com/recogito/recogito-studio/blob/main/_autodocs/edge-functions.md

A minimal example function that responds to all HTTP methods with a greeting message. It demonstrates the basic structure of an Edge Function and how to return a JSON response.

```APIDOC
## POST /functions/v1/hello

### Description
A minimal example function demonstrating the basic function structure. Responds to all HTTP methods with a greeting message.

### Method
POST

### Endpoint
/functions/v1/hello

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
None

### Request Example
```bash
curl -X POST http://localhost:8000/functions/v1/hello \
  -H "Authorization: Bearer $ANON_KEY"
```

### Response
#### Success Response (200)
- **Content-Type** (string) - `application/json`
- **Body** (string) - `"Hello from Edge Functions!"`

#### Response Example
```json
"Hello from Edge Functions!"
```
```

--------------------------------

### List Documents by Project with Sorting and Limit

Source: https://github.com/recogito/recogito-studio/blob/main/_autodocs/api-resources.md

Example of how to list document records filtered by project ID, sorted by creation date in descending order, and limited to 10 results. Requires an API key for authorization.

```bash
GET /rest/v1/documents?project_id=eq.abc-123&order_by=created_at.desc&limit=10
Authorization: Bearer <API_KEY>
```

--------------------------------

### Example Document Response

Source: https://github.com/recogito/recogito-studio/blob/main/_autodocs/api-resources.md

A sample JSON response for a document record, illustrating the fields and data types returned by the API.

```json
[
  {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "created_at": "2024-01-15T10:30:00Z",
    "updated_at": "2024-01-20T14:22:00Z",
    "name": "Ancient Manuscript",
    "description": "Historical document from 1500s",
    "is_public": false,
    "owner_id": "user-uuid",
    "project_id": "project-uuid"
  }
]
```

--------------------------------

### Configure Organization Admin Password

Source: https://github.com/recogito/recogito-studio/blob/main/_autodocs/configuration.md

Set the organization admin password for initial setup. It is recommended to update this from the default insecure value.

```bash
ORG_ADMIN_PW=secure_admin_password
```

--------------------------------

### Kong API Gateway Configuration Example

Source: https://github.com/recogito/recogito-studio/blob/main/_autodocs/architecture.md

This snippet shows the routing rules for the Kong API Gateway, directing traffic to various backend services based on URL paths.

```yaml
docker/volumes/api/kong.yml
```

--------------------------------

### Example Layer Response

Source: https://github.com/recogito/recogito-studio/blob/main/_autodocs/api-resources.md

A sample JSON response for a layer. It contains metadata such as name, description, document association, creator, visibility, and display color.

```json
{
  "id": "layer-123",
  "created_at": "2024-01-15T10:30:00Z",
  "name": "Named Entities",
  "description": "Person and place names",
  "document_id": "doc-456",
  "creator_id": "user-789",
  "is_public": false,
  "color": "#FF5733"
}
```

--------------------------------

### Check Service Status

Source: https://github.com/recogito/recogito-studio/blob/main/_autodocs/deployment-and-operations.md

Verify that all Docker services are running and healthy after starting them with Docker Compose.

```bash
docker-compose ps
```

--------------------------------

### Recogito Studio Development Environment Variables

Source: https://github.com/recogito/recogito-studio/blob/main/_autodocs/configuration.md

These environment variables are used for local development setups. They often use default or easily manageable values for testing purposes.

```bash
POSTGRES_PASSWORD=dev-password
JWT_SECRET=dev-jwt-secret-with-minimum-32-characters
ANON_KEY=<demo-anon-key>
SERVICE_ROLE_KEY=<demo-service-key>
DASHBOARD_USERNAME=supabase
DASHBOARD_PASSWORD=password
VAULT_ENC_KEY=dev-vault-key-32-chars-minimum
POSTGRES_HOST=localhost
POSTGRES_PORT=5432
POSTGRES_DB=postgres
KONG_HTTP_PORT=8000
KONG_HTTPS_PORT=8443
SITE_URL=http://localhost:3000
API_EXTERNAL_URL=http://localhost:8000
PGRST_DB_SCHEMAS=public,storage,graphql_public
ENABLE_EMAIL_SIGNUP=false
DISABLE_SIGNUP=true
STUDIO_DEFAULT_ORGANIZATION="Dev Org"
STUDIO_DEFAULT_PROJECT="Dev Project"
MINIO_ROOT_USER=minioadmin
MINIO_ROOT_PASSWORD=minioadmin
FUNCTIONS_VERIFY_JWT=false
ROOM_SECRET=dev-room-secret
```

--------------------------------

### Pre-authorization Example Usage

Source: https://github.com/recogito/recogito-studio/blob/main/_autodocs/cantaloupe-delegate.md

Illustrates how Cantaloupe calls the pre_authorize method before serving from cache. The method relies on resource_accessible to perform an HTTP HEAD request and determine access.

```ruby
# Cantaloupe calls pre_authorize before serving from cache
# If returns false, cached image is not returned even if exists
context = {
  'identifier' => 'documents/file.jpg',
  'request_headers' => { 'Authorization' => 'Bearer token123' }
}
# pre_authorize called → resource_accessible → HTTP HEAD → returns true/false
```

--------------------------------

### Example User Profile Response

Source: https://github.com/recogito/recogito-studio/blob/main/_autodocs/api-resources.md

A sample JSON response for a user profile. It contains user identification, timestamps, contact information, full name, avatar URL, and organization details.

```json
{
  "id": "user-123",
  "created_at": "2024-01-01T00:00:00Z",
  "email": "user@example.com",
  "full_name": "Jane Doe",
  "avatar_url": "https://example.com/avatars/user.jpg",
  "organization_id": "org-456",
  "is_admin": false
}
```

--------------------------------

### List Annotations by Document with Specific Fields

Source: https://github.com/recogito/recogito-studio/blob/main/_autodocs/api-resources.md

Example of how to retrieve annotations associated with a specific document, selecting only the ID, creation timestamp, and body ID. Requires an API key for authorization.

```bash
GET /rest/v1/annotations?document_id=eq.{doc-id}&select=id,created_at,body_id
Authorization: Bearer <API_KEY>
```

--------------------------------

### Filtering Operators Example

Source: https://github.com/recogito/recogito-studio/blob/main/_autodocs/README.md

Examples of filtering operators supported by the REST API for querying data.

```text
| Operator | Example | Meaning |
|----------|---------|---------|
| `eq` | `id=eq.123` | Equals |
| `gt` | `created_at=gt.2024-01-01` | Greater than |
| `like` | `name=like.%test%` | Pattern match |
| `in` | `status=in.(draft,published)` | In list |
```

--------------------------------

### API Error Response Example

Source: https://github.com/recogito/recogito-studio/blob/main/_autodocs/README.md

Example structure of an API error response, providing details about the error and potential fixes.

```json
{
  "message": "Error description",
  "details": "Additional details",
  "hint": "How to fix"
}
```

--------------------------------

### Get Annotations by User and Date

Source: https://github.com/recogito/recogito-studio/blob/main/_autodocs/api-resources.md

Fetch annotations created by a specific user within the last week, ordered by creation date in descending order. Requires an API key for authorization.

```bash
GET /rest/v1/annotations?creator_id=eq.user-123&created_at=gte.2024-01-13&order_by=created_at.desc
Authorization: Bearer <API_KEY>
```

--------------------------------

### Troubleshoot Service Startup Failures

Source: https://github.com/recogito/recogito-studio/blob/main/_autodocs/deployment-and-operations.md

Provides commands to check logs for PostgreSQL and Kong, and lists common issues like port conflicts, missing networks, or disk space problems.

```bash
# Check logs
docker-compose logs postgres
docker-compose logs kong

# Common issues:
# - Port already in use: Kill process or change port
# - Network not created: docker network create recogito
# - Disk full: Check with df -h
```
```

--------------------------------

### Enable Phone Signup

Source: https://github.com/recogito/recogito-studio/blob/main/_autodocs/configuration.md

Set to true to enable phone/SMS authentication.

```bash
ENABLE_PHONE_SIGNUP=true
```

--------------------------------

### Docker Compose Up Command

Source: https://github.com/recogito/recogito-studio/blob/main/_autodocs/architecture.md

Orchestrates the deployment of Recogito Studio services using Docker containers. Navigate to the 'docker' directory before running.

```bash
cd docker
docker-compose up
```

--------------------------------

### Anonymous API Access Token Payload Example

Source: https://github.com/recogito/recogito-studio/blob/main/_autodocs/configuration.md

Example JSON payload for an anonymous API access token (ANON_KEY). This token is used for unauthenticated access.

```json
{
  "role": "anon",
  "iss": "supabase-demo",
  "iat": 1641769200,
  "exp": 1799535600
}
```

--------------------------------

### Create Docker Network

Source: https://github.com/recogito/recogito-studio/blob/main/_autodocs/deployment-and-operations.md

Create a dedicated Docker network for Recogito Studio services to communicate within.

```bash
docker network create recogito
```

--------------------------------

### Service Role API Access Token Payload Example

Source: https://github.com/recogito/recogito-studio/blob/main/_autodocs/configuration.md

Example JSON payload for a service role API access token (SERVICE_ROLE_KEY). This token is used for server-side operations and has higher privileges.

```json
{
  "role": "service_role",
  "iss": "supabase-demo",
  "iat": 1641769200,
  "exp": 1799535600
}
```

--------------------------------

### Navigate to Recogito Studio Directory

Source: https://github.com/recogito/recogito-studio/blob/main/README.md

Change the current directory to the root of the Recogito Studio repository before proceeding with the upgrade.

```sh
cd /path/to/recogito-studio
```

--------------------------------

### Rollback Recogito Studio

Source: https://github.com/recogito/recogito-studio/blob/main/_autodocs/deployment-and-operations.md

Instructions for rolling back Recogito Studio to a previous state, including restoring the database backup, reverting code changes, and restarting services.

```bash
# Restore backup
docker-compose down -v
docker exec supabase-postgres pg_restore ...

# Revert code
git reset --hard HEAD~1

# Restart
docker-compose up -d
```
```

--------------------------------

### Enable Email-Based Signups

Source: https://github.com/recogito/recogito-studio/blob/main/_autodocs/configuration.md

Enables or disables email/password authentication for user signups. Requires SMTP configuration to be set up.

```bash
ENABLE_EMAIL_SIGNUP=true
```

--------------------------------

### Edge Functions Route

Source: https://github.com/recogito/recogito-studio/blob/main/_autodocs/kong-gateway.md

Allows for the invocation of serverless Edge Functions via HTTP POST or GET requests.

```APIDOC
## POST /functions/v1/{function-name}

### Description
Invoke an Edge Function.

### Method
POST

### Endpoint
/functions/v1/{function-name}

### Parameters
#### Path Parameters
- **function-name** (string) - Required - The name of the function to invoke.

## GET /functions/v1/{function-name}

### Description
Invoke an Edge Function.

### Method
GET

### Endpoint
/functions/v1/{function-name}

### Parameters
#### Path Parameters
- **function-name** (string) - Required - The name of the function to invoke.
```

--------------------------------

### Enable WebP Detection

Source: https://github.com/recogito/recogito-studio/blob/main/_autodocs/configuration.md

Set to true to enable WebP image format detection and delivery.

```bash
IMGPROXY_ENABLE_WEBP_DETECTION=true
```

--------------------------------

### Realtime REST API Endpoint

Source: https://github.com/recogito/recogito-studio/blob/main/_autodocs/kong-gateway.md

Offers a RESTful interface for interacting with the Realtime service, supporting both GET and POST requests.

```APIDOC
## GET|POST /realtime/v1/api/

### Description
REST API for Realtime service operations.

### Method
GET, POST

### Endpoint
/realtime/v1/api/
```

--------------------------------

### Upgrade Recogito Studio

Source: https://github.com/recogito/recogito-studio/blob/main/_autodocs/deployment-and-operations.md

Steps to upgrade Recogito Studio by pulling the latest code, comparing environment files, rebuilding services, and verifying the deployment.

```bash
# Pull latest code
git pull origin main

# Compare .env files
diff docker/.env docker/.env.example

# Add new variables if needed
# Update versions in docker-compose.yml if needed

# Rebuild and restart
cd docker
docker-compose down
docker-compose pull
docker-compose up -d

# Wait for services
sleep 60

# Verify
docker-compose ps
curl -H "Authorization: Bearer $ANON_KEY" \
  http://localhost:8000/rest/v1/documents
```
```

--------------------------------

### Configure Docker Socket Location

Source: https://github.com/recogito/recogito-studio/blob/main/_autodocs/configuration.md

Specify the Docker socket location for log collection. This may vary by OS and setup.

```bash
DOCKER_SOCKET_LOCATION=/var/run/docker.sock          # Linux
DOCKER_SOCKET_LOCATION=/var/run/docker.sock          # Docker Desktop Mac/Windows
```

--------------------------------

### GET Request for Layers

Source: https://github.com/recogito/recogito-studio/blob/main/_autodocs/api-resources.md

Retrieve annotation layers for a given document by specifying the document_id. This is useful for accessing layer-specific configurations and metadata.

```bash
GET /rest/v1/layers?document_id=eq.{doc-id}
Authorization: Bearer <API_KEY>
```

--------------------------------

### GET Request for Organizations

Source: https://github.com/recogito/recogito-studio/blob/main/_autodocs/api-resources.md

Query organizations based on their owner's ID. This allows retrieval of organization details filtered by the owner profile.

```bash
GET /rest/v1/organizations?owner_id=eq.{user-id}
Authorization: Bearer <API_KEY>
```

--------------------------------

### Paginate Documents with Keyset Pagination

Source: https://github.com/recogito/recogito-studio/blob/main/_autodocs/api-resources.md

Implements keyset pagination for retrieving documents, using `order_by` and a filter on the last ID from the previous response for efficient fetching of subsequent pages.

```bash
# First page
GET /rest/v1/documents?order_by=id&limit=10

# Next page using last ID from previous response
GET /rest/v1/documents?id=gt.{last-id}&order_by=id&limit=10
```

--------------------------------

### GET Request for Projects

Source: https://github.com/recogito/recogito-studio/blob/main/_autodocs/api-resources.md

Fetch projects associated with a specific organization by using the organization_id parameter. This helps in managing and querying project-level data.

```bash
GET /rest/v1/projects?organization_id=eq.{org-id}
Authorization: Bearer <API_KEY>
```

--------------------------------

### Environment Variables Configuration

Source: https://github.com/recogito/recogito-studio/blob/main/_autodocs/README.md

Key environment variables for configuring Recogito Studio, including secrets and service settings.

```bash
# Secrets (CHANGE THESE)
POSTGRES_PASSWORD=...
JWT_SECRET=...
ANON_KEY=...
SERVICE_ROLE_KEY=...

# Services
POSTGRES_HOST=localhost
POSTGRES_PORT=5432
SITE_URL=https://recogito.example.com
API_EXTERNAL_URL=https://api.example.com

# Email
SMTP_HOST=mail.example.com
SMTP_PORT=587
SMTP_USER=noreply@example.com
```

--------------------------------

### GET Request for Annotation Bodies

Source: https://github.com/recogito/recogito-studio/blob/main/_autodocs/api-resources.md

Use this endpoint to retrieve annotation bodies associated with a specific annotation. Ensure you include the annotation_id parameter.

```bash
GET /rest/v1/bodies?annotation_id=eq.{ann-id}
Authorization: Bearer <API_KEY>
```

--------------------------------

### Set Additional Redirect URLs

Source: https://github.com/recogito/recogito-studio/blob/main/_autodocs/configuration.md

Provides a comma-separated list of additional URLs allowed for OAuth redirects. This is useful for development or multi-environment setups.

```bash
ADDITIONAL_REDIRECT_URLS=https://app.example.com,https://localhost:3000
```

--------------------------------

### Graceful Zero-Downtime Deployment

Source: https://github.com/recogito/recogito-studio/blob/main/_autodocs/deployment-and-operations.md

For non-breaking changes, follow these steps to perform a zero-downtime deployment. This involves updating code, pulling new images, and performing a graceful restart of the service, allowing Kong to buffer requests.

```bash
# For non-breaking changes:
1. Update code
2. Pull new images: docker-compose pull
3. Graceful restart: docker-compose restart service-name
# Kong continues accepting requests, buffers briefly
```

--------------------------------

### CustomDelegate Class Initialization

Source: https://github.com/recogito/recogito-studio/blob/main/_autodocs/cantaloupe-delegate.md

Initializes the CustomDelegate class, setting the URL prefix from an environment variable.

```ruby
class CustomDelegate
  attr_accessor :context
  
  def initialize
    @url_prefix = ENV['CANTALOUPE_HTTPSOURCE_BASICLOOKUPSTRATEGY_URL_PREFIX']
  end
  
  # ... method implementations
end
```

--------------------------------

### Create User via SQL

Source: https://github.com/recogito/recogito-studio/blob/main/_autodocs/deployment-and-operations.md

Creates a new authentication user in the PostgreSQL database using SQL commands executed via Docker exec. It generates a UUID, sets the email, encrypts the password, and confirms the email.

```bash
docker exec -i supabase-postgres psql -U postgres postgres << 'EOF'
-- Create auth user
INSERT INTO auth.users (
  id, email, encrypted_password, email_confirmed_at, created_at
) VALUES (
  gen_random_uuid(),
  'user@example.com',
  crypt('password123', gen_salt('bf')),
  now(),
  now()
);

-- Verify
SELECT id, email FROM auth.users WHERE email = 'user@example.com';
EOF
```
```

--------------------------------

### Set Public Supabase URL

Source: https://github.com/recogito/recogito-studio/blob/main/_autodocs/configuration.md

Configure the public URL for client-side Supabase initialization. This is an optional setting.

```bash
PUBLIC_SUPABASE=https://api.example.com
```

--------------------------------

### Recogito Studio Production Environment Variables

Source: https://github.com/recogito/recogito-studio/blob/main/_autodocs/configuration.md

These environment variables are for production deployments, utilizing generated secrets and specific domain configurations for security and scalability.

```bash
POSTGRES_PASSWORD=$(openssl rand -base64 32)
JWT_SECRET=$(openssl rand -base64 32)
ANON_KEY=<generate-with-jwt-tool>
SERVICE_ROLE_KEY=<generate-with-jwt-tool>
DASHBOARD_USERNAME=$(openssl rand -hex 8)
DASHBOARD_PASSWORD=$(openssl rand -base64 32)
VAULT_ENC_KEY=$(openssl rand -base64 32)
POSTGRES_HOST=db.example.com
POSTGRES_PORT=5432
POSTGRES_DB=recogito_prod
KONG_HTTP_PORT=80
KONG_HTTPS_PORT=443
SITE_URL=https://recogito.example.com
API_EXTERNAL_URL=https://api.example.com
PGRST_DB_SCHEMAS=public,storage,graphql_public
ENABLE_EMAIL_SIGNUP=true
ENABLE_EMAIL_AUTOCONFIRM=false
SMTP_HOST=mail.example.com
SMTP_PORT=587
SMTP_USER=noreply@example.com
SMTP_PASS=$(openssl rand -base64 32)
SMTP_ADMIN_EMAIL=admin@example.com
DISABLE_SIGNUP=false
STUDIO_DEFAULT_ORGANIZATION="Recogito Studio"
STUDIO_DEFAULT_PROJECT="Main"
MINIO_ROOT_USER=$(openssl rand -hex 16)
MINIO_ROOT_PASSWORD=$(openssl rand -base64 32)
FUNCTIONS_VERIFY_JWT=true
ROOM_SECRET=$(openssl rand -base64 32)
INVITE_CRYPTO_KEY=$(openssl rand -base64 32)
MAIL_FROM_ADDRESS=noreply@example.com
JWT_EXPIRY=86400
```

--------------------------------

### Example Annotation Body Response

Source: https://github.com/recogito/recogito-studio/blob/main/_autodocs/api-resources.md

This JSON object represents a typical response for an annotation body. It includes details like type, value, purpose, format, and language.

```json
{
  "id": "body-789",
  "annotation_id": "ann-456",
  "type": "TextualBody",
  "value": "This is a comment",
  "purpose": "commenting",
  "format": "text/plain",
  "language": "en"
}
```

--------------------------------

### Configure MinIO Root User

Source: https://github.com/recogito/recogito-studio/blob/main/_autodocs/configuration.md

Set the MinIO root user (access key). Must be at least 3 characters long.

```bash
MINIO_ROOT_USER=minio-admin
```

--------------------------------

### Configure Logflare Backend API Key

Source: https://github.com/recogito/recogito-studio/blob/main/_autodocs/configuration.md

Set the API key for the Logflare backend for server-side logging. This is required if logging is enabled.

```bash
LOGFLARE_LOGGER_BACKEND_API_KEY=your-api-key
```

--------------------------------

### Automated PostgreSQL Backup Script

Source: https://github.com/recogito/recogito-studio/blob/main/_autodocs/deployment-and-operations.md

This bash script automates daily PostgreSQL backups for Recogito Studio, stores them in a designated directory, and cleans up old backups. It uses Docker to execute pg_dump and cp commands.

```bash
# backup.sh

BACKUP_DIR="/backups/recogito"
DATE=$(date +%Y%m%d_%H%M%S)
PASSWORD="$POSTGRES_PASSWORD"

mkdir -p $BACKUP_DIR

docker exec supabase-postgres pg_dump \
  -U postgres \
  -F c \
  -b \
  -v \
  -f /tmp/recogito_$DATE.dump \
  postgres

docker cp supabase-postgres:/tmp/recogito_$DATE.dump \
  $BACKUP_DIR/

# Keep only last 30 days
find $BACKUP_DIR -type f -mtime +30 -delete

echo "Backup completed: $BACKUP_DIR/recogito_$DATE.dump"
```
```

--------------------------------

### Test API Connectivity

Source: https://github.com/recogito/recogito-studio/blob/main/_autodocs/deployment-and-operations.md

Test the Recogito Studio API's availability and authentication. Initially, accessing the profile should result in a 401 Unauthorized error, and accessing documents with a valid token should return data.

```bash
curl http://localhost:8000/api/profile
# Expected: 401 Unauthorized (authentication needed)
```

```bash
curl -H "Authorization: Bearer $ANON_KEY" \
  http://localhost:8000/rest/v1/documents
# Expected: JSON array (may be empty)
```

--------------------------------

### List all documents in a project with annotations count

Source: https://github.com/recogito/recogito-studio/blob/main/_autodocs/api-resources.md

Retrieves a list of all documents within a specified project, including the count of their associated annotations. This is useful for getting an overview of project content.

```APIDOC
## GET /rest/v1/documents?project_id=eq.proj-123&select=id,name,annotations:annotations(id)

### Description
Retrieves a list of all documents within a specified project, including the count of their associated annotations.

### Method
GET

### Endpoint
/rest/v1/documents

### Parameters
#### Query Parameters
- **project_id** (string) - Required - Filter by project ID.
- **select** (string) - Optional - Specify which fields to return, including a count of related annotations.
```

--------------------------------

### GET Request for User Profiles

Source: https://github.com/recogito/recogito-studio/blob/main/_autodocs/api-resources.md

Retrieve a user profile by specifying the user's ID. This endpoint provides detailed information about a user's account and associated organization.

```bash
GET /rest/v1/profiles?id=eq.{user-id}
Authorization: Bearer <API_KEY>
```

--------------------------------

### Recogito Studio System Architecture Diagram

Source: https://github.com/recogito/recogito-studio/blob/main/_autodocs/architecture.md

This diagram illustrates the high-level components of the Recogito Studio system and their interactions.

```text
┌─────────────────────────────────────────────────────────────────┐
│ Client Applications (Web, Mobile)                               │
└────────┬──────────────────────────────────────────────────────┬─┘
         │                                                        │
    HTTPS/REST API                                    WebSocket (Realtime)
         │                                                        │
    ┌────▼──────────────────────────────────────────────────────▼────┐
    │ Kong API Gateway (API Reverse Proxy)                           │
    │ - Route requests to backend services                           │
    │ - Authentication (key-auth)                                    │
    │ - CORS headers                                                 │
    │ - Rate limiting                                                │
    └────┬────┬──────┬────┬───────┬─────────┬────┬──────────────┬───┘
         │    │      │    │       │         │    │              │
    ┌────▼──┐ │ ┌────▼─┐ │ ┌────▼──┐ ┌────▼──┐ │ ┌────────────▼──┐
    │Studio │ │ │Auth  │ │ │REST   │ │Graph  │ │ │Realtime/WebS  │
    │(Web UI)│ │ │Service│ │ │API    │ │QL    │ │ │(Socket.io)    │
    │        │ │ │      │ │ │      │ │      │ │ │               │
    └────────┘ │ └─┬────┘ │ └──────┘ │      │ │ │               │
               │   │      │          │      │ │ └───────────────┘
    ┌──────────▼─┐ │ ┌────▼──────┐  │      │ │
    │ Edge       │ │ │Functions  │  │      │ │ ┌──────────────┐
    │Functions   │ │ │(Deno)     │  │      │ │ │IIIF Server   │
    │(Deno)      │ │ │           │  │      │ │ │(Cantaloupe)  │
    │ - hello    │ │ └───────────┘  │      │ │ │              │
    │ - main     │ │                 │      │ │ └──────────────┘
    │            │ │                 ▼      │ │
    └────────────┘ │            ┌────────┐  │ │
                   │            │Storage │  │ │
                   │            │API     │  │ │
                   │            └────────┘  │ │
                   │                        ▼ ▼
                   │                   ┌──────────┐
                   │                   │MinIO S3  │
                   │                   │Storage   │
                   │                   └──────────┘
                   │
                   └──────────────────┬─────────────────┐
                                      │                 │
                              ┌───────▼──────┐  ┌──────▼──────┐
                              │PostgreSQL    │  │Supavisor    │
                              │Database      │  │(Pooler)     │
                              │ - Tables     │  │             │
                              │ - RLS        │  │             │
                              │ - Functions  │  │             │
                              └──────────────┘  └─────────────┘
```

--------------------------------

### View Docker Logs for Services

Source: https://github.com/recogito/recogito-studio/blob/main/_autodocs/architecture.md

Use docker-compose logs to view logs for individual Recogito Studio services. This is useful for monitoring and debugging.

```bash
docker-compose logs kong
docker-compose logs auth
docker-compose logs postgres
docker-compose logs realtime
docker-compose logs functions
```

--------------------------------

### Handling Different HTTP Methods in Edge Function

Source: https://github.com/recogito/recogito-studio/blob/main/_autodocs/edge-functions.md

Illustrates how to use a switch statement to handle different HTTP methods (GET, POST, PUT, DELETE) within a single Edge Function.

```typescript
serve(async (req: Request) => {
  switch (req.method) {
    case 'GET':
      return handleGet(req)
    case 'POST':
      return handlePost(req)
    case 'PUT':
      return handlePut(req)
    case 'DELETE':
      return handleDelete(req)
    default:
      return new Response('Method not allowed', { status: 405 })
  }
})
```

--------------------------------

### Enable User Invites

Source: https://github.com/recogito/recogito-studio/blob/main/_autodocs/configuration.md

Set to TRUE to allow organization admins to invite users. This is an optional setting with a default value of TRUE.

```bash
PUBLIC_ENABLE_USER_INVITE=TRUE
```

--------------------------------

### Troubleshoot File Upload Issues

Source: https://github.com/recogito/recogito-studio/blob/main/_autodocs/deployment-and-operations.md

Helps resolve file upload problems by checking logs for storage-related services (Supabase Storage, Minio), verifying bucket existence, and checking disk space.

```bash
# Check storage
docker logs supabase-storage
docker logs minio

# Verify bucket exists
docker exec minio mc ls minio/stub

# Check disk space
docker exec supabase-postgres df -h
```
```

--------------------------------

### Get annotations created by a specific user in last week

Source: https://github.com/recogito/recogito-studio/blob/main/_autodocs/api-resources.md

Fetches annotations created by a particular user within the last week, ordered by creation date in descending order. This helps in tracking recent user activity.

```APIDOC
## GET /rest/v1/annotations?creator_id=eq.user-123&created_at=gte.2024-01-13&order_by=created_at.desc

### Description
Fetches annotations created by a particular user within the last week, ordered by creation date in descending order.

### Method
GET

### Endpoint
/rest/v1/annotations

### Parameters
#### Query Parameters
- **creator_id** (string) - Required - Filter by the creator's user ID.
- **created_at** (string) - Required - Filter by creation date (e.g., 'gte.2024-01-13' for greater than or equal to).
- **order_by** (string) - Optional - Sort results by creation date in descending order ('created_at.desc').
```

--------------------------------

### Ruby: Get HTTP Resource Info

Source: https://github.com/recogito/recogito-studio/blob/main/_autodocs/cantaloupe-delegate.md

Maps an image identifier to HTTP resource information, including URI, headers, and whether to send a HEAD request. Use when an image identifier needs to be resolved to a full URL for fetching.

```ruby
def httpsource_resource_info(options = {})
  puts "Getting resource info for identifier: #{context['identifier']}"
  # ... implementation returns Hash or nil
end
```

```ruby
{
  'uri' => 'http://example.com/image.jpg',
  'headers' => { 'Authorization' => '...' },
  'send_head_request' => true
}
```

```ruby
def httpsource_resource_info(options = {})
  if @url_prefix && context['identifier']
    identifier = context['identifier']
    uri = "#{@url_prefix}#{identifier}"
    bearer_token = extract_bearer_token(context['request_headers'])
    
    return {
      'uri' => uri,
      'headers' => { "Authorization" => "Bearer #{bearer_token}" },
      'send_head_request' => true
    }
  end
  nil
end
```

--------------------------------

### Troubleshoot Database Connection Errors

Source: https://github.com/recogito/recogito-studio/blob/main/_autodocs/deployment-and-operations.md

Steps to diagnose database connection issues, including testing the connection, checking pooler logs, and increasing the maximum client connections.

```bash
# Test connection
docker exec supabase-postgres psql -U postgres postgres -c "SELECT version();"

# Check pooler
docker logs supabase-pooler

# Increase connections
POOLER_MAX_CLIENT_CONN=500
docker-compose restart pooler
```
```

--------------------------------

### Using Supabase Client in Edge Function

Source: https://github.com/recogito/recogito-studio/blob/main/_autodocs/edge-functions.md

Demonstrates how to initialize and use the Supabase client within an Edge Function to interact with your Supabase project, including selecting data from a table.

```typescript
import { createClient } from 'https://esm.sh/@supabase/supabase-js@2'

const supabase = createClient(
  Deno.env.get('SUPABASE_URL'),
  Deno.env.get('SUPABASE_SERVICE_ROLE_KEY')
)

const { data, error } = await supabase
  .from('documents')
  .select('*')
```

--------------------------------

### Create Annotation

Source: https://github.com/recogito/recogito-studio/blob/main/_autodocs/api-resources.md

Create a new annotation with specified document, layer, target, body, creator, and motivation. Requires an API key and JSON content type.

```bash
POST /rest/v1/annotations
Authorization: Bearer <API_KEY>
Content-Type: application/json

{
  "document_id": "doc-123",
  "layer_id": "layer-456",
  "target_id": "target-789",
  "body_id": "body-012",
  "creator_id": "user-345",
  "motivation": "commenting"
}
```

--------------------------------

### Configure SMTP Host

Source: https://github.com/recogito/recogito-studio/blob/main/_autodocs/configuration.md

Set the SMTP server hostname for sending emails. Required if ENABLE_EMAIL_SIGNUP is true.

```bash
SMTP_HOST=supabase-mail
```

```bash
SMTP_HOST=smtp.gmail.com
```

--------------------------------

### Set Default Project Name

Source: https://github.com/recogito/recogito-studio/blob/main/_autodocs/configuration.md

Set the default project name for new deployments.

```bash
STUDIO_DEFAULT_PROJECT="Main Project"
```

--------------------------------

### Accessing Environment Variables in Deno

Source: https://github.com/recogito/recogito-studio/blob/main/_autodocs/edge-functions.md

Demonstrates how to access all environment variables available in the Docker container and convert them into a JavaScript object or an array.

```typescript
const envVarsObj = Deno.env.toObject()
const envVars = Object.keys(envVarsObj).map((k) => [k, envVarsObj[k]])
```

--------------------------------

### Annotation Creation Flow

Source: https://github.com/recogito/recogito-studio/blob/main/_autodocs/architecture.md

Details the steps involved in creating an annotation, including client request, Kong validation, PostgREST processing, PostgreSQL operations, and Realtime broadcasting.

```text
1. Client: POST /rest/v1/annotations
   Header: Authorization: Bearer <JWT>
2. Kong: Validate key, check CORS
3. PostgREST: Parse request
4. PostgreSQL: Apply RLS policies
5. PostgREST: Execute INSERT
6. PostgreSQL: Insert row + trigger replication
7. Realtime: Broadcast change to subscribed clients
8. PostgREST: Return created row
9. Client: Receive annotation with ID
```

--------------------------------

### Configure Supabase Service Key

Source: https://github.com/recogito/recogito-studio/blob/main/_autodocs/configuration.md

Provide the Supabase service role API key for server-side operations. This is required for Recogito Studio's integration with Supabase.

```bash
SUPABASE_SERVICE_KEY=eyJhbGciOiJIUzI1NiI...
```

--------------------------------

### Basic-Auth Plugin Configuration

Source: https://github.com/recogito/recogito-studio/blob/main/_autodocs/kong-gateway.md

Sets up the Basic-Auth plugin for username/password validation, with an option to hide credentials from the backend.

```yaml
plugins:
  - name: basic-auth
    config:
      hide_credentials: true
```

--------------------------------

### Realtime WebSocket Route Configuration

Source: https://github.com/recogito/recogito-studio/blob/main/_autodocs/kong-gateway.md

Sets up a Kong route for Realtime WebSocket connections, including CORS, key authentication, and access control.

```yaml
- name: realtime-v1-ws
  url: http://realtime-dev.supabase-realtime:4000/socket
  protocol: ws
  routes:
    - name: realtime-v1-ws
      strip_path: true
      paths:
        - /realtime/v1/
  plugins:
    - name: cors
    - name: key-auth
      config:
        hide_credentials: false
    - name: acl
      config:
        hide_groups_header: true
        allow:
          - admin
          - anon
```

--------------------------------

### Configure Auto-Renewal for Certbot

Source: https://github.com/recogito/recogito-studio/blob/main/_autodocs/deployment-and-operations.md

Set up a cron job to automatically renew Let's Encrypt SSL/TLS certificates. This ensures your Recogito Studio instance remains accessible via HTTPS.

```bash
# Edit crontab
crontab -e

# Add line
0 2 * * * certbot renew --quiet
```

--------------------------------

### Configure Alternative Logflare API Key

Source: https://github.com/recogito/recogito-studio/blob/main/_autodocs/configuration.md

Set an alternative API key for Logflare, which may be used by Vector configuration.

```bash
LOGFLARE_API_KEY=your-api-key
```

--------------------------------

### Pull Latest Code

Source: https://github.com/recogito/recogito-studio/blob/main/README.md

Fetch the most recent version of the Recogito Studio codebase from the repository.

```sh
git pull
```

--------------------------------

### Set PostgreSQL Host

Source: https://github.com/recogito/recogito-studio/blob/main/_autodocs/configuration.md

Configure the hostname or IP address for the PostgreSQL server. Use 'localhost' for Docker internal networks or 'host.docker.internal' for Docker Desktop.

```bash
POSTGRES_HOST=db.example.com
POSTGRES_HOST=localhost    # Docker network internal
POSTGRES_HOST=host.docker.internal  # Host machine (Docker Desktop)
```

--------------------------------

### Configure Supabase Host URL

Source: https://github.com/recogito/recogito-studio/blob/main/_autodocs/configuration.md

Set the Supabase API base URL for application code. This is required for Recogito Studio's integration with Supabase.

```bash
SUPABASE_HOST=https://api.example.com
```

--------------------------------

### View Kong Configuration

Source: https://github.com/recogito/recogito-studio/blob/main/_autodocs/kong-gateway.md

Commands to inspect the Kong configuration and view logs for debugging purposes.

```bash
docker exec supabase-kong kong config init
docker logs supabase-kong
```

--------------------------------

### Configure Cantaloupe HTTP Source Lookup Strategy

Source: https://github.com/recogito/recogito-studio/blob/main/_autodocs/configuration.md

Set the strategy for mapping image identifiers to HTTP URLs when using HttpSource. Options are BasicLookupStrategy or ScriptLookupStrategy.

```bash
CANTALOUPE_HTTPSOURCE_LOOKUP_STRATEGY=ScriptLookupStrategy
```

--------------------------------

### Basic Authentication

Source: https://github.com/recogito/recogito-studio/blob/main/_autodocs/README.md

This method is used for authenticating with the dashboard. It requires a username and password.

```bash
curl -u username:password http://localhost:8000/
```

--------------------------------

### Configure MinIO Root Password

Source: https://github.com/recogito/recogito-studio/blob/main/_autodocs/configuration.md

Set the MinIO root password (secret key). Must be at least 8 characters long.

```bash
MINIO_ROOT_PASSWORD=my-secret-minio-password
```

--------------------------------

### REST API Basics

Source: https://github.com/recogito/recogito-studio/blob/main/_autodocs/api-resources.md

Provides an overview of the basic CRUD operations available through the PostgREST API, including methods, endpoints, and required headers for authentication and content type.

```APIDOC
## REST API Basics

### Description
This section details the fundamental CRUD (Create, Read, Update, Delete) operations supported by the Recogito Studio REST API, which is powered by PostgREST.

### CRUD Operations

| Method | Endpoint | Operation |
|--------|----------|-----------|
| GET | `/rest/v1/{table}` | List rows |
| GET | `/rest/v1/{table}?id=eq.123` | Get single row |
| POST | `/rest/v1/{table}` | Create row |
| PATCH | `/rest/v1/{table}?id=eq.123` | Update row |
| DELETE | `/rest/v1/{table}?id=eq.123` | Delete row |

### Required Headers

```
Authorization: Bearer <SUPABASE_ANON_KEY>
Content-Type: application/json
```

### Query Parameters

| Parameter | Example | Purpose |
|-----------|---------|---------|
| `select` | `id,name` | Choose columns |
| `order_by` | `created_at.desc` | Sort results |
| `limit` | `10` | Limit rows returned |
| `offset` | `20` | Skip rows (pagination) |
| Filters | `id=eq.123`, `name=like.%test%` | Filter rows |
```

--------------------------------

### Disable User Signups

Source: https://github.com/recogito/recogito-studio/blob/main/_autodocs/configuration.md

Controls whether new user registration is allowed. Set to 'true' to disable signups, allowing only existing users to log in.

```bash
DISABLE_SIGNUP=false   # Allow signups
```

```bash
DISABLE_SIGNUP=true    # Disable signups (admin-only)
```

--------------------------------

### Configure Google Cloud Project ID

Source: https://github.com/recogito/recogito-studio/blob/main/_autodocs/configuration.md

Set your Google Cloud project ID for log export.

```bash
GOOGLE_PROJECT_ID=my-gcp-project
```

--------------------------------

### Create Function Directory

Source: https://github.com/recogito/recogito-studio/blob/main/_autodocs/edge-functions.md

Create a directory for your function within the Docker volumes. This is the first step in setting up a new edge function.

```bash
docker/volumes/functions/{name}/
```

--------------------------------

### Select Related Data in Annotations

Source: https://github.com/recogito/recogito-studio/blob/main/_autodocs/api-resources.md

Fetch annotations and include all fields from their related 'body' and 'target' data using the `select` parameter with nested wildcards.

```bash
GET /rest/v1/annotations?select=id,body(*),target(*)
```

--------------------------------

### Configure SMTP User

Source: https://github.com/recogito/recogito-studio/blob/main/_autodocs/configuration.md

Set the SMTP authentication username.

```bash
SMTP_USER=noreply@example.com
```

--------------------------------

### Configure Google Cloud Project Number

Source: https://github.com/recogito/recogito-studio/blob/main/_autodocs/configuration.md

Set your Google Cloud project number for log export.

```bash
GOOGLE_PROJECT_NUMBER=123456789
```

--------------------------------

### Execute Automatic Upgrade Script

Source: https://github.com/recogito/recogito-studio/blob/main/README.md

Run the upgrade script to automatically perform the upgrade process, including code updates, Docker image rebuild, and database schema changes.

```sh
./upgrade.sh
```

--------------------------------

### Configure Cantaloupe HTTP Source Basic Lookup URL Prefix

Source: https://github.com/recogito/recogito-studio/blob/main/_autodocs/configuration.md

Specify the base URL prefix for the HTTP image source when using BasicLookupStrategy.

```bash
CANTALOUPE_HTTPSOURCE_BASICLOOKUPSTRATEGY_URL_PREFIX=http://kong:8000/storage/v1/object/authenticated/documents/
```

--------------------------------

### Set Mail From Address

Source: https://github.com/recogito/recogito-studio/blob/main/_autodocs/configuration.md

Configure the email address used for sending invitations and notifications. This is an optional setting.

```bash
MAIL_FROM_ADDRESS=noreply@example.com
```

--------------------------------

### List Documents with Annotation Count

Source: https://github.com/recogito/recogito-studio/blob/main/_autodocs/api-resources.md

Retrieve a list of documents for a given project, including the count of annotations associated with each document. Requires an API key for authorization.

```bash
GET /rest/v1/documents?project_id=eq.proj-123&select=id,name,annotations:annotations(id)
Authorization: Bearer <API_KEY>
```