377 lines
7.9 KiB
Markdown
377 lines
7.9 KiB
Markdown
# 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 <your-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 <PID>
|
|
```
|
|
|
|
---
|
|
|
|
## 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.
|