86f6cd5fd6
- Introduced multiple new markdown files covering API and routing, application architecture, deployment architecture, database patterns, frontend patterns, and security practices. - Established guidelines for development workflows, testing strategies, and continuous improvement of rules. - Enhanced project overview and technology stack documentation to provide clarity on Coolify's features and architecture.
293 lines
8.6 KiB
Plaintext
293 lines
8.6 KiB
Plaintext
---
|
|
description:
|
|
globs:
|
|
alwaysApply: false
|
|
---
|
|
# Coolify Cursor Rules - Complete Guide
|
|
|
|
## Overview
|
|
|
|
This comprehensive set of Cursor Rules provides deep insights into **Coolify**, an open-source self-hostable alternative to Heroku/Netlify/Vercel. These rules will help you understand, navigate, and contribute to this complex Laravel-based deployment platform.
|
|
|
|
## Rule Categories
|
|
|
|
### 🏗️ Architecture & Foundation
|
|
- **[project-overview.mdc](mdc:.cursor/rules/project-overview.mdc)** - What Coolify is and its core mission
|
|
- **[technology-stack.mdc](mdc:.cursor/rules/technology-stack.mdc)** - Complete technology stack and dependencies
|
|
- **[application-architecture.mdc](mdc:.cursor/rules/application-architecture.mdc)** - Laravel application structure and patterns
|
|
|
|
### 🎨 Frontend Development
|
|
- **[frontend-patterns.mdc](mdc:.cursor/rules/frontend-patterns.mdc)** - Livewire + Alpine.js + Tailwind architecture
|
|
|
|
### 🗄️ Data & Backend
|
|
- **[database-patterns.mdc](mdc:.cursor/rules/database-patterns.mdc)** - Database architecture, models, and data management
|
|
- **[deployment-architecture.mdc](mdc:.cursor/rules/deployment-architecture.mdc)** - Docker orchestration and deployment workflows
|
|
|
|
### 🌐 API & Communication
|
|
- **[api-and-routing.mdc](mdc:.cursor/rules/api-and-routing.mdc)** - RESTful APIs, webhooks, and routing patterns
|
|
|
|
### 🧪 Quality Assurance
|
|
- **[testing-patterns.mdc](mdc:.cursor/rules/testing-patterns.mdc)** - Testing strategies with Pest PHP and Laravel Dusk
|
|
|
|
### 🔧 Development Process
|
|
- **[development-workflow.mdc](mdc:.cursor/rules/development-workflow.mdc)** - Development setup, coding standards, and contribution guidelines
|
|
|
|
### 🔒 Security
|
|
- **[security-patterns.mdc](mdc:.cursor/rules/security-patterns.mdc)** - Security architecture, authentication, and best practices
|
|
|
|
## Quick Navigation
|
|
|
|
### Core Application Files
|
|
- **[app/Models/Application.php](mdc:app/Models/Application.php)** - Main application entity (74KB, highly complex)
|
|
- **[app/Models/Server.php](mdc:app/Models/Server.php)** - Server management (46KB, complex)
|
|
- **[app/Models/Service.php](mdc:app/Models/Service.php)** - Service definitions (58KB, complex)
|
|
- **[app/Models/Team.php](mdc:app/Models/Team.php)** - Multi-tenant structure (8.9KB)
|
|
|
|
### Configuration Files
|
|
- **[composer.json](mdc:composer.json)** - PHP dependencies and Laravel setup
|
|
- **[package.json](mdc:package.json)** - Frontend dependencies and build scripts
|
|
- **[vite.config.js](mdc:vite.config.js)** - Frontend build configuration
|
|
- **[docker-compose.dev.yml](mdc:docker-compose.dev.yml)** - Development environment
|
|
|
|
### API Documentation
|
|
- **[openapi.json](mdc:openapi.json)** - Complete API documentation (373KB)
|
|
- **[routes/api.php](mdc:routes/api.php)** - API endpoint definitions (13KB)
|
|
- **[routes/web.php](mdc:routes/web.php)** - Web application routes (21KB)
|
|
|
|
## Key Concepts to Understand
|
|
|
|
### 1. Multi-Tenant Architecture
|
|
Coolify uses a **team-based multi-tenancy** model where:
|
|
- Users belong to multiple teams
|
|
- Resources are scoped to teams
|
|
- Access control is team-based
|
|
- Data isolation is enforced at the database level
|
|
|
|
### 2. Deployment Philosophy
|
|
- **Docker-first** approach for all deployments
|
|
- **Zero-downtime** deployments with health checks
|
|
- **Git-based** workflows with webhook integration
|
|
- **Multi-server** support with SSH connections
|
|
|
|
### 3. Technology Stack
|
|
- **Backend**: Laravel 11 + PHP 8.4
|
|
- **Frontend**: Livewire 3.5 + Alpine.js + Tailwind CSS 4.1
|
|
- **Database**: PostgreSQL 15 + Redis 7
|
|
- **Containerization**: Docker + Docker Compose
|
|
- **Testing**: Pest PHP 3.8 + Laravel Dusk
|
|
|
|
### 4. Security Model
|
|
- **Defense-in-depth** security architecture
|
|
- **OAuth integration** with multiple providers
|
|
- **API token** authentication with Sanctum
|
|
- **Encrypted storage** for sensitive data
|
|
- **SSH key** management for server access
|
|
|
|
## Development Quick Start
|
|
|
|
### Local Setup
|
|
```bash
|
|
# Clone and setup
|
|
git clone https://github.com/coollabsio/coolify.git
|
|
cd coolify
|
|
cp .env.example .env
|
|
|
|
# Docker development (recommended)
|
|
docker-compose -f docker-compose.dev.yml up -d
|
|
docker-compose exec app composer install
|
|
docker-compose exec app npm install
|
|
docker-compose exec app php artisan migrate
|
|
```
|
|
|
|
### Code Quality
|
|
```bash
|
|
# PHP code style
|
|
./vendor/bin/pint
|
|
|
|
# Static analysis
|
|
./vendor/bin/phpstan analyse
|
|
|
|
# Run tests
|
|
./vendor/bin/pest
|
|
```
|
|
|
|
## Common Patterns
|
|
|
|
### Livewire Components
|
|
```php
|
|
class ApplicationShow extends Component
|
|
{
|
|
public Application $application;
|
|
|
|
protected $listeners = [
|
|
'deployment.started' => 'refresh',
|
|
'deployment.completed' => 'refresh',
|
|
];
|
|
|
|
public function deploy(): void
|
|
{
|
|
$this->authorize('deploy', $this->application);
|
|
app(ApplicationDeploymentService::class)->deploy($this->application);
|
|
}
|
|
}
|
|
```
|
|
|
|
### API Controllers
|
|
```php
|
|
class ApplicationController extends Controller
|
|
{
|
|
public function __construct()
|
|
{
|
|
$this->middleware('auth:sanctum');
|
|
$this->middleware('team.access');
|
|
}
|
|
|
|
public function deploy(Application $application): JsonResponse
|
|
{
|
|
$this->authorize('deploy', $application);
|
|
$deployment = app(ApplicationDeploymentService::class)->deploy($application);
|
|
return response()->json(['deployment_id' => $deployment->id]);
|
|
}
|
|
}
|
|
```
|
|
|
|
### Queue Jobs
|
|
```php
|
|
class DeployApplicationJob implements ShouldQueue
|
|
{
|
|
public function handle(DockerService $dockerService): void
|
|
{
|
|
$this->deployment->update(['status' => 'running']);
|
|
|
|
try {
|
|
$dockerService->deployContainer($this->deployment->application);
|
|
$this->deployment->update(['status' => 'success']);
|
|
} catch (Exception $e) {
|
|
$this->deployment->update(['status' => 'failed']);
|
|
throw $e;
|
|
}
|
|
}
|
|
}
|
|
```
|
|
|
|
## Testing Patterns
|
|
|
|
### Feature Tests
|
|
```php
|
|
test('user can deploy application via API', function () {
|
|
$user = User::factory()->create();
|
|
$application = Application::factory()->create(['team_id' => $user->currentTeam->id]);
|
|
|
|
$response = $this->actingAs($user)
|
|
->postJson("/api/v1/applications/{$application->id}/deploy");
|
|
|
|
$response->assertStatus(200);
|
|
expect($application->deployments()->count())->toBe(1);
|
|
});
|
|
```
|
|
|
|
### Browser Tests
|
|
```php
|
|
test('user can create application through UI', function () {
|
|
$user = User::factory()->create();
|
|
|
|
$this->browse(function (Browser $browser) use ($user) {
|
|
$browser->loginAs($user)
|
|
->visit('/applications/create')
|
|
->type('name', 'Test App')
|
|
->press('Create Application')
|
|
->assertSee('Application created successfully');
|
|
});
|
|
});
|
|
```
|
|
|
|
## Security Considerations
|
|
|
|
### Authentication
|
|
- Multi-provider OAuth support
|
|
- API token authentication
|
|
- Team-based access control
|
|
- Session management
|
|
|
|
### Data Protection
|
|
- Encrypted environment variables
|
|
- Secure SSH key storage
|
|
- Input validation and sanitization
|
|
- SQL injection prevention
|
|
|
|
### Container Security
|
|
- Non-root container users
|
|
- Minimal capabilities
|
|
- Read-only filesystems
|
|
- Network isolation
|
|
|
|
## Performance Optimization
|
|
|
|
### Database
|
|
- Eager loading relationships
|
|
- Query optimization
|
|
- Connection pooling
|
|
- Caching strategies
|
|
|
|
### Frontend
|
|
- Lazy loading components
|
|
- Asset optimization
|
|
- CDN integration
|
|
- Real-time updates via WebSockets
|
|
|
|
## Contributing Guidelines
|
|
|
|
### Code Standards
|
|
- PSR-12 PHP coding standards
|
|
- Laravel best practices
|
|
- Comprehensive test coverage
|
|
- Security-first approach
|
|
|
|
### Pull Request Process
|
|
1. Fork repository
|
|
2. Create feature branch
|
|
3. Implement with tests
|
|
4. Run quality checks
|
|
5. Submit PR with clear description
|
|
|
|
## Useful Commands
|
|
|
|
### Development
|
|
```bash
|
|
# Start development environment
|
|
docker-compose -f docker-compose.dev.yml up -d
|
|
|
|
# Run tests
|
|
./vendor/bin/pest
|
|
|
|
# Code formatting
|
|
./vendor/bin/pint
|
|
|
|
# Frontend development
|
|
npm run dev
|
|
```
|
|
|
|
### Production
|
|
```bash
|
|
# Install Coolify
|
|
curl -fsSL https://cdn.coollabs.io/coolify/install.sh | bash
|
|
|
|
# Update Coolify
|
|
./scripts/upgrade.sh
|
|
```
|
|
|
|
## Resources
|
|
|
|
### Documentation
|
|
- **[README.md](mdc:README.md)** - Project overview and installation
|
|
- **[CONTRIBUTING.md](mdc:CONTRIBUTING.md)** - Contribution guidelines
|
|
- **[CHANGELOG.md](mdc:CHANGELOG.md)** - Release history
|
|
- **[TECH_STACK.md](mdc:TECH_STACK.md)** - Technology overview
|
|
|
|
### Configuration
|
|
- **[config/](mdc:config)** - Laravel configuration files
|
|
- **[database/migrations/](mdc:database/migrations)** - Database schema
|
|
- **[tests/](mdc:tests)** - Test suite
|
|
|
|
This comprehensive rule set provides everything needed to understand, develop, and contribute to the Coolify project effectively. Each rule focuses on specific aspects while maintaining connections to the broader architecture.
|