Deploy on Vercel

Vercel is the official recommended provider for self-hosting Shelve. This platform offers native integration with the ecosystem that Shelve uses and greatly simplifies deployment.

Prerequisites

• A Vercel account
• A GitHub repository with Shelve source code
• A PostgreSQL database (we recommend Neon)

Recommended Vercel native integrations

For an optimal experience, we recommend using Vercel's native integrations:

• Database: Neon PostgreSQL
• Cache/Session: Vercel KV (Redis)
• Email: Resend
• AI: Vercel AI SDK if you use AI features

These integrations are optimized for Vercel and offer simplified configuration.

Quick deployment

1. Fork and deployment

1. Fork the Shelve repository to your GitHub account
2. Connect your repository to Vercel
3. Vercel will automatically detect that it's a Nuxt application

2. Environment variables configuration

Before the first deployment, you need to configure environment variables. Go to your Vercel project settings > Environment Variables.

Required environment variables

These variables are mandatory for Shelve to work:

# PostgreSQL database
DATABASE_URL=postgresql://username:password@host:port/database

# Security (generate random keys of 32+ characters)
NUXT_SESSION_PASSWORD=your-32-character-minimum-session-password
NUXT_PRIVATE_ENCRYPTION_KEY=your-32-character-minimum-encryption-key

Security keys generation

You can generate secure keys with this command:

# Generates a 64-character key
openssl rand -base64 48

Database configuration

Shelve requires a PostgreSQL database. We recommend Neon for its excellent Vercel integration, but you can use any PostgreSQL provider.

Option 1: Using Vercel-Neon integration (Recommended)

1. Use the Vercel-Neon integration directly
2. The integration will automatically configure the DATABASE_URL environment variable
3. No manual configuration needed

Option 2: Manual configuration

1. Create a PostgreSQL database with any provider (Neon, Supabase, Railway, etc.)
2. Copy the PostgreSQL connection URL
3. Add it as DATABASE_URL variable in Vercel project settings

Authentication configuration

Shelve supports multiple authentication methods. You need at least one authentication method configured for users to create accounts and log in.

Option 1: Email authentication (Recommended)

Configure email service variables below to enable OTP-based authentication via email.

Option 2: OAuth authentication

Configure OAuth providers below for social authentication.

GitHub OAuth

To enable GitHub authentication:

# GitHub OAuth (both variables are required together)
NUXT_OAUTH_GITHUB_CLIENT_ID=your_github_client_id
NUXT_OAUTH_GITHUB_CLIENT_SECRET=your_github_client_secret

Google OAuth

To enable Google authentication:

# Google OAuth (both variables are required together)
NUXT_OAUTH_GOOGLE_CLIENT_ID=your_google_client_id
NUXT_OAUTH_GOOGLE_CLIENT_SECRET=your_google_client_secret

Email service (Required for email authentication)

For email-based authentication using OTP codes:

# Resend API key (required for email authentication)
NUXT_PRIVATE_RESEND_API_KEY=re_your_resend_api_key
NUXT_PRIVATE_SENDER_EMAIL=noreply@yourapp.com

Optional environment variables

Administration and security

# Admin emails (comma-separated)
NUXT_PRIVATE_ADMIN_EMAILS=admin@yourapp.com,admin2@yourapp.com

# Allowed origins for CORS (comma-separated)
NUXT_PRIVATE_ALLOWED_ORIGINS=https://yourapp.com,https://www.yourapp.com

Advanced GitHub integration

To use GitHub integration (secrets synchronization), you need to configure a GitHub App:

1. Create a GitHub App

1. Go to your GitHub organization settings
2. Create a new GitHub App with the following permissions:

Repository permissions:

• Actions: Read
• Administration: Read
• Contents: Read
• Metadata: Read
• Secrets: Read and write
• Variables: Read and write
• Webhooks: Read and write

Organization permissions:

• Secrets: Read and write
• Variables: Read and write

2. Configure private key

# GitHub private key (PKCS#8 base64 format)
NUXT_PRIVATE_GITHUB_PRIVATE_KEY=your_base64_encoded_private_key

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

Automatic validation

Shelve automatically validates environment variables configuration at startup. If a required variable is missing or invalid, the application will display a detailed error.

Vercel deployment logs will show you:

• ✅ GitHub OAuth: enabled/disabled
• ✅ Google OAuth: enabled/disabled
• ✅ Email Service: enabled/disabled

Deployment

Once all variables are configured:

1. Commit and push your changes (if necessary)
2. Vercel will automatically deploy your application
3. Your Shelve instance will be accessible at the URL provided by Vercel

Custom domain configuration

1. In your Vercel project settings, add your domain
2. Configure DNS according to Vercel instructions
3. Update NUXT_PRIVATE_ALLOWED_ORIGINS with your new domain

Monitoring and logs

Use Vercel tools to monitor your deployment:

• Functions: API routes performance
• Analytics: Traffic and performance
• Logs: Real-time debugging