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 v24.x LTS
  • pnpm v11 — the repository pins the exact version via the packageManager field in the root package.json, so the simplest setup is to run corepack enable (Corepack ships with Node.js) and let it provision the matching pnpm automatically
  • Git

System requirements:

  • RAM: about 2 GB free for pnpm install (the ZenStack code-generation step peaks under 0.5 GB) and about 8 GB free for a production pnpm build (the Next.js/Turbopack build peaks around 7 GB across its process tree). Lower-memory machines can add swap; the steps then complete more slowly instead of being killed. For production, the Docker images remain the recommended path — the same build there also fits ~8 GB.

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
  • RustFS, AWS S3, or another S3-compatible service - 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 tsx db/seed.ts 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. Sync the database schema: Navigate back into the application directory (testplanit/testplanit) and push the schema to create the necessary database tables (this project uses ZenStack`s push workflow from schema.zmodel, not migrations):

    cd testplanit # Ensure you are in the testplanit/testplanit directory
    pnpm generate

  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!