Configuration

Configure your Colibri instance

6 min read

Colibri is configured through environment variables and instance settings. This guide covers all configuration options for both development and production environments.

Environment Variables

Environment variables are set in a .env file at the root of the project or configured through your hosting provider.

Database Configuration

Variable	Description	Default	Required
`DB_URL`	PostgreSQL connection string	-	Yes
`DATABASE_CERTIFICATE`	Base64-encoded CA certificate for SSL	-	No

Example:

bash

# Development (local PostgreSQL)
DB_URL=postgresql://colibri:password@localhost:5432/colibri

# Production (with SSL)
DB_URL=postgresql://user:pass@db.example.com:5432/colibri?sslmode=require
DATABASE_CERTIFICATE=LS0tLS1CRUdJTiBDRVJUSUZJQ0FURS0tLS0t...

Connection pool settings are managed automatically, but you can tune them by appending query parameters:

bash

DB_URL=postgresql://user:pass@host:5432/colibri?pool_min=2&pool_max=10

Storage Configuration

Variable	Description	Default	Required
`STORAGE_S3_URL`	S3-compatible endpoint URL	-	Yes
`S3_PROTOCOL_ACCESS_KEY_ID`	S3 access key	-	Yes
`S3_PROTOCOL_ACCESS_KEY_SECRET`	S3 secret key	-	Yes
`S3_PROTOCOL_REGION`	S3 region	`us-east-1`	No
`S3_BUCKET_ASSETS`	Bucket name for ebook files	`colibri`	No
`S3_BUCKET_COVERS`	Bucket name for cover images	`colibri`	No

Example:

bash

# MinIO (local development)
STORAGE_S3_URL=http://localhost:9000
S3_PROTOCOL_ACCESS_KEY_ID=minioadmin
S3_PROTOCOL_ACCESS_KEY_SECRET=minioadmin
S3_PROTOCOL_REGION=us-east-1
S3_BUCKET_ASSETS=colibri
S3_BUCKET_COVERS=colibri

# AWS S3
STORAGE_S3_URL=https://s3.amazonaws.com
S3_PROTOCOL_ACCESS_KEY_ID=AKIAIOSFODNN7EXAMPLE
S3_PROTOCOL_ACCESS_KEY_SECRET=wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY
S3_PROTOCOL_REGION=us-west-2
S3_BUCKET_ASSETS=my-colibri-books
S3_BUCKET_COVERS=my-colibri-covers

# Cloudflare R2
STORAGE_S3_URL=https://your-account-id.r2.cloudflarestorage.com
S3_PROTOCOL_ACCESS_KEY_ID=your-access-key
S3_PROTOCOL_ACCESS_KEY_SECRET=your-secret-key
S3_PROTOCOL_REGION=auto
S3_BUCKET_ASSETS=colibri
S3_BUCKET_COVERS=colibri

See the Storage Configuration guide for provider-specific details.

Application Configuration

Variable	Description	Default	Required
`PUBLIC_BASE_URL`	Public URL of your instance	-	Yes
`APP_SECRET_KEY`	Secret key for encryption	-	Yes
`NODE_ENV`	Environment mode	`production`	No
`PORT`	HTTP port to listen on	`3000`	No

Example:

bash

# Development
PUBLIC_BASE_URL=http://localhost:5173
APP_SECRET_KEY=$(openssl rand -hex 32)
NODE_ENV=development

# Production
PUBLIC_BASE_URL=https://library.example.com
APP_SECRET_KEY=<your-generated-key>
NODE_ENV=production
PORT=3000

Important: Generate a unique APP_SECRET_KEY for your instance:

bash

openssl rand -hex 32

Never share or commit this key to version control.

Authentication Configuration

Variable	Description	Default	Required
`JWT_SECRET`	JWT signing secret	-	Yes
`SERVICE_ROLE_KEY`	Service role JWT key	-	Yes
`ANON_KEY`	Anonymous access JWT key	-	Yes
`SESSION_ID_COOKIE_NAME`	Session cookie name	`ksid`	No
`AUTH_TOKEN_COOKIE_NAME`	Auth token cookie name	`ktok`	No
`PUBLIC_PASSCODE_LENGTH`	Length of email passcodes	`6`	No
`PUBLIC_PASSCODE_TTL`	Passcode expiration (seconds)	`300`	No

Example:

bash

# Auto-generated by Supabase
JWT_SECRET=your-jwt-secret
SERVICE_ROLE_KEY=your-service-role-key
ANON_KEY=your-anon-key

# Optional customization
SESSION_ID_COOKIE_NAME=colibri_session
AUTH_TOKEN_COOKIE_NAME=colibri_token
PUBLIC_PASSCODE_LENGTH=8
PUBLIC_PASSCODE_TTL=600  # 10 minutes

If using Supabase, these are auto-generated. For manual PostgreSQL setups, generate them:

bash

# JWT secret (256-bit)
openssl rand -base64 32

# Service role and anon keys are JWTs signed with JWT_SECRET
# Use Supabase's JWT generator or implement your own

OAuth Configuration

Variable	Description	Default	Required
`OAUTH_ISSUER`	OAuth issuer URL	-	No
`OAUTH_AUTHORIZATION_CODE_TTL`	Auth code expiration (seconds)	`60`	No
`OAUTH_ACCESS_TOKEN_TTL`	Access token expiration (seconds)	`3600`	No
`OAUTH_REFRESH_TOKEN_TTL`	Refresh token expiration (seconds)	`604800`	No
`OAUTH_DEVICE_CODE_TTL`	Device code expiration (seconds)	`1800`	No
`OAUTH_DEVICE_POLLING_INTERVAL`	Device flow polling interval (seconds)	`5`	No
`OAUTH_CONSENT_TTL`	Consent expiration (seconds)	`604800`	No

Example:

bash

# OAuth server configuration
OAUTH_ISSUER=https://library.example.com
OAUTH_AUTHORIZATION_CODE_TTL=60
OAUTH_ACCESS_TOKEN_TTL=3600  # 1 hour
OAUTH_REFRESH_TOKEN_TTL=604800  # 7 days
OAUTH_DEVICE_CODE_TTL=1800  # 30 minutes
OAUTH_DEVICE_POLLING_INTERVAL=5
OAUTH_CONSENT_TTL=604800  # 7 days

OAuth is used for third-party app integrations and API access. See the CLI OAuth commands for details.

Email Configuration (Optional)

Variable	Description	Default	Required
`MAILJET_API_KEY`	Mailjet API key	-	No
`MAILJET_SECRET_KEY`	Mailjet secret key	-	No

Example:

bash

MAILJET_API_KEY=your-mailjet-api-key
MAILJET_SECRET_KEY=your-mailjet-secret-key

Email is used for:

Email-based authentication (passcodes)
User invitations
Notifications (optional)

If not configured, authentication will use Passkeys only.

External Services

Variable	Description	Default	Required
`PUBLIC_GUTENDEX_INSTANCE_URL`	Gutendex API URL	`https://gutendex.com/`	No
`PUBLIC_HELP_CENTER_BASE_URL`	Help documentation URL	-	No

Example:

bash

PUBLIC_GUTENDEX_INSTANCE_URL=https://gutendex.com/
PUBLIC_HELP_CENTER_BASE_URL=https://help.example.com

Development Options

Variable	Description	Default	Required
`LLMS_TXT_ENABLED`	Enable llms.txt endpoint	`true`	No

Example:

bash

# Enable AI/LLM documentation endpoint
LLMS_TXT_ENABLED=true

The llms.txt endpoint exposes metadata about your instance for AI tools.

Instance Settings

Instance settings are managed through the web interface or CLI. These are stored in the database and apply to all users.

Accessing Instance Settings

Via Web Interface:

Log in as an administrator
Navigate to Settings > Instance
Configure settings and click Save

Via CLI:

bash

# View all settings
colibri settings get

# Set a specific setting
colibri settings set <key> <value>

General Settings

Instance Information

Setting	Description	Default
Instance Name	Display name for your library	`Colibri`
Instance Description	Description shown on login page	-
Instance Icon	Icon/logo URL	-

Example:

bash

colibri settings set instance.name "My Library"
colibri settings set instance.description "A personal ebook collection"
colibri settings set instance.icon "https://example.com/logo.png"

Registration Settings

Setting	Description	Default
Allow Registration	Enable/disable new user registration	`true`
Require Email Verification	Require email verification for new accounts	`true`
Default User Role	Default role for new users	`adult`

Example:

bash

colibri settings set auth.registration.enabled false
colibri settings set auth.registration.emailVerification true
colibri settings set auth.registration.defaultRole adult

Metadata Provider Settings

Configure API keys for external metadata providers. See the Metadata Enrichment guide for provider details.

Google Books

Setting URN	Description	Required
`urn:colibri:settings:metadata:google-books-key`	Google Books API key	No

Get an API key from the Google Cloud Console.

Via CLI:

bash

colibri settings set urn:colibri:settings:metadata:google-books-key YOUR_API_KEY

ISBNdb

Setting URN	Description	Required
`urn:colibri:settings:metadata:isbndb-api-key`	ISBNdb API key	No

Via CLI:

bash

colibri settings set urn:colibri:settings:metadata:isbndb-api-key YOUR_API_KEY

Springer Nature

Setting URN	Description	Required
`urn:colibri:settings:metadata:springer-key`	Springer API key	No

Via CLI:

bash

colibri settings set urn:colibri:settings:metadata:springer-key YOUR_API_KEY

Amazon Product Advertising API

Setting URN	Description	Required
`urn:colibri:settings:metadata:amazon-access-key`	AWS access key	Yes*
`urn:colibri:settings:metadata:amazon-secret-key`	AWS secret key	Yes*
`urn:colibri:settings:metadata:amazon-partner-tag`	Associate tag	Yes*
`urn:colibri:settings:metadata:amazon-region`	Marketplace region	Yes*

*Required if using Amazon as a metadata provider.

Supported regions: us, uk, de, fr, jp, ca, it, es, au

Via CLI:

bash

colibri settings set urn:colibri:settings:metadata:amazon-access-key YOUR_ACCESS_KEY
colibri settings set urn:colibri:settings:metadata:amazon-secret-key YOUR_SECRET_KEY
colibri settings set urn:colibri:settings:metadata:amazon-partner-tag YOUR_TAG
colibri settings set urn:colibri:settings:metadata:amazon-region us

Free Metadata Providers

These providers work without configuration:

Open Library: Books, authors, covers, subjects
WikiData: Authority data, identifiers
Library of Congress: Bibliographic data, subjects
Internet Archive: Public domain books, covers
DOAB: Open access academic books
DNB: German National Library
BNB: British National Bibliography
VIAF: Virtual authority records
ISNI: Author identifiers
Crossref: Academic publications, DOIs

Configuration Examples

Development Environment

Minimal configuration for local development:

bash

# .env
DB_URL=postgresql://colibri:colibri@localhost:5432/colibri
STORAGE_S3_URL=http://localhost:9000
S3_PROTOCOL_ACCESS_KEY_ID=minioadmin
S3_PROTOCOL_ACCESS_KEY_SECRET=minioadmin
S3_PROTOCOL_REGION=us-east-1
PUBLIC_BASE_URL=http://localhost:5173
APP_SECRET_KEY=$(openssl rand -hex 32)
NODE_ENV=development

Production Environment

Complete configuration for production deployment:

bash

# .env
# Database (managed PostgreSQL with SSL)
DB_URL=postgresql://user:pass@db.example.com:5432/colibri?sslmode=require
DATABASE_CERTIFICATE=<base64-ca-cert>

# Storage (AWS S3)
STORAGE_S3_URL=https://s3.amazonaws.com
S3_PROTOCOL_ACCESS_KEY_ID=AKIAIOSFODNN7EXAMPLE
S3_PROTOCOL_ACCESS_KEY_SECRET=wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY
S3_PROTOCOL_REGION=us-west-2
S3_BUCKET_ASSETS=my-library-books
S3_BUCKET_COVERS=my-library-covers

# Application
PUBLIC_BASE_URL=https://library.example.com
APP_SECRET_KEY=<generated-secret-key>
NODE_ENV=production
PORT=3000

# Authentication
JWT_SECRET=<generated-jwt-secret>
SERVICE_ROLE_KEY=<generated-service-key>
ANON_KEY=<generated-anon-key>
SESSION_ID_COOKIE_NAME=colibri_session
AUTH_TOKEN_COOKIE_NAME=colibri_token

# Email
MAILJET_API_KEY=<your-mailjet-api-key>
MAILJET_SECRET_KEY=<your-mailjet-secret-key>

# OAuth
OAUTH_ISSUER=https://library.example.com
OAUTH_ACCESS_TOKEN_TTL=3600
OAUTH_REFRESH_TOKEN_TTL=604800

Docker Compose Environment

For Docker deployments, use environment variables in docker-compose.yaml:

yaml

services:
  colibri:
    environment:
      DB_URL: "postgresql://colibri:colibri@postgres:5432/colibri"
      STORAGE_S3_URL: "http://minio:9000"
      S3_PROTOCOL_ACCESS_KEY_ID: "colibri"
      S3_PROTOCOL_ACCESS_KEY_SECRET: "password"
      PUBLIC_BASE_URL: "http://localhost:3000"
      APP_SECRET_KEY: "${APP_SECRET_KEY}"

And create a .env file for secrets:

bash

APP_SECRET_KEY=your-generated-secret

Security Best Practices

Secrets Management

Never commit secrets to version control:

bash

# .gitignore
.env
.env.local
.env.production

Generate strong secrets:

bash

# 256-bit secret
openssl rand -hex 32

# Or use a password manager
# 1Password, Bitwarden, LastPass, etc.

Use environment-specific files:

.env.development
.env.production
.env.test

Database Security

Always use SSL in production:

bash

DB_URL=postgresql://user:pass@host:5432/db?sslmode=require

Rotate database credentials regularly:

Create new user with same permissions
Update DB_URL
Restart application
Remove old user

Limit database access:

sql

-- Create read-only user for reporting
CREATE USER colibri_readonly WITH PASSWORD 'password';
GRANT SELECT ON ALL TABLES IN SCHEMA public TO colibri_readonly;

Storage Security

Use private buckets:

S3 buckets should NOT have public read access
Colibri uses signed URLs for file access

Rotate storage credentials:

Generate new access keys
Update environment variables
Restart application
Deactivate old keys

Enable versioning (recommended):

Protects against accidental deletions
Allows file recovery

Environment-Specific Configuration

Vercel

Create environment variables in the Vercel dashboard:

Go to your project settings
Navigate to Environment Variables
Add all required variables
Separate values for Production, Preview, and Development

Railway

Set environment variables in Railway dashboard:

Select your project
Go to Variables tab
Add variables
Deploy

Fly.io

Use fly secrets command:

bash

fly secrets set APP_SECRET_KEY=your-secret
fly secrets set DB_URL=postgresql://...

Or use fly.toml:

toml

[env]
  PUBLIC_BASE_URL = "https://your-app.fly.dev"
  NODE_ENV = "production"

# Secrets go in fly secrets, not here

Troubleshooting Configuration

Environment Variables Not Loading

Symptoms: Application uses default values or fails to start

Solutions:

Verify .env file is in the correct directory (project root)
Check for syntax errors in .env (no spaces around =)
Ensure .env is not in .gitignore for local development
Restart the application after changes

Database Connection Issues

Symptoms: “Connection refused” or “authentication failed”

Solutions:

Verify DB_URL format
Check database is running and accessible
Test connection: psql $DB_URL
For SSL errors, check DATABASE_CERTIFICATE
Verify firewall allows PostgreSQL port (5432)

Storage Connection Issues

Symptoms: “Access denied” or “bucket not found”

Solutions:

Verify credentials are correct
Check bucket exists
Test with AWS CLI: aws s3 ls s3://your-bucket
For MinIO, verify endpoint URL format
Check S3 region matches bucket region

JWT/Authentication Issues

Symptoms: “Invalid token” or “Unauthorized” errors

Solutions:

Verify JWT_SECRET, SERVICE_ROLE_KEY, and ANON_KEY are set
Ensure secrets haven’t been rotated without updating env vars
Check cookie names don’t conflict with other apps
Clear browser cookies and try again

Next Steps

After configuring your instance:

Set up storage in detail - Configure S3 providers
Create your first account - Set up admin user
Configure metadata providers - Enable enrichment
Upload books - Start building your library

Configuration Reference

For a complete list of all environment variables, see:

.env.example in the repository
Architecture Overview for technical details

Environment Variables ​

Database Configuration ​

Storage Configuration ​

Application Configuration ​

Authentication Configuration ​

OAuth Configuration ​

Email Configuration (Optional) ​

External Services ​

Development Options ​

Instance Settings ​

Accessing Instance Settings ​

General Settings ​

Instance Information ​

Registration Settings ​

Metadata Provider Settings ​

Google Books ​

ISBNdb ​

Springer Nature ​

Amazon Product Advertising API ​

Free Metadata Providers ​

Configuration Examples ​

Development Environment ​

Production Environment ​

Docker Compose Environment ​

Security Best Practices ​

Secrets Management ​

Database Security ​

Storage Security ​

Environment-Specific Configuration ​

Vercel ​

Railway ​

Fly.io ​

Troubleshooting Configuration ​

Environment Variables Not Loading ​

Database Connection Issues ​

Storage Connection Issues ​

JWT/Authentication Issues ​

Next Steps ​

Configuration Reference ​

Environment Variables

Database Configuration

Storage Configuration

Application Configuration

Authentication Configuration

OAuth Configuration

Email Configuration (Optional)

External Services

Development Options

Instance Settings

Accessing Instance Settings

General Settings

Instance Information

Registration Settings

Metadata Provider Settings

Google Books

ISBNdb

Springer Nature

Amazon Product Advertising API

Free Metadata Providers

Configuration Examples

Development Environment

Production Environment

Docker Compose Environment

Security Best Practices

Secrets Management

Database Security

Storage Security

Environment-Specific Configuration

Vercel

Railway

Fly.io

Troubleshooting Configuration

Environment Variables Not Loading

Database Connection Issues

Storage Connection Issues

JWT/Authentication Issues

Next Steps

Configuration Reference