coolify/CONTRIBUTING.md

Contributing to Coolify

"First, thanks for considering contributing to my project. It really means a lot!" - @andrasbacsai

You can ask for guidance anytime on our Discord server in the #contribute channel.

To understand the tech stack, please refer to the Tech Stack document.

Table of Contents

1. Setup Development Environment
2. Verify Installation
3. Fork and Setup Local Repository
4. Set up Environment Variables
5. Start Coolify
6. Start Development
7. Create a Pull Request
8. Development Notes
9. Resetting Development Environment
10. Additional Contribution Guidelines

1. Setup Development Environment

Follow the steps below for your operating system:

Windows

1. Install docker-ce, Docker Desktop (or similar):

   • Docker CE (recommended):
     • Install Windows Subsystem for Linux v2 (WSL2) by following this guide: Install WSL
     • After installing WSL2, install Docker CE for your Linux distribution by following this guide: Install Docker Engine
     • Make sure to choose the appropriate Linux distribution (e.g., Ubuntu) when following the Docker installation guide
   • Install Docker Desktop (easier):
     • Download and install Docker Desktop for Windows
     • Ensure WSL2 backend is enabled in Docker Desktop settings

2. Install Spin:

   • Follow the instructions to install Spin on Windows from the Spin documentation

MacOS

1. Install Orbstack, Docker Desktop (or similar):

   • Orbstack (recommended, as it is a faster and lighter alternative to Docker Desktop):
     • Download and install Orbstack
   • Docker Desktop:
     • Download and install Docker Desktop for Mac

2. Install Spin:

   • Follow the instructions to install Spin on MacOS from the Spin documentation

Linux

1. Install Docker Engine, Docker Desktop (or similar):

   • Docker Engine (recommended, as there is no VM overhead):
     • Follow the official Docker Engine installation guide for your Linux distribution
   • Docker Desktop:
     • If you want a GUI, you can use Docker Desktop for Linux

2. Install Spin:

   • Follow the instructions to install Spin on Linux from the Spin documentation

2. Verify Installation (Optional)

After installing Docker (or Orbstack) and Spin, verify the installation:

1. Open a terminal or command prompt
2. Run the following commands:

   docker --version
   spin --version
   

   You should see version information for both Docker and Spin.

3. Fork and Setup Local Repository

1. Fork the Coolify repository to your GitHub account.

2. Install a code editor on your machine (choose one):

   Editor	Platform	Download Link
   Visual Studio Code (recommended free)	Windows/macOS/Linux	Download
   Cursor (recommended but paid)	Windows/macOS/Linux	Download
   Zed (very fast)	macOS/Linux	Download

3. Clone the Coolify Repository from your fork to your local machine

   • Use git clone in the command line, or
   • Use GitHub Desktop (recommended):
     • Download and install from https://desktop.github.com/
     • Open GitHub Desktop and login with your GitHub account
     • Click on File -> Clone Repository select github.com as the repository location, then select your forked Coolify repository, choose the local path and then click Clone

4. Open the cloned Coolify Repository in your chosen code editor.

4. Set up Environment Variables

1. In the Code Editor, locate the .env.development.example file in the root directory of your local Coolify repository.
2. Duplicate the .env.development.example file and rename the copy to .env.
3. Open the new .env file and review its contents. Adjust any environment variables as needed for your development setup.
4. If you encounter errors during database migrations, update the database connection settings in your .env file. Use the IP address or hostname of your PostgreSQL database container. You can find this information by running docker ps after executing spin up.
5. Save the changes to your .env file.

5. Start Coolify

1. Open a terminal in the local Coolify directory.
2. Run the following command in the terminal (leave that terminal open):

   spin up
   

Note

You may see some errors, but don't worry; this is expected.

3. If you encounter permission errors, especially on macOS, use:

   sudo spin up
   

Note

If you change environment variables afterwards or anything seems broken, press Ctrl + C to stop the process and run spin up again.

6. Start Development

1. Access your Coolify instance:

   • URL: http://localhost:8000
   • Login: test@example.com
   • Password: password

2. Additional development tools:

   Tool	URL	Note
   Laravel Horizon (scheduler)	http://localhost:8000/horizon	Only accessible when logged in as root user
   Mailpit (email catcher)	http://localhost:8025
   Telescope (debugging tool)	http://localhost:8000/telescope	Disabled by default

Note

To enable Telescope, add the following to your .env file:

TELESCOPE_ENABLED=true

7. Create a Pull Request

Important

Please read the Pull Request Guidelines carefully before creating your PR.

1. After making changes or adding a new service:

   • Commit your changes to your forked repository.
   • Push the changes to your GitHub account.

2. Creating the Pull Request (PR):

   • Navigate to the main Coolify repository on GitHub.
   • Click the "Pull requests" tab.
   • Click the green "New pull request" button.
   • Choose your fork and next branch as the compare branch.
   • Click "Create pull request".

3. Filling out the PR details:

   • Give your PR a descriptive title.
   • Use the Pull Request Template provided and fill in the details.

Important

Always set the base branch for your PR to the next branch of the Coolify repository, not the v4.x branch.

4. Submit your PR:
   • Review your changes one last time.
   • Click "Create pull request" to submit.

Note

Make sure your PR is out of draft mode as soon as it's ready for review. PRs that are in draft mode for a long time may be closed by maintainers.

After submission, maintainers will review your PR and may request changes or provide feedback.

Pull Request Guidelines

To maintain high-quality contributions and efficient review process:

• Target Branch: Always target the next branch, never v4.x or any other branch. PRs targeting incorrect branches will be closed without review.
• Descriptive Titles: Use clear, concise PR titles that describe the change (e.g., "fix: one click postgresql database stuck in restart loop" instead of "Fix database").
• PR Descriptions: Provide detailed, meaningful descriptions. Avoid generic or AI-generated fluff. Include:
  • What the change does
  • Why it's needed
  • How to test it
  • Any breaking changes
  • Screenshot or video recording of your changes working without any issues
  • Links to related issues
• Link to Issues: All PRs must link to an existing GitHub issue. If no issue exists, create one first. Unrelated PRs may be closed.
• Single Responsibility: Each PR should address one issue or feature. Do not bundle unrelated changes.
• Draft Mode: Use draft PRs for work-in-progress. Convert to ready-for-review only when complete and tested.
• Review Readiness: Ensure your PR is ready for review within a reasonable timeframe (max 7 days in draft). Stale drafts may be closed.
• Current Focus: We are currently prioritizing stability and bug fixes over new features. PRs adding new features may not be reviewed, or may be closed without review to maintain focus.
• Language Translations: Coolify currently supports only English. Pull requests for new language translations will not be accepted. Multi-language support may be considered in the next major version (v5).
• AI Usage Policy: We are not against AI tools—we use them ourselves. However, AI discourse is mandatory: You must fully understand the changes in your PR and be able to explain them clearly. Many PRs using AI lack this understanding, leading to untested or incorrect submissions. If you use AI, ensure you can articulate what the code does, why it was changed, and how it was tested.

Review Process

• Response Time: Maintainers will review PRs promptly, but complex changes may take time. Be patient and responsive to feedback.
• Revisions: Address all review comments. Unresolved feedback may lead to PR closure.
• Merge Criteria: PRs are merged only after:
  • All tests pass (including CI)
  • Code review approval
• Closing PRs: PRs may be closed for:
  • Inactivity (>7 days without response)
  • Failure to meet guidelines
  • Duplicate or superseded work
  • Security or quality concerns

Code Quality, Testing, and Bounty Submissions

All contributions must adhere to the highest standards of code quality and testing:

• Testing Required: Every PR must include steps to test your changes. Untested code will not be reviewed or merged.
• Local Verification: Ensure your changes work in the development environment. Test all affected features thoroughly.
• Code Standards: Follow the existing code style, conventions, and patterns in the codebase.
• No AI-Generated Code: Do not submit code generated by AI tools without fully understanding and verifying it. AI-generated submissions that are untested or incorrect will be rejected immediately.

For PRs that claim bounties:

• Eligibility: Bounty PRs must strictly follow all guidelines above. Untested, poorly described, or non-compliant PRs will not qualify for bounty rewards.
• Original Work: Bounties are for genuine contributions. Submitting AI-generated or copied code solely for bounty claims will result in disqualification and potential removal from contributing.
• Quality Standards: Bounty submissions are held to even higher standards. Ensure comprehensive testing, clear documentation, and alignment with project goals. When maintainers review the changes, they should work as expected (the things mentioned in the PR description plus what the bounty issuer needs).
• Claim Process: Only successfully merged PRs that pass all reviews (core maintainers + bounty issuer) and meet bounty criteria will be awarded. Follow the issue's bounty guidelines precisely.
• Prioritization: Contributor PRs are prioritized over first-time or new contributors.
• Developer Experience: We highly advise beginners to avoid participating in bug bounties for our codebase. Most of the time, they don't know what they are changing, how it affects other parts of the system, or if their changes are even correct.
• Review Comments: When maintainers ask questions, you should be able to respond properly without generic or AI-generated fluff.

Development Notes

When working on Coolify, keep the following in mind:

1. Database Migrations: After switching branches or making changes to the database structure, always run migrations:

   docker exec -it coolify php artisan migrate
   

2. Resetting Development Setup: To reset your development setup to a clean database with default values:

   docker exec -it coolify php artisan migrate:fresh --seed
   

3. Troubleshooting: If you encounter unexpected behavior, ensure your database is up-to-date with the latest migrations and if possible reset the development setup to eliminate any environment-specific issues.

Important

Forgetting to migrate the database can cause problems, so make it a habit to run migrations after pulling changes or switching branches.

Resetting Development Environment

If you encounter issues or break your database or something else, follow these steps to start from a clean slate (works since v4.0.0-beta.342):

1. Stop all running containers ctrl + c.

2. Remove all Coolify containers:

   docker rm coolify coolify-db coolify-redis coolify-realtime coolify-testing-host coolify-minio coolify-vite-1 coolify-mail
   

3. Remove Coolify volumes (it is possible that the volumes have no coolify prefix on your machine, in that case remove the prefix from the command):

   docker volume rm coolify_dev_backups_data coolify_dev_postgres_data coolify_dev_redis_data coolify_dev_coolify_data coolify_dev_minio_data
   

4. Remove unused images:

   docker image prune -a
   

5. Start Coolify again:

   spin up
   

6. Run database migrations and seeders:

   docker exec -it coolify php artisan migrate:fresh --seed
   

After completing these steps, you'll have a fresh development setup.

Important

Always run database migrations and seeders after switching branches or pulling updates to ensure your local database structure matches the current codebase and includes necessary seed data.

Additional Contribution Guidelines

Contributing a New Service

To add a new service to Coolify, please refer to our documentation: Adding a New Service

Contributing to Documentation

To contribute to the Coolify documentation, please refer to this guide: Contributing to the Coolify Documentation