Deployment Guide - Luz de Arcanos

Overview
Prerequisites
Local Development Setup
1. Clone and Install
2. Configure Environment Variables
3. Run Development Server
Vercel Deployment
Method 1: Vercel CLI (Recommended)
Install Vercel CLI
Deploy from Command Line
Method 2: GitHub Integration (Automated)
1. Connect Repository to Vercel
2. Configure Environment Variables
3. Deploy
Build Configuration
Astro SSR Adapter
Build Output
Vercel Function Configuration
Environment Variables
Required Variables
Optional Variables
Setting Variables Locally
Setting Variables on Vercel
Deployment Checklist
Custom Domain Setup
Add Domain to Vercel
DNS Configuration
Monitoring & Logs
View Deployment Logs
Monitor Function Performance
Troubleshooting
Build Fails: “GEMINI_API_KEY not found”
Runtime Error: “429 Rate Limit Exceeded”
Build Warning: “trustedDependencies”
SSR Not Working
Performance Optimization
Edge Functions (Advanced)
Static Asset Optimization
Caching Headers
Rollback & Versioning
Rollback to Previous Deployment
Git-based Versioning
Production Checklist
Next Steps

Overview

Luz de Arcanos is optimized for deployment on Vercel using Astro’s SSR (Server-Side Rendering) mode. This guide covers the complete deployment process from local development to production.

Prerequisites

Node.js

string

required

Node.js 18+ or Bun runtime

Vercel Account

string

required

Free account at vercel.com

Gemini API Key

string

required

Obtain from Google AI Studio

Git Repository

string

required

GitHub, GitLab, or Bitbucket repository

Local Development Setup

1. Clone and Install

# Clone the repository
git clone https://github.com/RamirezDiazCarlos/TarotWeb.git
cd TarotWeb

# Install dependencies
bun install

2. Configure Environment Variables

Create a .env file in the project root:

# Copy the example file
cp .env.example .env

# Edit with your API key
echo "GEMINI_API_KEY=your_actual_api_key_here" > .env

Never commit .env to version control. The .gitignore should already exclude it.

3. Run Development Server

bun dev

The application will be available at http://localhost:4321.

{
  "scripts": {
    "dev": "astro dev",
    "build": "astro build",
    "preview": "astro preview",
    "astro": "astro"
  }
}

See package.json:5-9 for all available scripts.

Vercel Deployment

Method 1: Vercel CLI (Recommended)

Install Vercel CLI

npm i -g vercel

Deploy from Command Line

# First deployment (follow prompts)
vercel

# Set production environment variable
vercel env add GEMINI_API_KEY production
# Paste your API key when prompted

# Deploy to production
vercel --prod

The first vercel command creates a preview deployment. Use vercel --prod for production.

Method 2: GitHub Integration (Automated)

1. Connect Repository to Vercel

Go to vercel.com/new
Click “Import Project”
Select your Git provider (GitHub, GitLab, Bitbucket)
Choose the repository
Vercel will auto-detect Astro configuration

2. Configure Environment Variables

In the Vercel dashboard:

Go to Project Settings → Environment Variables
Add variable:
- Key: GEMINI_API_KEY
- Value: Your Gemini API key
- Environments: Production, Preview (optional), Development (optional)
Click Save

GEMINI_API_KEY=AIza...your_key_here

3. Deploy

Click Deploy. Vercel will:

Install dependencies
Run bun build
Deploy serverless functions
Assign a production URL

Every push to main branch will trigger automatic production deployments. Pull requests create preview deployments.

Build Configuration

Astro SSR Adapter

The project uses the Vercel adapter for SSR:

import { defineConfig } from 'astro/config';
import vercel from '@astrojs/vercel';

export default defineConfig({
  output: 'server',  // Enable SSR mode
  adapter: vercel(), // Vercel serverless adapter
});

output

string

default:"server"

server mode enables SSR. Every route is rendered on-demand.

adapter

function

default:"vercel()"

The Vercel adapter transforms Astro pages into Vercel serverless functions.

See astro.config.mjs:1-9 for the complete configuration.

Build Output

Running bun build produces:

dist/
├── _worker.js/       # Serverless function handlers
├── client/           # Static assets (CSS, JS, images)
└── server/           # SSR entry points

Vercel Function Configuration

Vercel automatically configures:

Runtime: Node.js 18.x (or Bun if detected)
Memory: 1024 MB (default)
Timeout: 10 seconds (Hobby), 60 seconds (Pro)
Regions: Auto (deployed globally)

The 10-second timeout is sufficient for Gemini API calls (~1-3 seconds average).

Environment Variables

Required Variables

GEMINI_API_KEY

string

required

Google Gemini API key. Obtain from Google AI Studio.Format: AIza... (39 characters)

Optional Variables

NODE_ENV

string

default:"production"

Automatically set by Vercel. Use development for local testing.

Setting Variables Locally

# .env file
GEMINI_API_KEY=AIzaSyC...

Setting Variables on Vercel

Via CLI:

vercel env add GEMINI_API_KEY production

Via Dashboard:

Project Settings → Environment Variables
Add GEMINI_API_KEY
Select environments (Production, Preview, Development)
Save

After adding/changing environment variables, you must redeploy for changes to take effect.

Deployment Checklist

Repository pushed to GitHub/GitLab/Bitbucket
.env file created locally (not committed)
Gemini API key obtained from Google AI Studio
Vercel account created
Repository connected to Vercel
GEMINI_API_KEY environment variable set on Vercel
First deployment successful
Production URL tested
Custom domain configured (optional)

Custom Domain Setup

Add Domain to Vercel

Go to Project Settings → Domains
Enter your domain (e.g., luzdearcanos.com)
Follow DNS configuration instructions
Wait for DNS propagation (5 minutes - 24 hours)

DNS Configuration

Add these records to your DNS provider:

Type    Name    Value
A       @       76.76.21.21
CNAME   www     cname.vercel-dns.com

Vercel automatically provisions SSL certificates via Let’s Encrypt.

Monitoring & Logs

View Deployment Logs

Via CLI:

vercel logs <deployment-url>

Via Dashboard:

Go to Deployments
Click on a deployment
View Build Logs or Function Logs

Monitor Function Performance

Vercel Pro provides:

Function execution time
Memory usage
Error rates
Geographic distribution

Hobby plan includes basic logs. Upgrade to Pro for advanced analytics.

Troubleshooting

Build Fails: “GEMINI_API_KEY not found”

Cause: Environment variable not set on Vercel. Solution:

vercel env add GEMINI_API_KEY production
# Redeploy
vercel --prod

Runtime Error: “429 Rate Limit Exceeded”

Cause: Gemini API quota exceeded. Solution: The application automatically falls back to alternative models and then to template-based readings. No action needed.

Build Warning: “trustedDependencies”

Cause: protobufjs requires post-install scripts. Solution: Already handled in package.json:16-18:

"trustedDependencies": [
  "protobufjs"
]

SSR Not Working

Cause: Adapter not configured. Solution: Verify astro.config.mjs:

export default defineConfig({
  output: 'server',      // Must be 'server'
  adapter: vercel(),     // Must include adapter
});

Performance Optimization

Edge Functions (Advanced)

For ultra-low latency, upgrade to Vercel Edge Functions:

// astro.config.mjs
import vercel from '@astrojs/vercel';

export default defineConfig({
  output: 'server',
  adapter: vercel({
    edgeMiddleware: true, // Enable Edge Runtime
  }),
});

Edge Functions have limitations (no Node.js APIs). Test thoroughly before deploying.

Static Asset Optimization

Images: Compress with tools like Squoosh
Video: Optimize background video (720p is sufficient)
Fonts: Preconnect to Google Fonts (already configured)

Caching Headers

Add caching for static assets:

// vercel.json (optional)
{
  "headers": [
    {
      "source": "/cards/(.*)",
      "headers": [
        {
          "key": "Cache-Control",
          "value": "public, max-age=31536000, immutable"
        }
      ]
    }
  ]
}

Rollback & Versioning

Rollback to Previous Deployment

Via Dashboard:

Go to Deployments
Find previous successful deployment
Click ⋮ → Promote to Production

Via CLI:

vercel rollback

Git-based Versioning

# Create release tag
git tag -a v1.0.0 -m "Production release"
git push origin v1.0.0

# Rollback to tag
git checkout v1.0.0
vercel --prod

Vercel keeps deployment history for 30 days (Hobby) or unlimited (Pro).

Production Checklist

Environment variables verified in production
Test consultation flow end-to-end
Check mobile responsiveness
Verify SEO meta tags (Open Graph, Twitter Card)
Test usage limit (5 consultations)
Confirm fallback reading works (simulate API failure)
Check video background loads on mobile
Validate SSL certificate
Set up monitoring alerts (Pro plan)

Next Steps

After successful deployment:

Monitor usage: Check Vercel analytics
Set up alerts: Configure email notifications for errors
Optimize costs: Review Gemini API usage
Add analytics: Integrate Google Analytics or Plausible
Custom domain: Configure your own domain name

Live demo: luzdearcanos.vercel.app

AI Integration

Configuration Reference

⌘I

Get Started

Features

User Guide

Technical

Resources

​Overview

​Prerequisites

​Local Development Setup

​1. Clone and Install

​2. Configure Environment Variables

​3. Run Development Server

​Vercel Deployment

​Method 1: Vercel CLI (Recommended)

​Install Vercel CLI

​Deploy from Command Line

​Method 2: GitHub Integration (Automated)

​1. Connect Repository to Vercel

​2. Configure Environment Variables

​3. Deploy

​Build Configuration

​Astro SSR Adapter

​Build Output

​Vercel Function Configuration

​Environment Variables

​Required Variables

​Optional Variables

​Setting Variables Locally

​Setting Variables on Vercel

​Deployment Checklist

​Custom Domain Setup

​Add Domain to Vercel

​DNS Configuration

​Monitoring & Logs

​View Deployment Logs

​Monitor Function Performance

​Troubleshooting

​Build Fails: “GEMINI_API_KEY not found”

​Runtime Error: “429 Rate Limit Exceeded”

​Build Warning: “trustedDependencies”

​SSR Not Working

​Performance Optimization

​Edge Functions (Advanced)

​Static Asset Optimization

​Caching Headers

​Rollback & Versioning

​Rollback to Previous Deployment

​Git-based Versioning

​Production Checklist

​Next Steps

Overview

Prerequisites

Local Development Setup

1. Clone and Install

2. Configure Environment Variables

3. Run Development Server

Vercel Deployment

Method 1: Vercel CLI (Recommended)

Install Vercel CLI

Deploy from Command Line

Method 2: GitHub Integration (Automated)

1. Connect Repository to Vercel

2. Configure Environment Variables

3. Deploy

Build Configuration

Astro SSR Adapter

Build Output

Vercel Function Configuration

Environment Variables

Required Variables

Optional Variables

Setting Variables Locally

Setting Variables on Vercel

Deployment Checklist

Custom Domain Setup

Add Domain to Vercel

DNS Configuration

Monitoring & Logs

View Deployment Logs

Monitor Function Performance

Troubleshooting

Build Fails: “GEMINI_API_KEY not found”

Runtime Error: “429 Rate Limit Exceeded”

Build Warning: “trustedDependencies”

SSR Not Working

Performance Optimization

Edge Functions (Advanced)

Static Asset Optimization

Caching Headers

Rollback & Versioning

Rollback to Previous Deployment

Git-based Versioning

Production Checklist

Next Steps