Environment variables

This page documents all environment variables available in Shelve, their usage and configuration.

Required variables

These environment variables are mandatory for Shelve to function:

DATABASE_URL

• Type: String (PostgreSQL URL)
• Required: ✅ Yes
• Description: Connection URL to your PostgreSQL database
• Format: postgresql://username:password@host:port/database
• Example: postgresql://user:pass@db.example.com:5432/shelve

NUXT_SESSION_PASSWORD

• Type: String
• Required: ✅ Yes
• Constraint: Minimum 32 characters
• Description: Secret key to sign and encrypt user sessions
• Generation: openssl rand -base64 48

NUXT_PRIVATE_ENCRYPTION_KEY

• Type: String
• Required: ✅ Yes
• Constraint: Minimum 32 characters
• Description: Master key to encrypt sensitive data in the database
• Generation: openssl rand -base64 48

Authentication configuration

Shelve now supports multiple authentication methods. You need to configure at least one method for users to be able to create accounts and log in:

Option 1: Email authentication only (Recommended)

• Configure NUXT_PRIVATE_RESEND_API_KEY and NUXT_PRIVATE_SENDER_EMAIL
• Users can sign up and log in using their email with OTP codes
• No OAuth setup required

Option 2: OAuth only

• Configure at least one OAuth provider (GitHub or Google)
• Users authenticate via OAuth providers
• No email service required

Option 3: Both methods (Maximum flexibility)

• Configure both email service and OAuth providers
• Users can choose their preferred authentication method
• Recommended for production environments

Authentication variables

Shelve supports multiple authentication methods. You need at least one authentication method configured:

Email authentication (OTP)

For email-based authentication using one-time passwords (OTP), you need to configure email service variables below.

OAuth authentication (Optional)

OAuth providers offer an alternative authentication method alongside email authentication.

GitHub OAuth

To enable GitHub authentication, configure these two variables together:

NUXT_OAUTH_GITHUB_CLIENT_ID

• Type: String
• Required: 🔶 Optional (must be paired with CLIENT_SECRET)
• Description: Client ID of your GitHub OAuth App
• How to get: GitHub Developer Settings

NUXT_OAUTH_GITHUB_CLIENT_SECRET

• Type: String
• Required: 🔶 Optional (must be paired with CLIENT_ID)
• Description: Client Secret of your GitHub OAuth App
• How to get: GitHub Developer Settings

Google OAuth

To enable Google authentication, configure these two variables together:

NUXT_OAUTH_GOOGLE_CLIENT_ID

• Type: String
• Required: 🔶 Optional (must be paired with CLIENT_SECRET)
• Description: Client ID of your Google OAuth App
• How to get: Google Cloud Console

NUXT_OAUTH_GOOGLE_CLIENT_SECRET

• Type: String
• Required: 🔶 Optional (must be paired with CLIENT_ID)
• Description: Client Secret of your Google OAuth App
• How to get: Google Cloud Console

GitHub integration variables

NUXT_PRIVATE_GITHUB_PRIVATE_KEY

• Type: String (Base64)
• Required: 🔶 Optional
• Description: Private key of your GitHub App for advanced integration
• Usage: Automatic secrets synchronization with GitHub
• Format: PKCS#8 encoded in base64

How to get this key

1. Create a GitHub App in your organization
2. Download the private key (.pem format)
3. Convert it to PKCS#8 format and encode in base64:

openssl pkcs8 -topk8 -inform PEM -outform PEM -nocrypt -in private-key.pem | base64 -w 0

Email service variables

NUXT_PRIVATE_RESEND_API_KEY

• Type: String
• Required: ⚠️ Required for email authentication (OTP)
• Format: Must start with re_
• Description: Resend API key for sending emails including OTP codes
• Usage: OTP authentication, welcome emails, notifications
• How to get: Resend Dashboard

NUXT_PRIVATE_SENDER_EMAIL

• Type: String (Email)
• Required: ⚠️ Required for email authentication (required if RESEND_API_KEY is set)
• Description: Sender email address for OTP codes and notifications
• Format: noreply@yourdomain.com
• Constraint: Must be a valid email verified in Resend

Administration variables

NUXT_PRIVATE_ADMIN_EMAILS

• Type: String (comma-separated list)
• Required: 🔶 Optional
• Description: List of emails with access to admin features
• Format: admin@app.com,admin2@app.com
• Usage: Access to statistics, user management

NUXT_PRIVATE_ALLOWED_ORIGINS

• Type: String (comma-separated list of URLs)
• Required: 🔶 Optional
• Description: Allowed origins for CORS requests
• Format: https://app.com,https://www.app.com
• Usage: Security, CSRF attack prevention

Automatic validation

Shelve uses an automatic environment variables validation system:

• Startup validation: The application checks all required variables
• Format validation: URLs, emails, minimum lengths are verified
• Consistency validation: OAuth pairs are validated together
• Explicit error messages: In case of error, logs indicate exactly what's wrong

Configuration by environment

Local development

Create a .env file at the root of your project:

# Copy from .env.example
DATABASE_URL=postgresql://localhost:5432/shelve_dev
NUXT_SESSION_PASSWORD=your-dev-session-password-32-chars-min
NUXT_PRIVATE_ENCRYPTION_KEY=your-dev-encryption-key-32-chars-min

Production on Vercel

Configure all variables in your Vercel project settings:

1. Vercel Project > Settings > Environment Variables
2. Add each variable with its value
3. Select appropriate environments (Production, Preview, Development)

Troubleshooting

Common errors

"Session password must be at least 32 characters long"

• Generate a longer key: openssl rand -base64 48

"Must be a valid PostgreSQL URL"

• Check the format: postgresql://user:pass@host:port/db
• Test the connection to your database

"GitHub OAuth validation failed"

• Make sure you have defined CLIENT_ID AND CLIENT_SECRET together
• Verify that the values are correct

"Resend API key must start with 're_'"

• Use the Resend API key, not a test key
• Verify that you copied the complete key

Missing environment variables

Vercel deployment logs will show:

🔐 Auth configuration validated:
  GitHub OAuth: ✅/❌
  Google OAuth: ✅/❌  
  Email Service: ✅/❌

This allows you to quickly check which integrations are active.