# 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

- 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

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

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

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

You can generate secure keys with this command:

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

## Database configuration

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)

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

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

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:

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

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)

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

<callout type="warning">

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

</callout>

## Optional environment variables

### Administration and security

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

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

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

<callout type="warning">

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

</callout>

## 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