# RedFlag Development Guide ## Prerequisites - **Go 1.21+** - Backend and agent development - **Node.js 18+** - Web dashboard development - **Docker & Docker Compose** - Database and containerized deployments - **Make** - Build automation (optional but recommended) --- ## Quick Start (Development) ```bash # Clone repository git clone https://github.com/Fimeg/RedFlag.git cd RedFlag # Start database docker-compose up -d postgres # Build and run server cd aggregator-server go mod tidy go build -o redflag-server cmd/server/main.go ./redflag-server --setup ./redflag-server # Build and run agent (separate terminal) cd aggregator-agent go mod tidy go build -o redflag-agent cmd/agent/main.go ./redflag-agent --server http://localhost:8080 --token --register # Run web dashboard (separate terminal) cd aggregator-web npm install npm run dev ``` --- ## Makefile Commands ```bash make help # Show all available commands make build-all # Build server, agent, and web make build-server # Build server binary make build-agent # Build agent binary make build-web # Build web dashboard make db-up # Start PostgreSQL container make db-down # Stop PostgreSQL container make db-reset # Reset database (WARNING: destroys data) make server # Run server with auto-reload make agent # Run agent make web # Run web dev server make test # Run all tests make test-server # Run server tests make test-agent # Run agent tests make clean # Clean build artifacts make docker-build # Build Docker images make docker-up # Start all services in Docker make docker-down # Stop all Docker services ``` --- ## Project Structure ``` RedFlag/ ├── aggregator-server/ # Go server backend │ ├── cmd/server/ # Main server entry point │ ├── internal/ │ │ ├── api/ # REST API handlers and middleware │ │ ├── database/ # Database layer with migrations │ │ ├── models/ # Data models and structs │ │ └── config/ # Configuration management │ ├── Dockerfile │ └── go.mod ├── aggregator-agent/ # Cross-platform Go agent │ ├── cmd/agent/ # Agent main entry point │ ├── internal/ │ │ ├── client/ # HTTP client with token renewal │ │ ├── config/ # Configuration system │ │ ├── scanner/ # Update scanners (APT, DNF, Winget, etc.) │ │ ├── installer/ # Package installers │ │ ├── system/ # System information collection │ │ └── service/ # Windows service integration │ ├── install.sh # Linux installation script │ └── go.mod ├── aggregator-web/ # React dashboard │ ├── src/ │ │ ├── components/ # Reusable UI components │ │ ├── pages/ # Page components │ │ ├── hooks/ # Custom React hooks │ │ ├── lib/ # API client and utilities │ │ └── types/ # TypeScript type definitions │ ├── Dockerfile │ └── package.json ├── docs/ # Documentation ├── docker-compose.yml # Development environment ├── Makefile # Build automation └── README.md ``` --- ## Building from Source ### Server ```bash cd aggregator-server go mod tidy go build -o redflag-server cmd/server/main.go ``` ### Agent ```bash cd aggregator-agent go mod tidy # Linux go build -o redflag-agent cmd/agent/main.go # Windows (cross-compile from Linux) GOOS=windows GOARCH=amd64 go build -o redflag-agent.exe cmd/agent/main.go # macOS (future support) GOOS=darwin GOARCH=amd64 go build -o redflag-agent cmd/agent/main.go ``` ### Web Dashboard ```bash cd aggregator-web npm install npm run build # Production build npm run dev # Development server ``` --- ## Running Tests ### Server Tests ```bash cd aggregator-server go test ./... go test -v ./internal/api/... # Verbose output for specific package go test -cover ./... # With coverage ``` ### Agent Tests ```bash cd aggregator-agent go test ./... go test -v ./internal/scanner/... # Specific package ``` ### Web Tests ```bash cd aggregator-web npm test npm run test:coverage ``` --- ## Database Migrations Migrations are in `aggregator-server/internal/database/migrations/` ### Create New Migration ```bash # Naming: XXX_description.up.sql touch aggregator-server/internal/database/migrations/013_add_feature.up.sql ``` ### Run Migrations ```bash cd aggregator-server ./redflag-server --migrate ``` ### Migration Best Practices - Always use `.up.sql` suffix - Include rollback logic in comments - Test migrations on copy of production data - Keep migrations idempotent when possible --- ## Docker Development ### Build All Images ```bash docker-compose build ``` ### Build Specific Service ```bash docker-compose build aggregator-server docker-compose build aggregator-agent docker-compose build aggregator-web ``` ### View Logs ```bash docker-compose logs -f # All services docker-compose logs -f aggregator-server # Specific service ``` ### Rebuild Without Cache ```bash docker-compose build --no-cache docker-compose up -d --force-recreate ``` --- ## Code Style ### Go - Use `gofmt` and `goimports` before committing - Follow standard Go naming conventions - Add comments for exported functions - Keep functions small and focused ```bash # Format code gofmt -w . goimports -w . # Lint golangci-lint run ``` ### TypeScript/React - Use Prettier for formatting - Follow ESLint rules - Use TypeScript strict mode - Prefer functional components with hooks ```bash # Format code npm run format # Lint npm run lint ``` --- ## Debugging ### Server Debug Mode ```bash ./redflag-server --log-level debug ``` ### Agent Debug Mode ```bash ./redflag-agent --log-level debug ``` ### Web Debug Mode ```bash npm run dev # Includes source maps and hot reload ``` ### Database Queries ```bash # Connect to PostgreSQL docker exec -it redflag-postgres psql -U redflag -d redflag # Common queries SELECT * FROM agents; SELECT * FROM registration_tokens; SELECT * FROM agent_commands WHERE status = 'pending'; ``` --- ## Common Development Tasks ### Reset Everything ```bash docker-compose down -v # Destroy all data make clean # Clean build artifacts rm -rf aggregator-agent/cache/ docker-compose up -d # Start fresh ``` ### Update Dependencies ```bash # Go modules cd aggregator-server && go get -u ./... cd aggregator-agent && go get -u ./... # npm packages cd aggregator-web && npm update ``` ### Generate Mock Data ```bash # Create test registration token curl -X POST http://localhost:8080/api/v1/admin/registration-tokens \ -H "Authorization: Bearer $ADMIN_TOKEN" \ -d '{"label": "Test Token", "max_seats": 10}' ``` --- ## Release Process 1. Update version in `aggregator-agent/cmd/agent/main.go` 2. Update CHANGELOG.md 3. Run full test suite 4. Build release binaries 5. Create git tag 6. Push to GitHub ```bash # Build release binaries make build-all # Create tag git tag -a v0.1.17 -m "Release v0.1.17" git push origin v0.1.17 ``` --- ## Troubleshooting ### "Permission denied" on Linux ```bash # Give execute permissions chmod +x redflag-agent chmod +x redflag-server ``` ### Database connection issues ```bash # Check if PostgreSQL is running docker ps | grep postgres # Check connection psql -h localhost -U redflag -d redflag ``` ### Port already in use ```bash # Find process using port 8080 lsof -i :8080 kill -9 ``` --- ## Contributing 1. Fork the repository 2. Create a feature branch 3. Make your changes 4. Run tests 5. Submit a pull request Keep commits small and focused. Write clear commit messages.