Contributing

FlatRun is an open-source project and we welcome contributions! Whether you're fixing bugs, adding features, improving documentation, or helping with testing, your contributions are valuable.

Getting Started

Prerequisites

• Go 1.21+ (for the agent)
• Node.js 18+ (for the UI and website)
• Docker and Docker Compose
• Git

Setting Up Development Environment

Agent (Go)

git clone https://github.com/flatrun/agent.git
cd agent

# Install dependencies
go mod download

# Run tests
go test ./...

# Build
go build -o flatrun-agent ./cmd/agent

# Run locally
./flatrun-agent --config config.example.yml

UI (Vue.js)

git clone https://github.com/flatrun/ui.git
cd ui

# Install dependencies
npm install

# Run development server
npm run dev

# Run tests
npm test

# Build for production
npm run build

Website (Astro)

git clone https://github.com/flatrun/website.git
cd website

# Install dependencies
npm install

# Run development server
npm run dev

# Build for production
npm run build

How to Contribute

Reporting Issues

Found a bug or have a feature request?

1. Check existing issues to avoid duplicates
2. Create a new issue with a clear title and description
3. Include steps to reproduce (for bugs)
4. Add relevant logs, screenshots, or code samples

Pull Requests

1. Fork the repository
2. Create a feature branch: git checkout -b feature/my-feature
3. Make your changes
4. Write/update tests as needed
5. Run tests and linting
6. Commit with clear messages
7. Push to your fork
8. Open a Pull Request

Commit Messages

Use conventional commit format:

feat: add new template for Django
fix: resolve SSL certificate renewal issue
docs: update installation guide
refactor: simplify deployment manager
test: add integration tests for proxy

Code Style

Go (Agent)

• Follow standard Go conventions
• Run go fmt before committing
• Run go vet to catch common issues
• Use golangci-lint for comprehensive linting

TypeScript/Vue (UI)

• Follow existing code style
• Run npm run lint before committing
• Run npm run format for Prettier formatting
• Use TypeScript strictly (no any where avoidable)

Areas to Contribute

Good First Issues

Look for issues labeled good first issue on GitHub. These are typically:

• Documentation improvements
• Small bug fixes
• Test coverage improvements
• Minor UI enhancements

Feature Development

Major areas where contributions are welcome:

• New Templates — Add templates for popular applications
• Database Support — Improve database management features
• Monitoring — Enhanced stats and alerting
• UI Improvements — Better UX, accessibility, mobile support
• Documentation — Guides, tutorials, API docs

Testing

• Unit tests for new functionality
• Integration tests
• End-to-end tests
• Manual testing on different platforms

Project Structure

Agent Repository

agent/
├── cmd/agent/          # Entry point
├── internal/           # Internal packages
│   ├── api/           # REST API handlers
│   ├── auth/          # Authentication
│   ├── docker/        # Docker management
│   ├── proxy/         # Nginx orchestration
│   └── ...
├── pkg/               # Public packages
│   ├── config/        # Configuration
│   ├── models/        # Data models
│   └── ...
├── templates/         # Embedded templates
└── test/              # Test fixtures

UI Repository

ui/
├── src/
│   ├── components/    # Vue components
│   ├── pages/         # Page views
│   ├── stores/        # Pinia stores
│   ├── services/      # API services
│   └── types/         # TypeScript types
└── tests/             # Tests

Getting Help

• Open a GitHub Discussion for questions
• Check existing issues and PRs
• Read through the codebase documentation

License

FlatRun is licensed under the MIT License. By contributing, you agree that your contributions will be licensed under the same license.