Self-hosting

Run ThinkEx on your own infrastructure.

If you just want to use ThinkEx, go to thinkex.app — no setup needed. This guide is for running ThinkEx on your own infrastructure.

Self-hosting gives you full control over your data and deployment. ThinkEx runs as a Next.js app backed by PostgreSQL. Docker is the recommended way to run PostgreSQL locally.

Prerequisites

Before you begin, make sure you have:

• Node.js v20 or later
• pnpm (installed automatically by the setup script if missing)
• Docker (recommended for PostgreSQL) or PostgreSQL v12+ installed locally
• A Google AI API key from Google AI Studio — required for AI features

Setup

Automated

The setup script handles everything interactively: prerequisites, environment configuration, database initialization, and starting the development server.

1. Clone and run the setup script

   git clone https://github.com/ThinkEx-OSS/thinkex.git
   cd thinkex
   ./setup.sh
   

   The script will:

   • Check for Node.js, pnpm, and Docker
   • Create your .env file from the template
   • Generate BETTER_AUTH_SECRET automatically
   • Start PostgreSQL in Docker (or connect to a local PostgreSQL if Docker is unavailable)
   • Install dependencies
   • Initialize the database schema
   • Start the development server
2. Open ThinkEx

   Navigate to http://localhost:3000 in your browser.

Manual

1. Clone the repository

   git clone https://github.com/ThinkEx-OSS/thinkex.git
   cd thinkex
   
2. Start PostgreSQL

   Docker (recommended)

   docker-compose up -d postgres
   

   Local PostgreSQL

   Make sure PostgreSQL is running and you have a database ready. You’ll configure the connection string in the next step.

3. Install dependencies

   pnpm install
   
4. Configure environment variables

   Copy the example environment file and edit it:

   cp .env.example .env
   

   See the environment variables section below for what to set.

5. Initialize the database

   pnpm db:push
   
6. Start the development server

   pnpm dev
   
7. Open ThinkEx

   Navigate to http://localhost:3000 in your browser.

Managing the PostgreSQL Docker container:

docker-compose up -d    # Start PostgreSQL
docker-compose down     # Stop PostgreSQL
docker-compose logs -f postgres  # View logs

Storage options

ThinkEx supports two backends for file uploads. Choose the one that fits your setup:

Local storage

Files are saved to the ./uploads directory on the server. This is the simplest option and requires no external dependencies.

STORAGE_TYPE=local

This is the recommended option for self-hosting. You have full control over your files with no third-party services required.

Supabase storage

Files are stored in a Supabase storage bucket. Use this if you want cloud-based file storage.

STORAGE_TYPE=supabase
NEXT_PUBLIC_SUPABASE_URL=https://your-project.supabase.co
NEXT_PUBLIC_SUPABASE_ANON_KEY=eyJ...
SUPABASE_SERVICE_ROLE_KEY=eyJ...

In your Supabase project, create a storage bucket named file-upload and set it to Public.

Environment variables

Required

These variables must be set for ThinkEx to run:

Variable	Description
DATABASE_URL	PostgreSQL connection string. For Docker: postgresql://thinkex:thinkex_password_change_me@localhost:5432/thinkex. For local PostgreSQL: postgresql://user:password@localhost:5432/thinkex
BETTER_AUTH_SECRET	Secret key for session signing. Generate one with openssl rand -base64 32.
GOOGLE_GENERATIVE_AI_API_KEY	API key from Google AI Studio. Required for all AI features.
STORAGE_TYPE	File storage backend. Set to local or supabase.

Public URL (required for non-localhost deployments)

If you’re deploying to a domain other than localhost, set both of these to your public origin:

Variable	Description
NEXT_PUBLIC_APP_URL	The public URL of your ThinkEx instance (e.g., https://thinkex.example.com).
BETTER_AUTH_URL	Must match NEXT_PUBLIC_APP_URL for authentication to work correctly.

Optional

Variable	Description
GOOGLE_CLIENT_ID	Enables Google OAuth login. Get from Google Cloud Console.
GOOGLE_CLIENT_SECRET	Required alongside GOOGLE_CLIENT_ID for Google OAuth.
NEXT_PUBLIC_SUPABASE_URL	Your Supabase project URL. Required when STORAGE_TYPE=supabase.
NEXT_PUBLIC_SUPABASE_ANON_KEY	Supabase anon (public) key. Required when STORAGE_TYPE=supabase.
SUPABASE_SERVICE_ROLE_KEY	Supabase service role key. Required when STORAGE_TYPE=supabase.
FIRECRAWL_API_KEY	Enables web scraping via Firecrawl.
MISTRAL_API_KEY	Enables Mistral OCR for enhanced document text extraction.

Never commit your .env file to version control. It contains secrets that grant access to your database and external services.