Skip to content

ActivityPub-federated video streaming platform using P2P directly in your web browser

Add copilot instructions

Chocobozzzfcca9b72d344
diff --git a/.github/copilot-instructions.md b/.github/copilot-instructions.md
new file mode 100644
index 0000000000..a219e7b442
--- /dev/null
+++ b/.github/copilot-instructions.md
@@ -0,0 +1,222 @@
+# PeerTube Copilot Instructions
+
+## Repository Overview
+
+PeerTube is an open-source, ActivityPub-federated video streaming platform using P2P technology directly in web browsers. It's developed by Framasoft and provides a decentralized alternative to centralized video platforms like YouTube.
+
+**Repository Stats:**
+- **Size**: Large monorepo (~350MB, ~15k files)
+- **Type**: Full-stack web application
+- **Languages**: TypeScript (backend), Angular (frontend), Shell scripts
+- **Target Runtime**: Node.js >=20.x, PostgreSQL >=10.x, Redis >=6.x
+- **Package Manager**: Yarn 1.x (NOT >=2.x)
+- **Architecture**: Express.js API server + Angular SPA client + P2P video delivery
+
+## Critical: Client Directory Exclusion
+
+**🚫 ALWAYS IGNORE `client/` directory** - it contains a separate Angular frontend project with its own build system, dependencies, and development workflow. Focus only on the server-side backend code.
+
+## Build & Development Commands
+
+### Prerequisites (Required)
+1. **Dependencies**: Node.js >=20.x, Yarn 1.x, PostgreSQL >=10.x, Redis >=6.x, FFmpeg >=4.3, Python >=3.8
+2. **PostgreSQL Setup**:
+ ```bash
+ sudo -u postgres createuser -P peertube
+ sudo -u postgres createdb -O peertube peertube_dev
+ sudo -u postgres psql -c "CREATE EXTENSION pg_trgm;" peertube_dev
+ sudo -u postgres psql -c "CREATE EXTENSION unaccent;" peertube_dev
+ ```
+3. **Services**: Start PostgreSQL and Redis before development
+
+### Installation & Build (Execute in Order)
+```bash
+# 1. ALWAYS install dependencies first (takes ~2-3 minutes)
+yarn install --frozen-lockfile
+
+# 2. Build server (required for most operations, takes ~3-5 minutes)
+npm run build:server
+
+# 3. Optional: Build full application (takes ~10-15 minutes)
+npm run build
+```
+
+**⚠️ Critical Notes:**
+- Always run `yarn install --frozen-lockfile` before any build operation
+- Server build is prerequisite for testing and development
+- Never use `npm install` - always use `yarn`
+- Build failures often indicate missing PostgreSQL extensions or wrong Node.js version
+
+### Development Commands
+```bash
+# Server-only development (recommended for backend work)
+npm run dev:server # Starts server on localhost:9000 with hot reload
+
+# Full stack development (NOT recommended if only working on server)
+npm run dev # Starts both server (9000) and client (3000)
+
+# Development credentials:
+# Username: root
+# Password: test
+```
+
+### Testing Commands (Execute in Order)
+```bash
+# 1. Prepare test environment (required before first test run)
+sudo -u postgres createuser $(whoami) --createdb --superuser
+npm run clean:server:test
+
+# 2. Build (required before testing)
+npm run build
+
+# 3. Run specific test suites (recommended over full test)
+npm run ci -- api-1 # API tests part 1
+npm run ci -- api-2 # API tests part 2
+npm run ci -- lint # Linting only
+npm run ci -- client # Client tests
+
+# 4. Run single test file
+npm run mocha -- --exit --bail packages/tests/src/api/videos/single-server.ts
+
+# 5. Full test suite (takes ~45-60 minutes, avoid unless necessary)
+npm run test
+```
+
+**⚠️ Test Environment Notes:**
+- Tests require PostgreSQL user with createdb/superuser privileges
+- Some tests need Docker containers for S3/LDAP simulation
+- Test failures often indicate missing system dependencies or DB permissions
+- Set `DISABLE_HTTP_IMPORT_TESTS=true` to skip flaky import tests
+
+### Validation Commands
+```bash
+# Lint code (runs ESLint + OpenAPI validation)
+npm run lint
+
+# Validate OpenAPI spec
+npm run swagger-cli -- validate support/doc/api/openapi.yaml
+
+# Build server
+npm run build:server
+```
+
+## Project Architecture & Layout
+
+### Server-Side Structure (Primary Focus)
+```
+server/core/
+β”œβ”€β”€ controllers/api/ # Express route handlers (add new endpoints here)
+β”‚ β”œβ”€β”€ index.ts # Main API router registration
+β”‚ β”œβ”€β”€ videos/ # Video-related endpoints
+β”‚ └── users/ # User-related endpoints
+β”œβ”€β”€ models/ # Sequelize database models
+β”‚ β”œβ”€β”€ video/ # Video, channel, playlist models
+β”‚ └── user/ # User, account models
+β”œβ”€β”€ lib/ # Business logic services
+β”‚ β”œβ”€β”€ job-queue/ # Background job processing
+β”‚ └── emailer.ts # Email service
+β”œβ”€β”€ middlewares/ # Express middleware
+β”‚ β”œβ”€β”€ validators/ # Input validation (always required)
+β”‚ └── auth.ts # Authentication middleware
+β”œβ”€β”€ helpers/ # Utility functions
+└── initializers/ # App startup and constants
+```
+
+### Key Configuration Files
+- `package.json` - Main dependencies and scripts
+- `server/package.json` - Server-specific config
+- `eslint.config.mjs` - Linting rules
+- `tsconfig.base.json` - TypeScript base config
+- `config/default.yaml` - Default app configuration
+- `.mocharc.cjs` - Test runner configuration
+
+### Shared Packages (`packages/`)
+```
+packages/
+β”œβ”€β”€ models/ # Shared TypeScript interfaces (modify for API changes)
+β”œβ”€β”€ core-utils/ # Common utilities
+β”œβ”€β”€ ffmpeg/ # Video processing
+β”œβ”€β”€ server-commands/ # Test helpers
+└── tests/ # Test files
+```
+
+### Scripts Directory (`scripts/`)
+- `scripts/build/` - Build automation
+- `scripts/dev/` - Development helpers
+- `scripts/ci.sh` - Continuous integration runner
+- `scripts/test.sh` - Test runner
+
+## Continuous Integration Pipeline
+
+**GitHub Actions** (`.github/workflows/test.yml`):
+1. **Matrix Strategy**: Tests run in parallel across different suites
+2. **Required Services**: PostgreSQL, Redis, LDAP, S3, Keycloak containers
+3. **Test Suites**: `types-package`, `client`, `api-1` through `api-5`, `transcription`, `cli-plugin`, `lint`, `external-plugins`
+4. **Environment**: Ubuntu 22.04, Node.js 20.x
+5. **Typical Runtime**: 15-30 minutes per suite
+
+**Pre-commit Checks**: ESLint, TypeScript compilation, OpenAPI validation
+
+## Making Code Changes
+
+### Adding New API Endpoint
+1. Create controller in `server/core/controllers/api/`
+2. Add validation middleware in `server/core/middlewares/validators/`
+3. Register route in `server/core/controllers/api/index.ts`
+4. Update shared types in `packages/models/`
+5. Add OpenAPI documentation tags
+6. Write tests in `packages/tests/src/api/`
+
+### Common Patterns to Follow
+```typescript
+// Controller pattern
+import express from 'express'
+import { apiRateLimiter, asyncMiddleware } from '../../middlewares/index.js'
+
+const router = express.Router()
+router.use(apiRateLimiter) // ALWAYS include rate limiting
+
+router.get('/:id',
+ validationMiddleware, // ALWAYS validate inputs
+ asyncMiddleware(handler) // ALWAYS wrap async handlers
+)
+```
+
+### Database Changes
+1. Create/modify Sequelize model in `server/core/models/`
+2. Generate migration in `server/core/initializers/migrations/`
+3. Update shared types in `packages/models/`
+4. Run `npm run build:server` to compile
+
+## Validation Steps Before PR
+
+1. **Build**: `npm run build` (must succeed)
+2. **Lint**: `npm run lint` (must pass without errors)
+5. **OpenAPI**: Validate if API changes made
+
+## Common Error Solutions
+
+**Build Errors:**
+- "Cannot find module": Run `yarn install --frozen-lockfile`
+- "PostgreSQL connection": Check PostgreSQL is running and extensions installed
+- TypeScript errors: Check Node.js version (must be >=20.x)
+
+**Test Errors:**
+- Permission denied: Ensure PostgreSQL user has createdb/superuser rights
+- Port conflicts: Stop other PeerTube instances
+- Import test failures: Set `DISABLE_HTTP_IMPORT_TESTS=true`
+
+**Development Issues:**
+- "Client dist not found": Run `npm run build:client` (only if working on client features)
+- Redis connection: Ensure Redis server is running
+- Hot reload not working: Kill all Node processes and restart
+
+## Trust These Instructions
+
+These instructions have been validated against the current codebase. Only search for additional information if:
+- Commands fail with updated error messages
+- New dependencies are added to package.json
+- Build system changes are detected
+- You need specific implementation details not covered here
+
+Focus on server-side TypeScript development in `server/core/` and ignore the `client/` directory unless explicitly working on frontend integration.
diff --git a/client/.github/instructions/angular.instructions.md b/client/.github/instructions/angular.instructions.md
new file mode 100644
index 0000000000..8f26f48630
--- /dev/null
+++ b/client/.github/instructions/angular.instructions.md
@@ -0,0 +1,104 @@
+---
+description: 'Angular-specific coding standards and best practices'
+applyTo: 'src/app/**/*.ts, src/app/**/*.html, src/app/**/*.scss, src/app/**/*.css'
+---
+
+# Angular Development Instructions
+
+Instructions for generating high-quality Angular applications with TypeScript, using Angular Signals for state management, adhering to Angular best practices as outlined at https://angular.dev.
+
+## Project Context
+- Latest Angular version (use standalone components by default)
+- TypeScript for type safety
+- Angular CLI for project setup and scaffolding
+- Follow Angular Style Guide (https://angular.dev/style-guide)
+- Use Angular Material or other modern UI libraries for consistent styling (if specified)
+
+## Development Standards
+
+### Architecture
+- Use standalone components unless modules are explicitly required
+- Organize code by feature modules or domains for scalability
+- Implement lazy loading for feature modules to optimize performance
+- Use Angular's built-in dependency injection system effectively
+- Structure components with a clear separation of concerns (smart vs. presentational components)
+
+### TypeScript
+- Enable strict mode in `tsconfig.json` for type safety
+- Define clear interfaces and types for components, services, and models
+- Use type guards and union types for robust type checking
+- Implement proper error handling with RxJS operators (e.g., `catchError`)
+- Use typed forms (e.g., `FormGroup`, `FormControl`) for reactive forms
+
+### Component Design
+- Follow Angular's component lifecycle hooks best practices
+- When using Angular >= 19, Use `input()` `output()`, `viewChild()`, `viewChildren()`, `contentChild()` and `viewChildren()` functions instead of decorators; otherwise use decorators
+- Leverage Angular's change detection strategy (default or `OnPush` for performance)
+- Keep templates clean and logic in component classes or services
+- Use Angular directives and pipes for reusable functionality
+
+### Styling
+- Use Angular's component-level CSS encapsulation (default: ViewEncapsulation.Emulated)
+- Prefer SCSS for styling with consistent theming
+- Implement responsive design using CSS Grid, Flexbox, or Angular CDK Layout utilities
+- Follow Angular Material's theming guidelines if used
+- Maintain accessibility (a11y) with ARIA attributes and semantic HTML
+
+### State Management
+- Use Angular Signals for reactive state management in components and services
+- Leverage `signal()`, `computed()`, and `effect()` for reactive state updates
+- Use writable signals for mutable state and computed signals for derived state
+- Handle loading and error states with signals and proper UI feedback
+- Use Angular's `AsyncPipe` to handle observables in templates when combining signals with RxJS
+
+### Data Fetching
+- Use Angular's `HttpClient` for API calls with proper typing
+- Implement RxJS operators for data transformation and error handling
+- Use Angular's `inject()` function for dependency injection in standalone components
+- Implement caching strategies (e.g., `shareReplay` for observables)
+- Store API response data in signals for reactive updates
+- Handle API errors with global interceptors for consistent error handling
+
+### Security
+- Sanitize user inputs using Angular's built-in sanitization
+- Implement route guards for authentication and authorization
+- Use Angular's `HttpInterceptor` for CSRF protection and API authentication headers
+- Validate form inputs with Angular's reactive forms and custom validators
+- Follow Angular's security best practices (e.g., avoid direct DOM manipulation)
+
+### Performance
+- Enable production builds with `ng build --prod` for optimization
+- Use lazy loading for routes to reduce initial bundle size
+- Optimize change detection with `OnPush` strategy and signals for fine-grained reactivity
+- Use trackBy in `ngFor` loops to improve rendering performance
+- Implement server-side rendering (SSR) or static site generation (SSG) with Angular Universal (if specified)
+
+### Testing
+- Write unit tests for components, services, and pipes using Jasmine and Karma
+- Use Angular's `TestBed` for component testing with mocked dependencies
+- Test signal-based state updates using Angular's testing utilities
+- Write end-to-end tests with Cypress or Playwright (if specified)
+- Mock HTTP requests using `HttpClientTestingModule`
+- Ensure high test coverage for critical functionality
+
+## Implementation Process
+1. Plan project structure and feature modules
+2. Define TypeScript interfaces and models
+3. Scaffold components, services, and pipes using Angular CLI
+4. Implement data services and API integrations with signal-based state
+5. Build reusable components with clear inputs and outputs
+6. Add reactive forms and validation
+7. Apply styling with SCSS and responsive design
+8. Implement lazy-loaded routes and guards
+9. Add error handling and loading states using signals
+10. Write unit and end-to-end tests
+11. Optimize performance and bundle size
+
+## Additional Guidelines
+- Follow Angular's naming conventions (e.g., `feature.component.ts`, `feature.service.ts`)
+- Use Angular CLI commands for generating boilerplate code
+- Document components and services with clear JSDoc comments
+- Ensure accessibility compliance (WCAG 2.1) where applicable
+- Use Angular's built-in i18n for internationalization (if specified)
+- Keep code DRY by creating reusable utilities and shared modules
+- Use signals consistently for state management to ensure reactive updates
diff --git a/client/.github/instructions/copilot-instructions.md b/client/.github/instructions/copilot-instructions.md
new file mode 100644
index 0000000000..9b2a79ddc4
--- /dev/null
+++ b/client/.github/instructions/copilot-instructions.md
@@ -0,0 +1,112 @@
+# PeerTube Client Development Instructions for Coding Agents
+
+## Client Overview
+
+This is the Angular frontend for PeerTube, a decentralized video hosting platform. The client is built with Angular 20+, TypeScript, and SCSS. It communicates with the PeerTube server API and provides the web interface for users, administrators, and content creators.
+
+**Key Technologies:**
+- Angular 20+ with standalone components
+- TypeScript 5+
+- SCSS for styling
+- RxJS for reactive programming
+- PrimeNg and Bootstrap for UI components
+- WebdriverIO for E2E testing
+- Angular CLI
+
+## Client Build and Development Commands
+
+### Prerequisites (for client development)
+- Node.js 20+
+- yarn 1
+- Running PeerTube server (see ../server instructions)
+
+### Essential Client Commands
+
+```bash
+# From the client directory:
+cd /client
+
+# 1. Install dependencies (ALWAYS first)
+yarn install --pure-lockfile
+
+# 2. Development server with hot reload
+npm run dev
+
+# 3. Build for production
+npm run build
+```
+
+### Client Testing Commands
+```bash
+# From client directory:
+npm run lint # ESLint for client code
+```
+
+### Common Client Issues and Solutions
+
+**Angular Build Failures:**
+- Always run `yarn install --pure-lockfile` after pulling changes
+- Clear `node_modules` and reinstall if dependency errors occur
+- Build may fail on memory issues: `NODE_OPTIONS="--max-old-space-size=4096" npm run build`
+- Check TypeScript errors carefully - Angular is strict about types
+
+**Development Server Issues:**
+- Default port is 3000, ensure it's not in use
+- Hot reload may fail on file permission issues
+- Clear browser cache if changes don't appear
+
+## Client Architecture and File Structure
+
+### Client Directory Structure
+```
+/src/
+ /app/
+ +admin/ # Admin interface components
+ +my-account/ # User account management pages
+ +my-library/ # User's videos, playlists, subscriptions
+ +search/ # Search functionality and results
+ +shared/ # Shared Angular components, services, pipes
+ +standalone/ # Standalone Angular components
+ +videos/ # Video-related components (watch, upload, etc.)
+ /core/ # Core services (auth, server, notifications)
+ /helpers/ # Utility functions and helpers
+ /menu/ # Navigation menu components
+ /assets/ # Static assets (images, icons, etc.)
+ /environments/ # Environment configurations
+ /locale/ # Internationalization files
+ /sass/ # Global SCSS styles
+```
+
+### Key Client Configuration Files
+
+- `angular.json` - Angular CLI workspace configuration
+- `tsconfig.json` - TypeScript configuration for client
+- `e2e/wdio*.conf.js` - WebdriverIO E2E test configurations
+- `src/environments/` - Environment-specific configurations
+
+### Shared Code with Server (`../shared/`)
+
+The client imports TypeScript models and utilities from the shared directory:
+- `../shared/models/` - Data models (Video, User, Channel, etc.). Import these in client code: `import { Video } from '@peertube/peertube-models'`
+- `../shared/core-utils/` - Utility functions shared between client/server. Import these in client code: `import { ... } from '@peertube/peertube-core-utils'`
+-
+
+## Client Development Workflow
+
+### Making Client Changes
+
+1. **Angular Components:** Create/modify in `/src/app/` following existing patterns
+2. **Shared Components:** Reusable components go in `/src/app/shared/`
+3. **Services:** Core services in `/src/app/core/`, feature services with components
+4. **Styles:** Component styles in `.scss` files, global styles in `/src/sass/`
+5. **Assets:** Images, icons in `/src/assets/`
+6. **Routing:** Routes defined in feature modules or `app-routing.module.ts`
+
+## Trust These Instructions
+
+These instructions are comprehensive and tested specifically for client development. Only search for additional information if:
+1. Commands fail despite following instructions exactly
+2. New error messages appear that aren't documented here
+3. You need specific Angular implementation details not covered above
+
+For server-side questions, refer to the server instructions in `../.github/copilot-instructions.md`.