ContextQMD
Back to Coolify

Contributing to Coolify

DEVELOPMENT.md

4.2.09.0 KB
Original Source

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:

<details> <summary><strong>Windows</strong></summary>

  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):

  2. Install Spin:

</details> <details> <summary><strong>MacOS</strong></summary>

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

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

  2. Install Spin:

</details> <details> <summary><strong>Linux</strong></summary>

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

  2. Install Spin:

</details>

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:
    bash
    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):

    EditorPlatformDownload Link
    Visual Studio Code (recommended free)Windows/macOS/LinuxDownload
    Cursor (recommended but paid)Windows/macOS/LinuxDownload
    Zed (very fast)Windows/macOS/LinuxDownload

  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):
    bash
    spin up

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

  1. If you encounter permission errors, especially on macOS, use:
    bash
    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:

  2. Additional development tools:

    ToolURLNote
    Laravel Horizon (scheduler)http://localhost:8000/horizonOnly accessible when logged in as root user
    Mailpit (email catcher)http://localhost:8025
    Telescope (debugging tool)http://localhost:8000/telescopeDisabled by default

[!NOTE] To enable Telescope, add the following to your .env file:

env
TELESCOPE_ENABLED=true

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:

    bash
    docker exec -it coolify php artisan migrate

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

    bash
    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:

    bash
    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):

    bash
    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:

    bash
    docker image prune -a

  5. Start Coolify again:

    bash
    spin up

  6. Run database migrations and seeders:

    bash
    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 Development Guidelines

Adding a New Service

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

Development for Documentation

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