watson/umami
1
0
Fork 0
mirror of https://github.com/umami-software/umami.git synced 2025-12-06 01:18:00 +01:00
Code Issues Projects Releases Packages Wiki Activity Actions 1
umami/.kiro/specs/project-setup-and-configuration/tasks.md

7.5 KiB
Raw Blame History

Implementation Plan

  • 1. Create environment template file

    • Create .env.example file with all required and optional environment variables
    • Include comments explaining each variable's purpose
    • Add example values for DATABASE_URL with proper PostgreSQL format
    • Document optional variables like BASE_PATH, CLOUD_MODE, TRACKER_SCRIPT_NAME
    • Requirements: 2.2, 2.3

  • 2. Create comprehensive setup validation script

    • 2.1 Implement Node.js version validation

      • Create scripts/setup-validator.js with checkNodeVersion function
      • Use semver to compare against minimum version 18.18
      • Return validation result with pass/fail status and helpful message
      • Requirements: 1.2, 1.3

    • 2.2 Implement package manager validation

      • Add checkPackageManager function to verify pnpm is installed
      • Check if pnpm command is available in PATH
      • Provide installation instructions if missing
      • Requirements: 1.4

    • 2.3 Implement environment file validation

      • Add checkEnvFile function to verify .env exists
      • Check if DATABASE_URL is present and properly formatted
      • Validate PostgreSQL connection string format
      • Requirements: 2.1, 2.2, 2.4

    • 2.4 Implement dependency installation check

      • Add checkDependencies function to verify node_modules exists
      • Check if key dependencies are installed
      • Suggest running pnpm install if missing
      • Requirements: 1.5

    • 2.5 Create main validation orchestrator

      • Implement validateSetup function that runs all checks
      • Execute checks in logical order with early exit on critical failures
      • Format and display results with color-coded output using chalk
      • Return overall status (ready/incomplete/error) with next steps
      • Requirements: 6.1, 6.3

  • 3. Enhance existing validation scripts

    • 3.1 Improve check-env.js error messages

      • Add color-coded output for missing variables
      • Include example .env.example reference in error messages
      • Show specific format requirements for each variable
      • Add solution suggestions for common errors
      • Requirements: 2.2, 6.3

    • 3.2 Enhance check-db.js with better error handling

      • Improve error messages for connection failures
      • Add troubleshooting steps for common database issues
      • Include PostgreSQL installation/startup instructions
      • Add validation for database URL format before connection attempt
      • Display database version requirements clearly
      • Requirements: 2.4, 2.5, 6.4, 6.5

  • 4. Create comprehensive setup documentation

    • 4.1 Create SETUP.md with detailed instructions

      • Write prerequisites section with Node.js and PostgreSQL requirements
      • Document step-by-step installation process with expected outputs
      • Include environment configuration section with examples
      • Add database setup instructions for PostgreSQL
      • Create troubleshooting section for common errors
      • Requirements: 1.1, 1.3, 2.2

    • 4.2 Add quick start section to SETUP.md

      • Provide condensed command list for experienced developers
      • Include validation commands to run at each step
      • Add links to detailed sections for more information
      • Requirements: 1.1

    • 4.3 Document common error scenarios

      • List common setup errors with solutions
      • Include database connection troubleshooting
      • Add Node.js version mismatch solutions
      • Document missing environment variable fixes
      • Requirements: 1.3, 2.4, 6.4

  • 5. Create interactive setup wizard

    • 5.1 Implement quick-setup.js script

      • Create scripts/quick-setup.js with interactive prompts
      • Use prompts package for user input
      • Implement step-by-step wizard flow
      • Requirements: 1.1, 2.2

    • 5.2 Add prerequisite checking to wizard

      • Check Node.js version before proceeding
      • Verify pnpm is installed
      • Display clear error messages if prerequisites not met
      • Requirements: 1.2, 1.3

    • 5.3 Implement database configuration prompts

      • Prompt for PostgreSQL host, port, database name, username, password
      • Construct DATABASE_URL from user inputs
      • Validate connection before saving
      • Requirements: 2.1, 2.4, 2.5

    • 5.4 Add .env file creation to wizard

      • Generate .env file from user inputs
      • Include optional variables with default values
      • Confirm file creation with user
      • Requirements: 2.2

    • 5.5 Implement dependency installation step

      • Run pnpm install automatically
      • Display installation progress
      • Handle installation errors gracefully
      • Requirements: 1.4, 1.5

    • 5.6 Add build execution to wizard

      • Run pnpm run build after successful setup
      • Display build progress and logs
      • Confirm successful database table creation
      • Show default admin credentials
      • Requirements: 3.1, 3.2, 3.3

    • 5.7 Add completion summary

      • Display setup completion message
      • Show next steps (running dev or start command)
      • Provide links to documentation
      • Requirements: 4.2

  • 6. Add npm scripts for validation

    • Add "validate-setup" script to package.json that runs setup-validator.js
    • Add "setup" script that runs the interactive quick-setup.js
    • Update build script to run validation before building
    • Requirements: 6.1, 6.2

  • 7. Enhance development server startup

    • 7.1 Add pre-dev validation

      • Modify dev script to run setup validation before starting
      • Display clear error if validation fails
      • Show which checks failed and how to fix them
      • Requirements: 4.4, 6.1

    • 7.2 Improve dev server startup messages

      • Display clear success message with URL when server starts
      • Show port number (3001) prominently
      • Include instructions for accessing the application
      • Requirements: 4.2

  • 8. Enhance production server startup

    • 8.1 Add pre-start validation

      • Verify build artifacts exist before starting production server
      • Check that all environment variables are present
      • Validate database connectivity
      • Requirements: 5.2, 5.4, 5.5

    • 8.2 Improve production startup messages

      • Display production server URL (port 3000)
      • Show environment configuration summary
      • Include security reminders (change default password)
      • Requirements: 5.3

  • 9. Add validation result models and formatting

    • Create TypeScript interfaces for ValidationResult and SetupStatus
    • Implement formatResults function for consistent output formatting
    • Add color-coded status indicators (✓ for pass, ✗ for fail, ⚠ for warning)
    • Create formatError function for detailed error display with solutions
    • Requirements: 6.3, 6.4

  • 10. Create automated tests for validation scripts

    • 10.1 Write unit tests for setup-validator.js

      • Test Node.js version validation with various versions
      • Test environment file existence checks
      • Test database URL format validation
      • Mock file system operations for testing
      • Requirements: 1.2, 2.1, 2.4

    • 10.2 Write integration tests for setup flow

      • Test complete setup flow from start to finish
      • Test error recovery scenarios
      • Verify error messages are displayed correctly
      • Test validation script integration with build process
      • Requirements: 6.1, 6.2, 6.3

  • 11. Update main README with setup improvements

    • Add link to SETUP.md for detailed instructions
    • Update "Installing from Source" section with validation steps
    • Add troubleshooting section reference
    • Include quick-setup script mention for beginners
    • Requirements: 1.1, 1.3