Project

Contributing

How to contribute to the FlatRun project.

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.

Resources

Agent Repository Go backend source UI Repository Vue.js frontend source
Star us on GitHub