An open-source, self-hostable PaaS alternative to Vercel, Heroku & Netlify that lets you easily deploy static sites, databases, full-stack applications and 360+ one-click services on your own servers.
PHP coolifydatabasesdeploymentdockerdocker-composeinertiajslaravelmariadbmysqlnextjsnodejsphppostgresredisself-hostedself-hostingserverstatic-sitesveltesvelte5
chore(repo): improve development guide
ShadowArcanist4776a572317c
diff --git a/DEVELOPMENT.md b/DEVELOPMENT.mdnew file mode 100644index 0000000000..69f2dc7606--- /dev/null+++ b/DEVELOPMENT.md@@ -0,0 +1,212 @@+# Contributing to Coolify+> "First, thanks for considering contributing to my project. It really means a lot!" - [@andrasbacsai](https://github.com/andrasbacsai)++You can ask for guidance anytime on our [Discord server](https://coollabs.io/discord) in the `#contribute` channel.++To understand the tech stack, please refer to the [Tech Stack](TECH_STACK.md) document.+++## Table of Contents+1. [Setup Development Environment](#1-setup-development-environment)+2. [Verify Installation](#2-verify-installation-optional)+3. [Fork and Setup Local Repository](#3-fork-and-setup-local-repository)+4. [Set up Environment Variables](#4-set-up-environment-variables)+5. [Start Coolify](#5-start-coolify)+6. [Start Development](#6-start-development)+7. [Create a Pull Request](#7-create-a-pull-request)+8. [Development Notes](#development-notes)+9. [Resetting Development Environment](#resetting-development-environment)+10. [Additional Contribution Guidelines](#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](https://learn.microsoft.com/en-us/windows/wsl/install?ref=coolify)+ - After installing WSL2, install Docker CE for your Linux distribution by following this guide: [Install Docker Engine](https://docs.docker.com/engine/install/?ref=coolify)+ - 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](https://docs.docker.com/desktop/install/windows-install/?ref=coolify)+ - Ensure WSL2 backend is enabled in Docker Desktop settings++2. Install Spin:+ - Follow the instructions to install Spin on Windows from the [Spin documentation](https://serversideup.net/open-source/spin/docs/installation/install-windows#download-and-install-spin-into-wsl2?ref=coolify)++</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):+ - Download and install [Orbstack](https://docs.orbstack.dev/quick-start#installation?ref=coolify)+ - Docker Desktop:+ - Download and install [Docker Desktop for Mac](https://docs.docker.com/desktop/install/mac-install/?ref=coolify)++2. Install Spin:+ - Follow the instructions to install Spin on MacOS from the [Spin documentation](https://serversideup.net/open-source/spin/docs/installation/install-macos/#download-and-install-spin?ref=coolify)++</details>++<details>+<summary><strong>Linux</strong></summary>++1. Install Docker Engine, Docker Desktop (or similar):+ - Docker Engine (recommended, as there is no VM overhead):+ - Follow the official [Docker Engine installation guide](https://docs.docker.com/engine/install/?ref=coolify) for your Linux distribution+ - Docker Desktop:+ - If you want a GUI, you can use [Docker Desktop for Linux](https://docs.docker.com/desktop/install/linux-install/?ref=coolify)++2. Install Spin:+ - Follow the instructions to install Spin on Linux from the [Spin documentation](https://serversideup.net/open-source/spin/docs/installation/install-linux#configure-docker-permissions?ref=coolify)++</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](https://github.com/coollabsio/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](https://code.visualstudio.com/download?ref=coolify) |+ | Cursor (recommended but paid) | Windows/macOS/Linux | [Download](https://www.cursor.com/?ref=coolify) |+ | Zed (very fast) | Windows/macOS/Linux | [Download](https://zed.dev/download?ref=coolify) |++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/](https://desktop.github.com/?ref=coolify)+ - 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.++3. 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:+ - URL: `http://localhost:8000`+ - Login: `[email protected]`+ - 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:+> ```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](https://coolify.io/docs/get-started/contribute/service)++### Development for Documentation+To contribute to the Coolify documentation, please refer to this guide: [Contributing to the Coolify Documentation](https://coolify.io/docs/get-started/contribute/documentation)\ No newline at end of file