# Deploy on Vercel

## Complete guide to deploy Shelve 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](/content/docs/self-hosting/vercel#prerequisites/index.html)

- A [Vercel](https://vercel.com/) account
- A GitHub repository with Shelve source code
- A PostgreSQL database (we recommend [Neon](https://neon.tech/))

## [Recommended Vercel native integrations](/content/docs/self-hosting/vercel#recommended-vercel-native-integrations/index.html)

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

- **Database**: [Neon PostgreSQL](https://vercel.com/integrations/neon)
- **Cache/Session**: [Vercel KV (Redis)](https://vercel.com/storage/kv)
- **Email**: [Resend](https://vercel.com/integrations/resend)
- **AI**: [Vercel AI SDK](https://vercel.com/ai) if you use AI features

These integrations are optimized for Vercel and offer simplified configuration.

## [Quick deployment](/content/docs/self-hosting/vercel#quick-deployment/index.html)

### [1. Fork and deployment](/content/docs/self-hosting/vercel#_1-fork-and-deployment/index.html)

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](/content/docs/self-hosting/vercel#_2-environment-variables-configuration/index.html)

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

## [Required environment variables](/content/docs/self-hosting/vercel#required-environment-variables/index.html)

These variables are **mandatory** for Shelve to work:

```bash
# 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](/content/docs/self-hosting/vercel#security-keys-generation/index.html)

You can generate secure keys with this command:

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

## [Database configuration](/content/docs/self-hosting/vercel#database-configuration/index.html)

Shelve requires a PostgreSQL database. We recommend [Neon](https://neon.tech/) for its excellent Vercel integration, but you can use any PostgreSQL provider.

### [Option 1: Using Vercel-Neon integration (Recommended)](/content/docs/self-hosting/vercel#option-1-using-vercel-neon-integration-recommended/index.html)

1. Use the [Vercel-Neon integration](https://vercel.com/integrations/neon) directly
2. The integration will automatically configure the `DATABASE_URL` environment variable
3. No manual configuration needed

### [Option 2: Manual configuration](/content/docs/self-hosting/vercel#option-2-manual-configuration/index.html)

1. Create a PostgreSQL database with any provider ([Neon](https://neon.tech/), [Supabase](https://supabase.com/), [Railway](https://railway.app/), etc.)
2. Copy the PostgreSQL connection URL
3. Add it as `DATABASE_URL` variable in Vercel project settings

## [Authentication configuration](/content/docs/self-hosting/vercel#authentication-configuration/index.html)

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)](/content/docs/self-hosting/vercel#option-1-email-authentication-recommended/index.html)

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

### [Option 2: OAuth authentication](/content/docs/self-hosting/vercel#option-2-oauth-authentication/index.html)

Configure OAuth providers below for social authentication.

### [GitHub OAuth](/content/docs/self-hosting/vercel#github-oauth/index.html)

To enable GitHub authentication:

```bash
# 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](/content/docs/self-hosting/vercel#google-oauth/index.html)

To enable Google authentication:

```bash
# 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)](/content/docs/self-hosting/vercel#email-service-required-for-email-authentication/index.html)

For email-based authentication using OTP codes:

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

**Important**: These variables are now required if you want to enable email authentication. Without them, users can only authenticate via OAuth providers.

## [Optional environment variables](/content/docs/self-hosting/vercel#optional-environment-variables/index.html)

### [Administration and security](/content/docs/self-hosting/vercel#administration-and-security/index.html)

```bash
# 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](/content/docs/self-hosting/vercel#advanced-github-integration/index.html)

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

### [1. Create a GitHub App](/content/docs/self-hosting/vercel#_1-create-a-github-app/index.html)

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](/content/docs/self-hosting/vercel#_2-configure-private-key/index.html)

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

The GitHub private key must be converted from PKCS#1 to PKCS#8 format, then base64 encoded. Use this command:

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

## [Automatic validation](/content/docs/self-hosting/vercel#automatic-validation/index.html)

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](/content/docs/self-hosting/vercel#deployment/index.html)

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](/content/docs/self-hosting/vercel#custom-domain-configuration/index.html)

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](/content/docs/self-hosting/vercel#monitoring-and-logs/index.html)

Use Vercel tools to monitor your deployment:

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