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
- Fork the Shelve repository to your GitHub account
- Connect your repository to Vercel
- 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)
- Use the Vercel-Neon integration directly
- The integration will automatically configure the
DATABASE_URL
environment variable - No manual configuration needed
Option 2: Manual configuration
- Create a PostgreSQL database with any provider (Neon, Supabase, Railway, etc.)
- Copy the PostgreSQL connection URL
- 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
- Go to your GitHub organization settings
- 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:
- Commit and push your changes (if necessary)
- Vercel will automatically deploy your application
- Your Shelve instance will be accessible at the URL provided by Vercel
Custom domain configuration
- In your Vercel project settings, add your domain
- Configure DNS according to Vercel instructions
- 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