Site-Snap - Website to PDF Capture & Annotation

Version 1.0.0

Introduction

Support: SakuraLeaf

Site-Snap is a full-featured SaaS application for capturing website snapshots as PDFs, editing them with annotations, and managing projects with subscription billing. Users can enter any URL, generate a high-quality PDF, annotate it with drawing tools, and save and share or download the result.

This documentation covers everything you need to install, configure, and deploy Site-Snap as your own SaaS platform.

Tech Stack

• Framework: Next.js (App Router) with TypeScript
• Database: PostgreSQL via Prisma ORM
• Hosting DB: Supabase (free tier works)
• Authentication: NextAuth.js (Credentials + Google OAuth)
• Payments: Paddle (subscriptions)
• Email: Resend (verification & password reset)
• Storage: AWS S3 (PDFs & thumbnails) or local filesystem
• CAPTCHA: Cloudflare Turnstile
• PDF Editor: Konva.js canvas for annotations
• Internationalization: next-intl (RTL support also)

Requirements

1. Node.js 18+ and npm (or yarn)
2. A Supabase account (free tier works) for the PostgreSQL database
3. A Vercel account (for production deployment) or any Node.js hosting

Supabase Database Setup

Site-Snap uses PostgreSQL as its database. Supabase provides a free hosted PostgreSQL instance that works for both local development and production.

• 1. Create a Supabase account
  Visit supabase.com and sign up for a free account.
• 2. Create a new project
  1. Click New Project in your Supabase dashboard.
  2. Choose a name (e.g. site-snap), set a strong database password, and select a region close to your users.
  3. Click "Generate a password". It will generate a URL-friendly password. Otherwise, if your password contains special characters (@ : / ? # & %), it needs to be URL-encoded.
  4. Click Create new project and wait for provisioning to complete.
• 3. Get the PostgreSQL connection string
  1. In your project dashboard, go to Settings > Database.
  2. Scroll to Connection string and select the URI tab.
  3. The connection string format looks like:
     postgresql://postgres:[YOUR-PASSWORD]@db.zdzrufvqywoxerasdwji.supabase.co:5432/postgres
  4. Severless DB connection URL:
     Note! When using in production on a serverless platform like Vercel, use the "Transaction pooler" URL (only in production, use the default above for migrations from localhost). The DB connection URL looks like:
     postgresql://postgres.ciglkovgphuywwtdlwmy:[YOUR-PASSWORD]@aws-1-eu-west-1.pooler.supabase.com:6543/postgres
  5. Replace [YOUR-PASSWORD] with the database password you set when creating the project.

Local Installation

Follow these steps to get Site-Snap running on your local machine.

• 1. Extract the project
  Unzip the downloaded archive (All files). There are two folders: documentation and the site-snap project.
• 2. Setup Git and GitHub
  While Git and GitHub are optional, they are highly recommended for seamless deployment to platforms like Vercel. Using Git also allows you to track custom modifications and manage updates effortlessly. If you're already set up, feel free to skip this step.
  If you're new to version control, check out this great primer: Git & GitHub Setup for Beginners
• 3. Install dependencies
  Open a terminal in the project root and run:
  npm install

  Note! - it might take a while, playwright package is about 100MB+
• 4. Configure environment variables
  1. Copy .env.example to .env.local:
  cp .env.example .env.local
  2. Open .env.local and configure the following variables:
  GOOGLE_CLIENT_ID — Google sign-in client

  GOOGLE_CLIENT_SECRET — Google sign-in secret

  DATABASE_URL — Your Supabase connection string (from the previous section)

  AUTH_SECRET — Generate with: openssl rand -base64 32 (any secret, a sample secret: k1+40yRyv/5kF0Dc6*@nafSS02Px2WCLfE667Jcfg0=)

  AUTH_URL — http://localhost:3000

  NEXT_PUBLIC_BASE_URL — http://localhost:3000

  SITE_NAME — SiteSnap (or your custom brand name)

  BROWSER_PROVIDER — playwright for local development, sparticuz for Vercel

  PDF_LOAD_IMAGES_STRATEGY — full (loads all images including lazy-loaded) or default

  NEXT_PUBLIC_PDF_DOWNLOAD_FILENAME — Default downloaded PDF filename (e.g. sitesnap-edited.pdf)

  NEXT_PUBLIC_THEME_STORAGE_KEY — LocalStorage key for theme preference (e.g. sitesnap-theme)

  NEXT_PUBLIC_CONSENT_COOKIE_KEY — Cookie name for consent banner (e.g. sitesnap-consent)
• 5. Generate the Prisma client
  npx prisma generate
  This generates the Prisma client based on your database schema.
  
• 5. Run database migrations
  npx prisma migrate dev --name init
  This creates all required tables in your Supabase database.
  
• 6. Verify migration
  Visit supabase.com, sign in and check the newly generated tables.
  
• 7. Prisma studio (optional)
  npx prisma studio
  Prisma Studio is a visual editor for your database. It opens a local web interface that allows you to view, explore, and manipulate your data without writing SQL or using a separate database GUI (like pgAdmin or TablePlus).
• 8. Seed the database
  npm run seed:plans
  This seeds the default plans (Free + Pro). Each new user will be automatically assigned to the free plan. Plans can be edited from the admin dashboard as well.
  npm run seed:admin
  Creates an admin user:
  Email: admin@sitesnap.dev

  Password: admin123
  Important!!!: After logging in as admin for the first time, go to Dashboard > My Account and change the default password immediately.
  Optionally, seed a test customer account:
  Note! - A customer account is needed to test Paddle integration. For admin roles, the subscription tab is not shown within the admin dashboard.
  npm run seed:customer
  Email: customer@sitesnap.dev

  Password: customer123
• 7. Start the development server
  npm run dev
  The app will be available at http://localhost:3000.

Database Migrations & Prisma

Site-Snap uses Prisma as its ORM. The database schema is defined in prisma/schema.prisma.

Prisma Workflow

The typical workflow when working with Prisma is: Edit schema → Generate client → Run migration.

Common Commands

Seed Scripts

The project includes several seed scripts to populate the database with initial data:

Admin Settings (App Settings)

Once logged in as an admin, go to Dashboard > App Settings. Most third-party integrations are configured from this page rather than environment variables. This makes it easy to update settings without redeploying.

Configurable Settings

The App Settings page contains the following configuration sections:

Google Sign-In Setup

To enable Google Sign-In, you need to create OAuth 2.0 credentials in the Google Cloud Console and enter them in the Admin App Settings.

• 1. Go to Google Cloud Console
  Visit: https://console.cloud.google.com/
• 2. Create or select a project
  1. At the top-left, click the project dropdown.
  2. Choose an existing project or click New Project to create one.
  3. Give it a name (for example Site-Snap Auth) and click Create.
• 3. Enable the OAuth API
  1. In the sidebar go to APIs & Services → Library.
  2. Search for Google Identity Services.
  3. Click the API entry, then click Enable.
• 4. Configure the OAuth consent screen
  1. Go to APIs & Services → OAuth consent screen.
  2. Choose External (for users outside your organization) or Internal (G Suite orgs only).
  3. Fill in the required fields:
     App name: your application's display name

     User support email: contact/support email

     Developer contact email: email for Google to reach you
  4. Add the scopes: profile and email.
  5. Click Save and continue.
• 5. Create OAuth 2.0 credentials
  1. Go to APIs & Services → Credentials.
  2. Click + Create Credentials → OAuth client ID.
  3. Choose:
     Application type: Web application

     Name: e.g., Site-Snap Web Client
  4. Under Authorized JavaScript origins, add:
     • http://localhost:3000 (for local development)
     • https://your-domain.com (for production)
  5. Under Authorized redirect URIs, add:
     • http://localhost:3000/api/auth/callback/google (for local development)
     • https://your-domain.com/api/auth/callback/google (for production)
• 6. Copy your credentials into App Settings
  1. When the OAuth client is created you'll see:
  Client ID — Copy this into .env GOOGLE_CLIENT_ID
  Client Secret — Copy this into .env GOOGLE_CLIENT_SECRET

Cloudflare Turnstile Setup

Site-Snap uses Cloudflare Turnstile for bot protection on sign-in, sign-up, and PDF generation forms.

• 1. Create a Cloudflare account
  Visit dash.cloudflare.com and sign up or log in.
• 2. Navigate to Turnstile
  In the Cloudflare dashboard, go to Application Security > Turnstile.
• 3. Add a site
  1. Click Add site.
  2. Enter your site name and domain (e.g. localhost for development, your-domain.com for production).
  3. Choose a widget type (Managed is recommended).
  4. Click Create.
• 4. Copy the keys
  After creating the site, you'll receive:
  Site Key — The public key used in the frontend widget

  Secret Key — The private key used for server-side verification
• 5. Enter the keys in App Settings
  1. Go to Admin > App Settings > Cloudflare Turnstile.
  2. Enter the Site Key and Secret Key.
  3. Optionally, you can disable Turnstile verification for PDF generation if desired.
  4. Save the settings.

Resend (Email) Setup

Site-Snap uses Resend for transactional emails, including email verification and password reset.

• 1. Create a Resend account
  Visit resend.com and sign up for a free account.
• 2. Get your API key
  1. In the Resend dashboard, go to API Keys.
  2. Click Create API Key.
  3. Give it a name and select the appropriate permissions.
  4. Copy the generated API key.
• 3. Verify your domain (recommended)
  1. Go to Domains in the Resend dashboard.
  2. Add your domain and follow the DNS verification steps.
  3. This allows you to send from a custom "From" address (e.g. noreply@yourdomain.com).
• 4. Configure in App Settings
  1. Go to Admin > App Settings > Resend (Email).
  2. Enter your API Key.
  3. Enter the From Email address (e.g. noreply@yourdomain.com).
  4. Save the settings.

Emails sent by Site-Snap

Emails templates

Paddle (Payments) Setup

Site-Snap integrates with Paddle to handle subscription payments. Paddle acts as a Merchant of Record, handling VAT/sales tax, invoicing, and global payments on your behalf.

Paddle supports sellers in over 200 countries and territories, allowing you to sell globally with no additional country-specific setup. Supported countries

Note! When testing with the sandbox, use the test card numbers listed in the "Testing with Sandbox" section below.

Important Notice: Paddle API Key Expiration!!! --- Please be advised that API keys issued by Paddle are valid for a period of 90 days from the date of creation. To ensure uninterrupted service and avoid any potential disruptions to your integrations, we strongly recommend monitoring your API key expiration dates and generating new keys before they expire.

Prerequisites

• Create a Paddle account at paddle.com. For testing, create an account with their sandbox environment at sandbox-vendors.paddle.com.
• Complete your Paddle seller setup and verification.

Configuration Steps

• 1. Create a Product and Price in Paddle
  1. In the Paddle dashboard, go to Catalog > Products.
  2. Click + New Product and fill in the product details (e.g. "Site-Snap Pro").
  3. Under the product, create a Price (e.g. $19/month recurring).
  4. Copy the Price ID (starts with pri_) — you'll need this later.
• 2. Get API Credentials
  1. Go to Developer Tools > Authentication in the Paddle dashboard.
  2. Copy your API Key.
  3. Go to Developer Tools > Client-side tokens and copy your Client Token.
• 3. Set up the Webhook
  1. Go to Developer Tools > Notifications in the Paddle dashboard.
  2. Click + New Destination.
  3. Set the webhook URL to: {YOUR_DOMAIN}/api/paddle/webhook
     • For local testing: http://localhost:3000/api/paddle/webhook (use a tunnel like ngrok)
     • For production: https://your-domain.com/api/paddle/webhook
  4. Select the following events:
     • subscription.created
     • subscription.updated
     • subscription.canceled
     • transaction.completed
  5. Copy the generated Webhook Secret Key.
• 4. Enter credentials in App Settings
  1. Go to Admin > App Settings > Paddle (Payments).
  2. Enter your API Key, Client Token, and Webhook Secret.
  3. Set the Environment to sandbox for testing or production for live payments.
  4. Save the settings.
• 5. Link the Price ID to your plan
  1. Go to Admin > Plans.
  2. Edit the Pro plan (or any paid plan).
  3. Paste the Paddle Price ID into the Paddle Price ID field.
  4. Save the plan.

Webhook Events

Site-Snap automatically handles these Paddle webhook events:

Testing with Sandbox

You can test payments using your Paddle sandbox account. Open a checkout, then use these card details to test payment by card:

Use any expiration date in the future.

AWS S3 Storage Setup

https://aws.amazon.com/console/

Mention - that on serverless local storage does not work

Site-Snap can store generated PDFs and project thumbnails on AWS S3. By default, local files are stored locally in the public/uploads/ directory. For production, S3 is recommended.

• 1. Create an AWS account
  Visit aws.amazon.com and sign up if you don't have an account.
• 2. Create an S3 bucket
  1. Go to the S3 service in the AWS console.
  2. Click Create bucket.
  3. Enter a unique bucket name (e.g. sitesnap-files).
  4. Choose a region close to your users.
  5. Under Block Public Access, uncheck "Block all public access" if you want PDFs to be directly accessible via URL. Acknowledge the warning.
  6. Click Create bucket.
• 3. Create an IAM user with S3 permissions
  1. Go to the IAM service in the AWS console.
  2. Click Users > Create user.
  3. Enter a username (e.g. sitesnap-s3).
  4. Attach the AmazonS3FullAccess policy (or create a custom policy scoped to your bucket).
  5. Create the user and go to Security credentials > Create access key.
  6. Copy the Access Key ID and Secret Access Key.
• 4. Configure in App Settings
  1. Go to Admin > App Settings > AWS S3 Storage.
  2. Enter your Bucket Name, Region, Access Key ID, and Secret Access Key.
  3. Switch the Storage Mode from local to s3.
  4. Save the settings.

S3 is used for storing generated PDFs and project thumbnails. Files are stored with the key pattern: pdfs/{projectId}.pdf and thumbnails/{projectId}.jpg.

AWS S3 Storage Setup

https://aws.amazon.com/console/

Note! Serverless local storage does not persist files reliably. Use S3 for production.

Site-Snap can store generated PDFs and project thumbnails on AWS S3. By default, local files are stored in public/uploads/. For production, S3 is recommended.

• 1. Create an AWS account
  Visit aws.amazon.com and sign up if you don't have an account.
• 2. Create an S3 bucket
  1. Go to the S3 service in the AWS console.
  2. Click Create bucket.
  3. Enter a unique bucket name (e.g., sitesnap-files).
  4. Choose a region close to your users.
  5. Under Object Ownership, select ACLs disabled (Bucket owner enforced).
  6. Under Block Public Access, uncheck "Block public access to buckets and objects granted through any bucket policy" to allow public reads via a bucket policy.
  7. Click Create bucket.
• 3. Configure CORS for browser access
  1. Open your bucket → Permissions → CORS configuration.
  2. Paste the following JSON to allow your frontend to fetch files:
  3. Replace "https://site-snap-gilt.vercel.app" with your domain:
  [ { "AllowedHeaders": ["*"], "AllowedMethods": ["GET", "HEAD"], "AllowedOrigins": ["https://site-snap-gilt.vercel.app"], "ExposeHeaders": [] } ]

  Alternatively, you can allow access from all domains.

  [ { "AllowedHeaders": ["*"], "AllowedMethods": ["GET", "HEAD"], "AllowedOrigins": ["*"], "ExposeHeaders": [] } ]
  3. Save the CORS configuration.
• 4. Add a bucket policy for public read access
  1. Open Permissions → Bucket policy.
  2. Paste the following JSON to allow public access to objects:
  { "Version": "2012-10-17", "Statement": [ { "Sid": "PublicReadGetObject", "Effect": "Allow", "Principal": "*", "Action": "s3:GetObject", "Resource": "arn:aws:s3:::sitesnap-files/*" } ] }
  3. Save the bucket policy.
• 5. Create an IAM user with S3 upload permissions
  1. Go to the IAM service in the AWS console.
  2. Click Users > Create user.
  3. Enter a username (e.g., sitesnap-s3).
  4. Click "Users" > sitesnap-s3.
  5. Click - Permissions policies tab.
  6. Click - Add Permission.
  7. Click - Attach policies directly.
  8. Search "AmazonS3FullAccess".
  9. Check "AmazonS3FullAccess" and click save.
  10. Create the user.
  11. Go to Security credentials > Create access key.
  12. Copy the Access Key ID and Secret Access Key to configure your app.
• 6. Configure in App Settings
  1. Go to Admin > App Settings > AWS S3 Storage.
  2. Enter your Bucket Name, Region, Access Key ID, and Secret Access Key.
  3. Switch the Storage Mode from local to s3.
  4. Save the settings.

Files are stored in S3 with the key patterns:

• pdfs/{projectId}.pdf
• thumbnails/{projectId}.jpg

Deploy to Vercel

Site-Snap is optimized for deployment on Vercel. Follow these steps to deploy your instance.

Prerequisites

• A Vercel account
• A GitHub repository with the Site-Snap project
• Your Supabase database already set up (same DB for local and production)

• 1. Push your code to GitHub
  Create a private GitHub repository and push the Site-Snap project code to it.
• 2. Import the project in Vercel
  1. Log in to vercel.com.
  2. Click Add New > Project.
  3. Import your GitHub repository.
  4. Select the Next.js framework preset (should be auto-detected).
• 3. Set environment variables
  In the Vercel project settings, add the following environment variables with production values:
  Note!!! You might only get the https://your-domain.vercel.app/ after your first deploy, you will have to re-edit: AUTH_URL and NEXT_PUBLIC_BASE_URL.
  GOOGLE_CLIENT_ID — Google sign-in client

  GOOGLE_CLIENT_SECRET — Google sign-in secret

  DATABASE_URL — Same Supabase connection string (shared database between local and production)

  AUTH_SECRET — Generate a new production secret: openssl rand -base64 32

  AUTH_URL — https://your-domain.vercel.app

  NEXT_PUBLIC_BASE_URL — https://your-domain.vercel.app

  SITE_NAME — Your app name (e.g. SiteSnap)

  BROWSER_PROVIDER — sparticuz (required for Vercel serverless environment)

  PDF_LOAD_IMAGES_STRATEGY — full or default

  NEXT_PUBLIC_PDF_DOWNLOAD_FILENAME — e.g. sitesnap-edited.pdf

  NEXT_PUBLIC_THEME_STORAGE_KEY — e.g. sitesnap-theme

  NEXT_PUBLIC_CONSENT_COOKIE_KEY — e.g. sitesnap-consent
• 4. Deploy
  Click Deploy. Vercel will build and deploy the application. The build command automatically runs prisma generate && next build.
• 5. Run database seeds (if needed)
  Since the database is shared between local and production, you can run seed scripts from your local terminal if you haven't already:
  npm run seed:admin
  Alternatively, you can use the Vercel CLI (vercel env pull + run locally).
• 6. Update third-party configurations for production
  After deploying, update the following to use your production domain:
  Paddle webhook URL — Update to https://your-domain.vercel.app/api/paddle/webhook

  Google OAuth redirect URIs — Add https://your-domain.vercel.app/api/auth/callback/google

  Cloudflare Turnstile — Add your production domain to the allowed domains list
• 7. Configure a specific production branch in Vercel (optional)
  You can configure Vercel to deploy only a specific branch to production. This is the most common setup when you want full control over what goes live.
  Open your project — Go to your project in the Vercel Dashboard

  Navigate to project settings — Click Settings → Deployments

  Set Production Branch — Under Production Branch, select your desired branch (e.g. main, release, prod)

  Save changes — Click Save
  Now:
  Selected branch — Deploys to Production

  All other branches — Create Preview Deployments only

  Swith environment to Preview — Branch Tracking > Disable

Deploy to VPS

Deploying Site-Snap to your own VPS (for example a DigitalOcean Droplet) is absolutely possible, but it can be more challenging than deploying to Vercel.

A traditional VPS setup usually requires installing and configuring tools such as:

• Node.js
• Process manager (PM2 or similar)
• Nginx (reverse proxy)
• SSL certificates (Let's Encrypt)
• Firewall and server security

If you prefer a much simpler experience, we highly recommend using Dokploy. It is open-source and provides a deployment experience similar to Vercel, but on your own VPS.

Dokploy handles:

• Automatic deployments from your Git repository
• SSL certificate management
• Reverse proxy configuration
• Application process management

👉 To get started with Dokploy, watch this step-by-step tutorial:
Dokploy Deployment Guide (YouTube)

Prerequisites

• A VPS (e.g. DigitalOcean, Hetzner, AWS, etc.)
• Your GitHub repository with the Site-Snap project
• Your Supabase database already set up (same DB for local and production)

Managing Plans (Admin)

Go to Admin > Plans to manage subscription plans. Site-Snap ships with two default plans: Free and Pro.

Plan Configuration

Each plan has the following settings:

To create additional paid plans, create a new price in your Paddle dashboard first, then create the plan in Site-Snap and link the Paddle Price ID.

Managing Users (Admin)

Go to Admin > Users to manage all registered users.

Features

• View all users — See a list of all registered users with their name, email, role, plan, and registration date.
• Search and filter — Search users by name, email, or filter by plan.
• Create users manually — Create new user accounts with a specific role and plan assignment.
• Assign plans — Change a user's subscription plan.
• Override limits — Set custom project and storage limits for individual users, overriding their plan defaults.
• Delete users — Remove a user account. This cascades to delete all their projects, files, and subscription data.

Using the App (End User Perspective)

This section describes the app from a customer's point of view.

Homepage — Capture a PDF

On the homepage, users enter a website URL and click the capture button. Site-Snap generates a high-quality PDF of the page. No account is required for basic captures, though Turnstile verification is used.

Sign Up / Sign In

Users can create an account with email and password, or sign in with Google (if configured). After signing up, users receive a verification email and must verify their address before they can log in.

Dashboard — My Projects

The dashboard shows all saved projects in a grid view with thumbnails. Users can view, edit, or delete their projects from here.

PDF Editor

The editor lets users annotate PDFs using drawing tools powered by Konva.js canvas. Users can add shapes, text, and freehand drawings on top of the PDF, then save or download the annotated version.

Subscription — Upgrade / Downgrade

Users can view their current plan and upgrade to a paid plan via the Paddle checkout overlay. Downgrading reverts the user to the free plan at the end of the current billing period.

Account Settings

Users can update their profile name, change their password, and delete their account. Deleting an account cancels any active subscription and removes all projects and files.

Internationalization

Site-Snap supports multiple languages out of the box using next-intl.

Supported Languages

Translation Files

Language files are located in the /messages/ directory at the project root. Each language has its own JSON file:

Adding a New Language

1. Create a new JSON file in the /messages/ directory (e.g. messages/de.json for German).
2. Copy the structure from messages/en.json and translate all values.
3. Add the new language metadata (locale code, label, direction) to @/messages/languages-meta.
4. RTL languages are supported.

Editing Translations

Open the corresponding JSON file in /messages/ and edit the translation values. The app will use the updated translations after a rebuild or in development mode immediately.

Environment Variables Reference

Below is a full reference of all environment variables used by Site-Snap.

Required Variables

Browser & PDF Settings

Branding Keys

Admin UI Settings (Not env vars)

The following settings are managed via the Admin UI at Dashboard > App Settings, not through environment variables:

Changelog

Version 1.0.0

• Website-to-PDF capture from any URL
• PDF annotation editor with drawing tools (Konva.js canvas)
• Project management (create, view, edit, delete)
• User authentication (email/password + Google OAuth)
• Email verification and password reset (via Resend)
• Subscription billing with Paddle integration
• Free and Pro tier system with configurable limits
• Admin dashboard: manage users, plans, and app settings
• User limit overrides per account
• AWS S3 or local file storage
• Cloudflare Turnstile bot protection
• Multi-language support
• Dark mode support
• Responsive design
• SSRF protection for PDF generation
• Webhook handling for payment events
• Account deletion with cascade cleanup