Skip to main content

Manual Installation Guide

This guide explains how to set up TestPlanIt for local development manually, without using Docker.

Prerequisites​

Before you begin, ensure you have the following installed:

  • Node.js v20.9.0 minimum (v24.x LTS recommended)
  • pnpm (version 10+ recommended)
  • Git

Required Services:

  • PostgreSQL - Main database
  • Valkey or Redis - Job queue and caching (Redis-compatible)

Optional Services:

The application will run without these services, but certain features will be disabled:

  • Elasticsearch - Search and indexing
    • Without it: Search functionality will be unavailable, but the application will function normally otherwise
  • MinIO or AWS S3 - File storage for attachments
    • Without it: File uploads (attachments, avatars, project icons) will fail with an error message
  • SMTP Email Server - Email notifications and Magic Link authentication
    • Without it: In-app notifications will still work, but email delivery will fail; Magic Link authentication will be unavailable (use password authentication instead)

Installation & Setup Steps​

  1. Clone the repository: Open your terminal and clone the TestPlanIt monorepo:

    git clone https://github.com/testplanit/testplanit.git
    cd testplanit

  2. Install dependencies: Run the installation command from the monorepo root directory (testplanit/):

    pnpm install

    This installs dependencies for all packages in the monorepo.

  3. Set up environment variables: Navigate into the TestPlanIt application directory (testplanit/testplanit) and copy the example environment file:

    cd testplanit
    cp .env.example .env
    • Edit the newly created .env file. The most crucial setting is DATABASE_URL. Update this value to point to your locally running PostgreSQL instance.
    • Add the Valkey URL: Add VALKEY_URL="valkey://localhost:6379" (or the appropriate URL if your Valkey instance is running elsewhere or requires authentication) to the file. This is needed for background job processing.
    • Review other settings like NEXTAUTH_SECRET (generate a new secret if needed), email server details (required for Magic Link authentication and notifications), etc., and configure them according to your needs.
    • Admin User Seeding: The ADMIN_EMAIL, ADMIN_NAME, and ADMIN_PASSWORD variables are used by the pnpm prisma db seed command to create the initial administrator user. You can customize these values in your .env file if you prefer different default credentials.
    • Demo Project: The seed script also creates a pre-populated Demo Project with sample test cases, test runs, sessions, milestones, tags, and issues. This helps new users explore TestPlanIt's features immediately. You can delete the Demo Project at any time from Administration > Projects.

  4. Run database migrations: Navigate back into the application directory (testplanit/testplanit) and run the Prisma migrations to create the necessary database tables:

    cd testplanit # Ensure you are in the testplanit/testplanit directory
    pnpm prisma migrate dev

  5. Run the development server: Still within the testplanit/testplanit directory, start the Next.js development server:

    pnpm dev

  6. Access TestPlanIt: Open your web browser and navigate to http://localhost:3000. You should see the TestPlanIt application.

You are now ready to start using TestPlanIt locally!