Add GitHub Copilot instructions for Spring Boot Admin development (#4556)

Co-authored-by: copilot-swe-agent[bot] <[email protected]>
Co-authored-by: ulischulte <[email protected]>

Author: Copilot

.github/copilot-instructions.md

@@ -0,0 +1,149 @@
+# Spring Boot Admin
+Spring Boot Admin is a multi-module Maven project providing an admin interface for Spring Boot applications that expose actuator endpoints. It consists of a Vue.js frontend and Java backend components with 19 Maven modules.
+
+Always reference these instructions first and fallback to search or bash commands only when you encounter unexpected information that does not match the info here.
+
+## Working Effectively
+
+### Prerequisites and Environment Setup
+- Install Java 17 (OpenJDK Temurin 17.0.16+ recommended) - project requires exactly Java 17
+- Install Node.js 22.18.0 exactly (project specifies this in .nvmrc and package.json)
+- Download Node.js 22.18.0: `curl -fsSL https://nodejs.org/dist/v22.18.0/node-v22.18.0-linux-x64.tar.xz -o /tmp/node.tar.xz`
+- Extract and configure PATH: `cd /tmp && tar -xf node.tar.xz && export PATH="/tmp/node-v22.18.0-linux-x64/bin:$PATH"`
+- Verify versions: `java -version` (should show 17.x) and `node --version` (should show v22.18.0)
+
+### Building the Project
+- **NEVER CANCEL builds - they take time but will complete successfully**
+- **CRITICAL**: Set timeout to 20+ minutes for builds, 60+ minutes for tests
+- Clean compile: `export PATH="/tmp/node-v22.18.0-linux-x64/bin:$PATH" && ./mvnw clean compile -B --no-transfer-progress -DskipTests` -- takes ~10.5 minutes
+- Full package: `export PATH="/tmp/node-v22.18.0-linux-x64/bin:$PATH" && ./mvnw package -B --no-transfer-progress -DskipTests` -- takes ~4 minutes  
+- Install to local repository: `export PATH="/tmp/node-v22.18.0-linux-x64/bin:$PATH" && ./mvnw install -B --no-transfer-progress -DskipTests` -- takes ~1.5 minutes
+
+### Testing
+- **NEVER CANCEL test runs - set 60+ minute timeouts**
+- Full test suite: `export PATH="/tmp/node-v22.18.0-linux-x64/bin:$PATH" && ./mvnw test -B --no-transfer-progress` -- takes 20-40 minutes
+- UI tests only: `cd spring-boot-admin-server-ui && export PATH="/tmp/node-v22.18.0-linux-x64/bin:$PATH" && npm run test` -- takes ~44 seconds
+- UI build only: `cd spring-boot-admin-server-ui && export PATH="/tmp/node-v22.18.0-linux-x64/bin:$PATH" && npm run build` -- takes ~16 seconds
+
+### Code Quality and Formatting
+- Format Java code: `./mvnw spring-javaformat:apply`
+- Check Java formatting: `./mvnw spring-javaformat:validate`
+- Lint UI code: `cd spring-boot-admin-server-ui && npm run lint`
+- Format UI code: `cd spring-boot-admin-server-ui && npm run format:fix`
+- **ALWAYS** run `./mvnw spring-javaformat:apply` and UI formatting before committing
+- **ALWAYS** run `./mvnw checkstyle:check` to verify compliance
+
+### Running Sample Applications
+- Build and install all modules first: `export PATH="/tmp/node-v22.18.0-linux-x64/bin:$PATH" && ./mvnw install -B --no-transfer-progress -DskipTests`
+- Run servlet sample: `cd spring-boot-admin-samples/spring-boot-admin-sample-servlet && export PATH="/tmp/node-v22.18.0-linux-x64/bin:$PATH" && ../../mvnw spring-boot:run -Dspring-boot.run.profiles=dev,insecure`
+- Access UI at: `http://localhost:8080` (username: user, password shown in logs or use insecure profile)
+- Application starts in ~3 seconds and shows "all up" status with registered instance
+
+### UI Development Mode
+- For UI development: `cd spring-boot-admin-server-ui && npm run build:watch` (builds on file changes)
+- Configure Spring Boot Admin Server with: 
+  ```
+  spring.boot.admin.ui.cache.no-cache: true
+  spring.boot.admin.ui.resource-locations: file:../../spring-boot-admin-server-ui/target/dist/
+  spring.boot.admin.ui.template-location: file:../../spring-boot-admin-server-ui/target/dist/
+  spring.boot.admin.ui.cache-templates: false
+  ```
+
+## Validation Scenarios
+- **MANUAL VALIDATION REQUIRED**: After building and running, always test actual functionality
+- Launch sample application and verify Spring Boot Admin UI loads at `http://localhost:8080`
+- Verify application registration: Should show "spring-boot-admin-sample-servlet" with UP status
+- Test navigation: Click on Applications, Wallboard, and instance details
+- Check endpoints: Verify actuator endpoints are detected and accessible
+- Test monitoring features: Instance details should show health, metrics, loggers, etc.
+
+## Key Modules and Locations
+
+### Primary Components
+- **Root**: `/` - Main Maven reactor project (pom.xml)
+- **Server Backend**: `spring-boot-admin-server/` - Core Spring Boot Admin server functionality
+- **UI Frontend**: `spring-boot-admin-server-ui/` - Vue.js 3 web interface with Vite build
+- **Client**: `spring-boot-admin-client/` - Client library for connecting applications
+- **Documentation**: `spring-boot-admin-docs/` - Asciidoc documentation
+
+### Starter Modules
+- **Server Starter**: `spring-boot-admin-starter-server/` - Auto-configuration for servers
+- **Client Starter**: `spring-boot-admin-starter-client/` - Auto-configuration for clients
+
+### Sample Applications (in spring-boot-admin-samples/)
+- **servlet**: Standard servlet-based sample (recommended for testing)
+- **reactive**: WebFlux reactive sample
+- **eureka**: Eureka discovery integration
+- **consul**: Consul discovery integration
+- **hazelcast**: Hazelcast session management
+- **war**: WAR deployment sample
+- **zookeeper**: Zookeeper discovery integration
+
+### Infrastructure
+- **Dependencies**: `spring-boot-admin-dependencies/` - Dependency management BOM
+- **Build**: `spring-boot-admin-build/` - Build configuration and tooling
+- **Server Cloud**: `spring-boot-admin-server-cloud/` - Spring Cloud integrations
+
+## Common Issues and Solutions
+
+### Build Issues
+- Node.js version mismatch: Always use exact PATH override with v22.18.0
+- Missing dependencies: Run `./mvnw install` to install all modules to local Maven repository
+- Checkstyle violations: Run `./mvnw spring-javaformat:apply` to auto-fix formatting
+- UI build failures: Verify Node.js version and run `npm install` in spring-boot-admin-server-ui/
+- "Command timed out": Increase timeout - builds legitimately take 10+ minutes
+
+### Runtime Issues
+- Sample app dependency resolution: Must run `./mvnw install` first to populate local repository
+- Config server connection refused: Normal warning, config server is optional in dev mode
+- Security warnings: Use `insecure` profile for development to bypass authentication
+
+## Development Workflow
+1. **Setup**: Configure Node.js 22.18.0 in PATH: `export PATH="/tmp/node-v22.18.0-linux-x64/bin:$PATH"`
+2. **Initial Build**: Run `./mvnw clean compile` to verify everything builds (~10.5 minutes - be patient)
+3. **Install Dependencies**: Run `./mvnw install -DskipTests` for sample app dependencies (~1.5 minutes)
+4. **Make Changes**: Edit code in appropriate modules
+5. **Format Code**: Run `./mvnw spring-javaformat:apply` and UI `npm run format:fix`
+6. **Test Build**: Run build commands to verify changes don't break anything
+7. **Manual Validation**: Start sample application and test UI functionality
+8. **Final Check**: Ensure formatting and linting pass before committing
+
+## Critical Timing Information
+- **NEVER CANCEL**: Build commands take significant time but complete successfully
+- Clean compile: ~10.5 minutes (normal, expected)
+- Package build: ~4 minutes
+- Install build: ~1.5 minutes
+- Full test suite: 20-40 minutes (set 60+ minute timeout)
+- UI tests only: ~44 seconds
+- UI build only: ~16 seconds
+- Application startup: ~3 seconds
+
+## Technology Stack
+- **Backend**: Spring Boot 3.5, Java 17, Maven multi-module
+- **Frontend**: Vue.js 3, Vite, TypeScript, Tailwind CSS
+- **Testing**: JUnit 5 (Java), Vitest (UI), Playwright integration
+- **Build**: Maven 3.9+, Node.js 22.18.0, npm
+- **Code Quality**: Spring Java Format, Checkstyle, ESLint, Prettier
+
+## Repository Structure Overview
+```
+spring-boot-admin/                    # Root project (19 modules)
+├── .github/                         # GitHub configuration
+├── spring-boot-admin-build/         # Build configuration
+├── spring-boot-admin-client/        # Client library
+├── spring-boot-admin-dependencies/  # Dependency management
+├── spring-boot-admin-docs/          # Documentation (Asciidoc)
+├── spring-boot-admin-samples/       # Sample applications
+│   ├── spring-boot-admin-sample-servlet/    # Main sample (recommended)
+│   ├── spring-boot-admin-sample-reactive/   # WebFlux sample
+│   └── [other samples]/            # Various integration samples
+├── spring-boot-admin-server/        # Core server implementation
+├── spring-boot-admin-server-cloud/  # Spring Cloud integrations
+├── spring-boot-admin-server-ui/     # Vue.js frontend
+│   ├── src/main/frontend/          # Vue.js source code
+│   ├── package.json                # Node.js dependencies
+│   └── .nvmrc                      # Node.js version specification
+├── spring-boot-admin-starter-*/     # Spring Boot auto-configuration
+├── mvnw                            # Maven wrapper
+└── pom.xml                         # Root Maven configuration
+```