| v2.3.3

Environment variables

Complete reference of Shelve 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

Recommendation: Use Neon with Vercel integration for simplified configuration.

`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

Important: Never modify these keys after first deployment, it would make existing data inaccessible.

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

Required setup: This variable requires a GitHub App configured with comprehensive permissions including Secrets, Variables, and more. See the Vercel documentation for the complete permissions list.

How to get this key

Create a GitHub App in your organization
Download the private key (.pem format)
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

Important: This variable is now required if you want to use email authentication (OTP). Without it, users can only authenticate via OAuth providers.

Recommendation: Use Resend with Vercel integration for automated configuration.

`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:

Vercel Project > Settings > Environment Variables
Add each variable with its value
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.

Report an issue or Edit this page on GitHub

Introduction

Help us improve Shelve by contributing to the project.