> ## Documentation Index
> Fetch the complete documentation index at: https://docs.screenshothis.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Self-host Screenshothis

> Run Screenshothis on your own infrastructure with complete control and customization.

# Self-host Screenshothis

Take complete control of your screenshot infrastructure by running Screenshothis on your own servers. This guide walks you through everything from local development setup to production deployment.

<Warning>
  **Important**: Always refer to the official [Screenshothis repository](https://github.com/screenshothis/screenshothis) for the most up-to-date setup instructions, environment variables, and configuration requirements. The repository README and `.env.example` files contain the definitive setup information.
</Warning>

<Note>
  **Why self-host?** While our hosted service provides simplicity and reliability, self-hosting gives you complete data control, unlimited customization options, and eliminates external dependencies.
</Note>

## Project architecture

Screenshothis uses a modern **monorepo** architecture built with TypeScript:

<CardGroup cols={2}>
  <Card title="Backend API" icon="server">
    **Location**: `apps/server`

    Hono + tRPC API with TypeScript for fast, type-safe screenshot generation
  </Card>

  <Card title="Frontend Web App" icon="globe">
    **Location**: `apps/web`

    React with TanStack Start and TailwindCSS for the dashboard and playground
  </Card>

  <Card title="Shared Packages" icon="package">
    **Location**: `packages/*`

    Common schemas, utilities, and types shared across applications
  </Card>

  <Card title="Infrastructure" icon="database">
    **Dependencies**

    PostgreSQL, Redis, and S3-compatible storage for complete functionality
  </Card>
</CardGroup>

## Technology stack

| Component              | Technology               | Purpose                             |
| ---------------------- | ------------------------ | ----------------------------------- |
| **Runtime**            | Node.js + TypeScript     | Fast, type-safe execution           |
| **API Framework**      | Hono + tRPC              | Lightweight, type-safe API          |
| **Frontend**           | React + TanStack Start   | Modern, fast web interface          |
| **Database**           | PostgreSQL + Drizzle ORM | Reliable data persistence           |
| **File Storage**       | S3-compatible storage    | Screenshot and asset storage        |
| **Cache/Sessions**     | Redis                    | Fast caching and session management |
| **Styling**            | TailwindCSS              | Utility-first CSS framework         |
| **Linting/Formatting** | Biome                    | Fast, consistent code formatting    |
| **Package Manager**    | pnpm                     | Efficient dependency management     |
| **Monorepo**           | Turborepo                | Fast, scalable build system         |
| **Containerization**   | Docker + Docker Compose  | Easy deployment and scaling         |

## Prerequisites

Before you begin, ensure you have these tools installed:

<Steps>
  <Step title="Install Node.js">
    Download and install **Node.js v18 or later** from [nodejs.org](https://nodejs.org)

    <Check>
      Verify your installation: `node --version` should show v18.0.0 or higher
    </Check>
  </Step>

  <Step title="Install pnpm">
    Install the pnpm package manager:

    ```bash theme={null}
    npm install -g pnpm
    ```

    <Check>
      Verify: `pnpm --version` should show the installed version
    </Check>
  </Step>

  <Step title="Install Docker">
    Download and install [Docker Desktop](https://docs.docker.com/get-docker/) for your operating system

    <Check>
      Verify: `docker --version` and `docker-compose --version` should both work
    </Check>
  </Step>

  <Step title="Install Git">
    Ensure Git is installed for cloning the repository

    <Check>
      Verify: `git --version` should show your Git installation
    </Check>
  </Step>
</Steps>

## Quick setup

Get Screenshothis running locally in under 10 minutes:

<Steps>
  <Step title="Clone the repository">
    ```bash theme={null}
    git clone https://github.com/screenshothis/screenshothis.git
    cd screenshothis
    ```

    <Check>
      You should now be in the screenshothis directory with all source code
    </Check>
  </Step>

  <Step title="Install dependencies">
    ```bash theme={null}
    pnpm install
    ```

    This installs all dependencies for the entire monorepo using pnpm workspaces.

    <Check>
      You should see "Dependencies installed" and no error messages
    </Check>
  </Step>

  <Step title="Start supporting services">
    Launch PostgreSQL, Redis, and MinIO (for local storage):

    ```bash theme={null}
    docker-compose up -d
    ```

    This starts:

    * **PostgreSQL** on `localhost:5432`
    * **Redis** on `localhost:6379`
    * **MinIO** (S3-compatible) on `localhost:9000` (API) and `localhost:9001` (Console)

    <Check>
      Verify services: `docker-compose ps` should show all services as "Up"
    </Check>
  </Step>

  <Step title="Configure environment variables">
    Copy and customize the environment files:

    ```bash theme={null}
    # Server environment
    cp apps/server/.env.example apps/server/.env

    # Web environment (optional)
    cp apps/web/.env.example apps/web/.env
    ```

    The default values work for local development with Docker Compose.

    <Tip>
      You can customize settings later. The defaults are configured to work with the Docker services.
    </Tip>
  </Step>

  <Step title="Set up the database">
    Apply the database schema:

    ```bash theme={null}
    pnpm run db:push
    ```

    This creates all necessary tables in your PostgreSQL database.

    <Check>
      You should see "Schema applied successfully" or similar confirmation
    </Check>
  </Step>

  <Step title="Configure local storage">
    Set up MinIO for local screenshot storage:

    1. **Open MinIO console** at [http://localhost:9001](http://localhost:9001)
    2. **Login with credentials**:
       * **Username**: `screenshothis-access-key`
       * **Password**: `screenshothis-secret-key`
    3. **Create a bucket** named `screenshothis-bucket`
    4. **Verify access** - you should see the empty bucket

    <Info>
      MinIO provides S3-compatible storage for local development. For production, use AWS S3, DigitalOcean Spaces, or another S3-compatible service.
    </Info>
  </Step>

  <Step title="Start the applications">
    Launch both the web interface and API server:

    ```bash theme={null}
    pnpm run dev
    ```

    This starts:

    * **Web UI**: [http://localhost:3001](http://localhost:3001)
    * **API Server**: [http://localhost:3000](http://localhost:3000)

    <Check>
      Visit both URLs to verify everything is working. You should see the Screenshothis interface and API health check.
    </Check>
  </Step>
</Steps>

## Environment configuration

### Server environment (`apps/server/.env`)

Configure the server with these essential variables:

```bash theme={null}
# Database Configuration
DATABASE_URL=postgresql://screenshothis:password@localhost:5432/screenshothis
DATABASE_HOST=localhost
DATABASE_PORT=5432
DATABASE_NAME=screenshothis
DATABASE_USER=screenshothis
DATABASE_PASSWORD=password

# Redis Configuration
REDIS_URL=redis://localhost:6379

# S3-Compatible Storage Configuration
# For local development (MinIO):
AWS_ACCESS_KEY_ID=screenshothis-access-key
AWS_SECRET_ACCESS_KEY=screenshothis-secret-key
AWS_REGION=us-east-1
AWS_BUCKET=screenshothis-bucket
AWS_URL=http://localhost:9000
AWS_ENDPOINT=http://localhost:9000
AWS_USE_PATH_STYLE_ENDPOINT=true

# For production, replace with your S3-compatible service:
# AWS_ACCESS_KEY_ID=your-actual-access-key
# AWS_SECRET_ACCESS_KEY=your-actual-secret-key
# AWS_REGION=us-east-1
# AWS_BUCKET=your-production-bucket
# AWS_URL=https://your-s3-endpoint.com
# AWS_ENDPOINT=https://your-s3-endpoint.com
# AWS_USE_PATH_STYLE_ENDPOINT=false

# API Configuration
PORT=3000
NODE_ENV=development

# Authentication & Security
BETTER_AUTH_SECRET=your-super-secure-auth-secret-key-here
DEFAULT_API_KEY_PREFIX=ss

# Rate Limiting & Security
RATE_LIMIT_WINDOW_MS=60000
RATE_LIMIT_MAX_REQUESTS=100

# Screenshot Configuration
SCREENSHOT_TIMEOUT=30000
MAX_SCREENSHOT_WIDTH=3840
MAX_SCREENSHOT_HEIGHT=2160

# Request Limits (Security)
MAX_HEADER_SIZE=8192  # 8KB header limit
MAX_COOKIE_SIZE=4096  # 4KB cookie limit

# CSP Bypass Auditing
AUDIT_CSP_BYPASS=true  # Log when bypass_csp=true is used
```

### Web environment (`apps/web/.env`)

Configure the web interface:

```bash theme={null}
# API Configuration
VITE_API_URL=http://localhost:3000

# Environment
NODE_ENV=development
```

<Warning>
  **Production security**: Always use strong, unique passwords and secrets for production deployments. Never use the default development values.
</Warning>

## Available scripts

Run these commands from the **root directory**:

### Development scripts

| Command               | Description                                   |
| --------------------- | --------------------------------------------- |
| `pnpm install`        | Install all dependencies for the monorepo     |
| `pnpm run dev`        | Start both web and server in development mode |
| `pnpm run dev:web`    | Start only the web (frontend) application     |
| `pnpm run dev:server` | Start only the server (backend) application   |

### Build and production scripts

| Command          | Description                              |
| ---------------- | ---------------------------------------- |
| `pnpm run build` | Build all applications for production    |
| `pnpm run start` | Start production builds (after building) |

### Database management scripts

| Command                | Description                                         |
| ---------------------- | --------------------------------------------------- |
| `pnpm run db:push`     | Apply Drizzle schema changes to the database        |
| `pnpm run db:studio`   | Open Drizzle Studio to view and manage the database |
| `pnpm run db:generate` | Generate migration files for schema changes         |
| `pnpm run db:migrate`  | Apply migrations to the database                    |

### Code quality scripts

| Command                | Description                                      |
| ---------------------- | ------------------------------------------------ |
| `pnpm run check-types` | Run TypeScript type checking across all packages |
| `pnpm run check`       | Run Biome linting and formatting checks          |
| `pnpm run format`      | Apply Biome formatting to the codebase           |
| `pnpm run lint`        | Run Biome linting checks                         |
| `pnpm run lint:fix`    | Run Biome linting and fix issues automatically   |

## Production deployment

### Docker production setup

Build and deploy production-ready Docker images:

<Steps>
  <Step title="Build production images">
    ```bash theme={null}
    # Build server image
    docker build -f apps/server/Dockerfile -t screenshothis-server .

    # Build web interface image
    docker build -f apps/web/Dockerfile -t screenshothis-web .
    ```
  </Step>

  <Step title="Set up external services">
    Configure production-grade external services:

    * **PostgreSQL**: Use managed PostgreSQL (AWS RDS, DigitalOcean Managed Databases, etc.)
    * **Redis**: Use managed Redis (AWS ElastiCache, DigitalOcean Managed Redis, etc.)
    * **S3 Storage**: Use AWS S3, DigitalOcean Spaces, Cloudflare R2, or Backblaze B2
  </Step>

  <Step title="Configure production environment">
    Create production environment files with:

    * Strong, unique passwords and secrets
    * Production database connections
    * Production S3-compatible storage credentials
    * Appropriate rate limits and timeouts
  </Step>

  <Step title="Set up infrastructure">
    Configure your production infrastructure:

    * **Reverse proxy**: nginx, Traefik, or cloud load balancer
    * **SSL certificates**: Let's Encrypt, cloud provider, or custom certificates
    * **Container orchestration**: Docker Compose, Kubernetes, or cloud container services
  </Step>
</Steps>

### Environment variables for production

Ensure these are properly configured for production:

<ParamField path="BETTER_AUTH_SECRET" type="string" required>
  Strong, unique secret for authentication. Generate with `openssl rand -base64 32`
</ParamField>

<ParamField path="DATABASE_URL" type="string" required>
  Connection string for your production PostgreSQL database
</ParamField>

<ParamField path="REDIS_URL" type="string" required>
  Connection string for your production Redis instance
</ParamField>

<ParamField path="AWS_ACCESS_KEY_ID" type="string" required>
  Access key for your S3-compatible storage service
</ParamField>

<ParamField path="AWS_SECRET_ACCESS_KEY" type="string" required>
  Secret key for your S3-compatible storage service
</ParamField>

<ParamField path="AWS_BUCKET" type="string" required>
  Name of your production storage bucket
</ParamField>

## Security considerations

<Warning>
  When self-hosting, you're responsible for security, updates, backups, and monitoring. Ensure you have proper security measures in place.
</Warning>

### Built-in security features

Screenshothis includes several security measures:

<AccordionGroup>
  <Accordion title="Request size limits" icon="shield">
    * **Header size limit**: 8 KB (8192 characters) per request
    * **Cookie size limit**: 4 KB (4096 characters) per request
    * **URL length limit**: Standard browser limits (2048 characters)
    * **Request timeout**: 30 seconds maximum

    These limits prevent abuse and ensure consistent performance.
  </Accordion>

  <Accordion title="Rate limiting" icon="clock">
    * Screenshot generation is limited per user
    * Configurable rate limits via environment variables
    * Built-in protection against abuse

    Monitor rate limit usage and adjust as needed for your use case.
  </Accordion>

  <Accordion title="CSP bypass auditing" icon="eye">
    * Every use of `bypass_csp=true` is audit-logged server-side
    * Helps identify potential security issues
    * Enables security review and compliance

    Review audit logs regularly for security monitoring.
  </Accordion>

  <Accordion title="Input validation" icon="check-circle">
    * All API inputs are validated using Zod schemas
    * URL validation prevents malicious requests
    * Parameter validation ensures data integrity

    Input validation helps prevent injection attacks and data corruption.
  </Accordion>
</AccordionGroup>

### Additional security recommendations

<Steps>
  <Step title="Keep dependencies updated">
    Regularly update Node.js, dependencies, and base Docker images to get security patches.
  </Step>

  <Step title="Secure your database">
    * Use strong passwords
    * Enable SSL/TLS connections
    * Restrict network access
    * Regular backups
  </Step>

  <Step title="Configure HTTPS">
    * Use SSL/TLS certificates for all connections
    * Configure secure headers
    * Enable HSTS (HTTP Strict Transport Security)
  </Step>

  <Step title="Monitor and log">
    * Set up application logging
    * Monitor resource usage
    * Track API usage patterns
    * Set up alerts for unusual activity
  </Step>
</Steps>

## Database management

### View and manage data

Use Drizzle Studio for a visual database interface:

```bash theme={null}
pnpm run db:studio
```

This opens a web interface at `http://localhost:4983` where you can:

* View all tables and data
* Edit records
* Run queries
* Manage relationships

### Handle schema changes

For development, use the simple approach:

```bash theme={null}
# Apply schema changes directly (development only)
pnpm run db:push
```

For production, use migrations:

```bash theme={null}
# Generate migration files when schema changes
pnpm run db:generate

# Apply migrations to database
pnpm run db:migrate
```

<Note>
  **Development vs Production**: Use `db:push` for rapid development iteration, but use migrations (`db:generate` and `db:migrate`) for production deployments where you need versioned, reversible database changes.
</Note>

## Troubleshooting

### Common issues and solutions

<AccordionGroup>
  <Accordion title="Port conflicts" icon="network-wired">
    **Problem**: Services fail to start due to port conflicts

    **Solutions**:

    * Change ports in `docker-compose.yml`
    * Update environment variables to match new ports
    * Stop conflicting services: `sudo lsof -i :5432` to find what's using PostgreSQL port
  </Accordion>

  <Accordion title="Database connection errors" icon="database">
    **Problem**: Cannot connect to PostgreSQL

    **Solutions**:

    * Verify PostgreSQL container is running: `docker-compose ps`
    * Check database credentials in environment variables
    * Ensure database exists: `docker-compose exec postgres psql -U screenshothis -d screenshothis`
    * Reset database: `docker-compose down && docker-compose up -d`
  </Accordion>

  <Accordion title="S3 storage connection errors" icon="cloud">
    **Problem**: Screenshot storage not working

    **Solutions**:

    * **For local development**: Verify MinIO container is running and accessible at `http://localhost:9001`
    * Check AWS environment variables match your storage configuration
    * Ensure the bucket exists and has proper permissions
    * **For production**: Verify your S3-compatible service credentials and bucket permissions
    * Test connection: `curl http://localhost:9000/minio/health/live`
  </Accordion>

  <Accordion title="Build and dependency errors" icon="package">
    **Problem**: Installation or build failures

    **Solutions**:

    * Clear node\_modules and reinstall: `rm -rf node_modules && pnpm install`
    * Clear Turborepo cache: `rm -rf .turbo`
    * Check TypeScript types: `pnpm run check-types`
    * Verify Node.js version: `node --version` (should be v18+)
    * Update pnpm: `npm install -g pnpm@latest`
  </Accordion>
</AccordionGroup>

### Getting help

<CardGroup cols={2}>
  <Card title="GitHub Issues" icon="github" href="https://github.com/screenshothis/screenshothis/issues">
    Search existing issues or create a new one for bugs and feature requests
  </Card>

  <Card title="View Docker Logs" icon="file-text">
    Check service logs: `docker-compose logs` or `docker-compose logs <service-name>`
  </Card>

  <Card title="Community Discussions" icon="message-circle" href="https://github.com/screenshothis/screenshothis/discussions">
    Join discussions for questions, ideas, and community support
  </Card>

  <Card title="Documentation" icon="book" href="https://docs.screenshothis.com">
    Browse complete documentation for configuration and usage guides
  </Card>
</CardGroup>

## Contributing

Screenshothis is an **open source** project (AGPL-3.0) with an active community. Your contributions help make it better for everyone.

### Ways to contribute

<Steps>
  <Step title="Report issues">
    Found a bug or have a feature request? [Create an issue](https://github.com/screenshothis/screenshothis/issues) with detailed information.
  </Step>

  <Step title="Improve documentation">
    Help others by improving documentation, adding examples, or fixing typos.
  </Step>

  <Step title="Submit code changes">
    Follow our development guidelines:

    * Run `pnpm run check` before committing
    * Ensure TypeScript types are correct: `pnpm run check-types`
    * Test your changes locally with `pnpm run dev`
    * Follow existing code style (Biome handles formatting)
  </Step>

  <Step title="Join discussions">
    Participate in [GitHub Discussions](https://github.com/screenshothis/screenshothis/discussions) to share ideas and help other users.
  </Step>
</Steps>

### Development workflow

<Tabs>
  <Tab title="Quick Fix">
    1. Fork the repository
    2. Create a feature branch: `git checkout -b fix-something`
    3. Make your changes
    4. Test locally: `pnpm run dev`
    5. Submit a pull request
  </Tab>

  <Tab title="Feature Development">
    1. Open an issue to discuss the feature
    2. Fork and create a feature branch
    3. Implement the feature with tests
    4. Update documentation
    5. Submit a pull request with detailed description
  </Tab>

  <Tab title="Documentation">
    1. Find documentation that needs improvement
    2. Make changes in the relevant `.mdx` files
    3. Test locally if possible
    4. Submit a pull request
  </Tab>
</Tabs>

## Next steps

<CardGroup cols={2}>
  <Card title="Configuration Guide" icon="settings" href="/self-host/configuration">
    Learn about all environment variables and configuration options
  </Card>

  <Card title="Deployment Guide" icon="rocket" href="/self-host/deployment">
    Production deployment strategies for different platforms
  </Card>

  <Card title="Troubleshooting" icon="life-ring" href="/self-host/troubleshooting">
    Detailed troubleshooting guide for common issues
  </Card>

  <Card title="API Reference" icon="code" href="/api-reference/introduction">
    Complete API documentation for your self-hosted instance
  </Card>
</CardGroup>

***

**License**: AGPL-3.0 • **Repository**: [github.com/screenshothis/screenshothis](https://github.com/screenshothis/screenshothis)