From 555b46a7d84d22a0f9ff0f30f22d3797ff8b3171 Mon Sep 17 00:00:00 2001
From: ShadowArcanist <162910371+ShadowArcanist@users.noreply.github.com>
Date: Tue, 24 Feb 2026 00:45:33 +0530
Subject: [PATCH 01/30] chore(repo): improve contributor guidelines
---
CONTRIBUTING.md | 463 +++++++++++++++++++++---------------------------
1 file changed, 205 insertions(+), 258 deletions(-)
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
index 9aec08420..af8c7503c 100644
--- a/CONTRIBUTING.md
+++ b/CONTRIBUTING.md
@@ -1,298 +1,245 @@
# Contributing to Coolify
+We’re happy that you’re interested in contributing to Coolify!
-> "First, thanks for considering contributing to my project. It really means a lot!" - [@andrasbacsai](https://github.com/andrasbacsai)
+There are many ways to help:
+- Answer questions in GitHub Discussions or Discord
+- Report reproducible bugs
+- Submit pull requests to fix issues
+- Add new one-click services
+- Improve documentation
-You can ask for guidance anytime on our [Discord server](https://coollabs.io/discord) in the `#contribute` channel.
+Coolify is a PaaS used by 400,000+ people worldwide and maintained by two active maintainers. Contributions are welcome — but **alignment matters more than quantity**.
-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:
-
-
-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](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)
-
-
-
-
-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](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)
-
-
-
-
-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](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)
-
-
-
-## 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) | 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: `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:
-> ```env
-> TELESCOPE_ENABLED=true
-> ```
-
-## 7. Create a Pull Request
+This guide explains **what kind of contributions are likely to be accepted** and how to submit them properly. Following it saves time for both you and the maintainers.
> [!IMPORTANT]
-> Please read the [Pull Request Guidelines](#pull-request-guidelines) carefully before creating your PR.
+> These guidelines may feel stricter than in many open-source projects. That is intentional.
+> Clear structure and boundaries prevent maintainer burnout and keep the project sustainable long-term.
-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".
+## High-Level Expectations
+- Coolify has a clear product direction.
+- Ownership and decisions are centralized.
+- Review capacity is limited.
+- Not every contribution will be accepted — even if technically correct.
-3. Filling out the PR details:
- - Give your PR a descriptive title.
- - Use the Pull Request Template provided and fill in the details.
+This is normal for a two-maintainer project.
-> [!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.
+## State of the Project
+Coolify is currently at v4 and is still in beta. While v4 is stable, it has some limitations, including:
+- Limited scaling support
+- A more complex user experience
+- Other smaller issues that need refinement
-> [!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.
+These limitations will be addressed in Coolify v5, which is in the planning stage. However, the maintainers are focused on releasing a stable v4 version before dedicating time to v5 development. Because of this, major features, architectural changes, or significant UI changes will not be accepted for v4 at this stage.
-After submission, maintainers will review your PR and may request changes or provide feedback.
+We welcome contributions that help stabilize v4, but larger changes will be saved for v5 once we have a stable v4 release.
-#### 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
+## What Makes a Strong Contribution
+The following types of contributions are most likely to be accepted:
-#### Code Quality, Testing, and Bounty Submissions
-All contributions must adhere to the highest standards of code quality and testing:
+- **Bug fixes** (with clear reproduction steps)
+- **Documentation improvements** (typos, clarifications, examples, guides)
+- **Features discussed and aligned beforehand**
+- **New service templates** requested by the community
+- **Small, focused pull requests**
-- **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.
+If your change is small and obvious (typo fix, small bug, minor docs update), you may open a pull request directly.
-**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.
+## Keep Changes Focused
+Only modify what is necessary to achieve your goal.
-## Development Notes
+If you are fixing a bug in `file.yaml`, do not:
+- Reformat unrelated files
+- Refactor unrelated code
+- Fix style issues elsewhere
+- Combine multiple unrelated changes
-When working on Coolify, keep the following in mind:
+Even “improvements” increase review complexity.
-1. **Database Migrations**: After switching branches or making changes to the database structure, always run migrations:
- ```bash
- docker exec -it coolify php artisan migrate
- ```
+**One pull request = one logical change.**
-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
- ```
+If you want to refactor or clean up code, discuss it first and submit it separately.
-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.
+## Discussion Is Required for Larger Changes
+For anything beyond a small fix, you must discuss it before opening a pull request.
-## Resetting Development Environment
+This includes:
+- New features
+- UI/UX changes
+- Changes to default behavior
+- Refactors or cleanup work
+- Performance rewrites
+- Architectural changes
+- Changes touching many files
-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`):
+Discussion happens in GitHub Discussions: https://github.com/coollabsio/coolify/discussions/categories/general
-1. Stop all running containers `ctrl + c`.
+Pull requests introducing major changes without prior discussion will be closed without review.
-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
- ```
+This ensures alignment before significant work is done.
-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
- ```
+## What This Project Is Not
+To set clear expectations:
+- Coolify is not optimized for first-time open-source contributors
+- We do not provide beginner-focused mentorship issues
+- Large unsolicited changes are unlikely to be accepted
+- Broad refactors or style rewrites are not helpful
+- Low-effort AI-generated pull requests will be closed
-5. Start Coolify again:
- ```bash
- spin up
- ```
+AI usage is allowed. However, contributors must fully understand what their changes do and why.
-6. Run database migrations and seeders:
- ```bash
- docker exec -it coolify php artisan migrate:fresh --seed
- ```
+Clear expectations help everyone use their time effectively.
-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.
+# Ways to Contribute
+## 1. Support Contributions
+We use Discord for most support requests and GitHub Discussions for help.
-## Additional Contribution Guidelines
+### Requesting Support
+If you need help:
+- Provide complete and detailed information
+- Include logs, screenshots, and steps to reproduce
+- Be respectful — support is voluntary
-### Contributing a New Service
+Do not ping people for attention. They respond when available.
-To add a new service to Coolify, please refer to our documentation:
-[Adding a New Service](https://coolify.io/docs/get-started/contribute/service)
+### Providing Support
+If you help others:
+- Verify your information before sharing
+- Be patient and respectful
+- Remember that not everyone has the same experience level
-### Contributing to Documentation
-To contribute to the Coolify documentation, please refer to this guide:
-[Contributing to the Coolify Documentation](https://github.com/coollabsio/documentation-coolify/blob/main/readme.md)
+## 2. Bug Report Contributions
+Create a GitHub issue **only** if:
+- The bug is reproducible
+- You have confirmed no existing issue already covers it
+
+For questions or general help, use GitHub Discussions or the Discord support channel.
+
+Bug reports must include:
+- Clear reproduction steps
+- Expected result
+- Actual result
+
+Incomplete reports may be closed.
+
+
+## 3. Code Contributions
+Maintainers may close pull requests at their discretion, without explanation.
+
+### Issue Requirement
+Every pull request should reference and close an Issue or Discussion.
+
+If none exists, create one first.
+
+Pull requests without linked issue or discussions may not be reviewed and can be closed at any time.
+
+
+## Commit Message Format
+All commits must start with an action and category:
+- `fix(ui):` — UI-related fixes
+- `feat(api):` — API-related changes
+- `feat(service):` — One-click service changes
+
+Examples:
+- `fix(api): version endpoint returns wrong data`
+- `feat(service): add supabase`
+
+Use the commit description only for concise context.
+
+Walls of text listing every change in description will be rejected.
+
+
+## Pull Request Title Format
+Pull request titles follow the same format:
+- `fix(ui):`
+- `feat(api):`
+- `feat(service):`
+
+Examples:
+- `fix(api): version endpoint returns wrong data`
+- `feat(service): add supabase`
+
+
+## AI Usage Disclosure
+If AI tools were used at any stage, mention it in the pull request description.
+
+AI is allowed.
+
+However:
+- You must understand every change
+- You must verify correctness
+- You must ensure it follows project patterns
+
+AI-generated pull requests without clear understanding will be closed.
+
+
+## Test Before Submitting
+Before submitting a pull request:
+- Test your changes thoroughly
+- Verify they work in a clean environment
+- Provide detailed testing steps in the PR description
+
+If maintainers cannot reproduce working behavior, the PR will be closed without further review.
+
+
+## Submitting a Pull Request
+- GitHub will auto-populate the PR template
+- The contributor agreement must remain intact
+- Pull requests without the contributor agreement will be closed
+- All pull requests must target the `next` branch
+- PRs targeting other branches will be closed without review
+
+
+## Bounty Issues
+Community members may create bounty issues for features or improvements.
+
+Important:
+- Only existing contributors are eligible
+- First-time contributors targeting bounty issues will be automatically closed and maybe excluded from contributing.
+
+This policy exists to prevent spam. We close 30+ bounty-targeted spam PRs per week.
+
+
+## FAQ
+**Q: Should I ask before fixing a typo or a small bug?**
+A: No, small, obvious fixes like typos or narrowly-scoped bug fixes can be submitted as a PR directly.
+
+**Q: I have an idea for a new feature.**
+A: Awesome! Discuss it first in GitHub Discussions or Discord. **Do not** open a PR for new features without prior alignment.
+
+**Q: My PR was closed without detailed feedback.**
+A: This usually means it didn’t align with the project’s direction, required more review bandwidth than available, or targeted major changes not allowed in v4. This is normal for a two-maintainer project.
+
+**Q: Can I work on an open issue?**
+A: Comment on the issue first to confirm it’s still relevant and that no one else is actively working on it. For anything beyond a small fix, discuss your approach before implementing.
+
+**Q: I noticed code that could be cleaned up while working on my change.**
+A: Focus only on your stated goal. Cleanups or refactors should be submitted as separate PRs after discussion.
+
+**Q: Can I use AI to help with my PR?**
+A: Yes, AI-assisted contributions are allowed. But you must fully understand and verify the changes. PRs that appear to be generated by AI without context understanding will be closed.
+
+**Q: Can I work on a bounty issue as a first-time contributor?**
+A: No, bounty issues are reserved for existing contributors. First-time contributors targeting bounty issues will have their PRs closed without review. This prevents spam and ensures bounties go to contributors familiar with the project.
+
+**Q: My PR was closed without review. Can I submit a new one?**
+A: Yes, but keep in mind a PR closure is feedback, not a rejection of your effort. It usually means the PR didn’t match the project goals or guidelines. Address these issues first — repeating the same approach may hurt your standing with maintainers.
+
+
+# Development Guides
+## Local Development
+To build and run Coolify locally, see: [Development](./DEVELOPMENT.md)
+
+## Adding a New Service
+To add a new one-click service, follow: https://coolify.io/docs/get-started/contribute/service
+
+## Contributing to Documentation
+To contribute to documentation, see: https://coolify.io/docs/get-started/contribute/documentation
\ No newline at end of file
From 4776a572317cc1afc362c40a09dcad41b7fecfd8 Mon Sep 17 00:00:00 2001
From: ShadowArcanist <162910371+ShadowArcanist@users.noreply.github.com>
Date: Tue, 24 Feb 2026 00:46:28 +0530
Subject: [PATCH 02/30] chore(repo): improve development guide
---
DEVELOPMENT.md | 212 +++++++++++++++++++++++++++++++++++++++++++++++++
1 file changed, 212 insertions(+)
create mode 100644 DEVELOPMENT.md
diff --git a/DEVELOPMENT.md b/DEVELOPMENT.md
new file mode 100644
index 000000000..69f2dc760
--- /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:
+
+
+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](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)
+
+
+
+
+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](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)
+
+
+
+
+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](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)
+
+
+
+
+## 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: `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:
+> ```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
From 84224d63666a3d66ebc25fb3f79843dcfaff7099 Mon Sep 17 00:00:00 2001
From: ShadowArcanist <162910371+ShadowArcanist@users.noreply.github.com>
Date: Tue, 24 Feb 2026 00:49:45 +0530
Subject: [PATCH 03/30] chore(repo): improve bug report issue template
---
.github/ISSUE_TEMPLATE/01_BUG_REPORT.yml | 22 ++++++++++++++++++++--
1 file changed, 20 insertions(+), 2 deletions(-)
diff --git a/.github/ISSUE_TEMPLATE/01_BUG_REPORT.yml b/.github/ISSUE_TEMPLATE/01_BUG_REPORT.yml
index 42df4785e..b785ba5be 100644
--- a/.github/ISSUE_TEMPLATE/01_BUG_REPORT.yml
+++ b/.github/ISSUE_TEMPLATE/01_BUG_REPORT.yml
@@ -1,7 +1,7 @@
name: 🐞 Bug Report
description: "File a new bug report."
title: "[Bug]: "
-labels: ["🐛 Bug", "🔍 Triage"]
+labels: ["🔍 Triage"]
body:
- type: markdown
attributes:
@@ -14,10 +14,22 @@ body:
- type: textarea
attributes:
- label: Error Message and Logs
+ label: Description and Error Message
description: Provide a detailed description of the error or exception you encountered, along with any relevant log output.
validations:
required: true
+
+ - type: textarea
+ attributes:
+ label: Expected Behavior
+ description: Please describe what you expected to happen instead of the issue. Be as detailed as possible.
+ value: |
+ 1.
+ 2.
+ 3.
+ 4.
+ validations:
+ required: true
- type: textarea
attributes:
@@ -58,6 +70,12 @@ body:
label: Operating System and Version (self-hosted)
description: Run `cat /etc/os-release` or `lsb_release -a` in your terminal and provide the operating system and version.
placeholder: "Ubuntu 22.04"
+
+ - type: textarea
+ attributes:
+ label: Screenshots / Visuals
+ description: If possible, provide screenshots, screen recordings, or diagrams to help illustrate the issue.
+ placeholder: "Attach images or provide links to recordings demonstrating the problem."
- type: textarea
attributes:
From 2b04153dece1a131910bf2fcd4cfeb97f87e4e1f Mon Sep 17 00:00:00 2001
From: ShadowArcanist <162910371+ShadowArcanist@users.noreply.github.com>
Date: Tue, 24 Feb 2026 00:50:46 +0530
Subject: [PATCH 04/30] chore(repo): improve enhancement bounty issue template
---
.../ISSUE_TEMPLATE/02_ENHANCEMENT_BOUNTY.yml | 23 +++++++++++++++++++
1 file changed, 23 insertions(+)
diff --git a/.github/ISSUE_TEMPLATE/02_ENHANCEMENT_BOUNTY.yml b/.github/ISSUE_TEMPLATE/02_ENHANCEMENT_BOUNTY.yml
index ef26125e0..b71f32bd2 100644
--- a/.github/ISSUE_TEMPLATE/02_ENHANCEMENT_BOUNTY.yml
+++ b/.github/ISSUE_TEMPLATE/02_ENHANCEMENT_BOUNTY.yml
@@ -20,6 +20,7 @@ body:
- New Feature
- New Service
- Improvement
+ - Bug Fix
validations:
required: true
@@ -29,3 +30,25 @@ body:
description: Provide a detailed description of the feature, improvement, or service you are proposing.
validations:
required: true
+
+ - type: textarea
+ attributes:
+ label: Requirements / How It Should Work
+ description: Describe in detail how the feature, service, or improvement should function. Include user flow, expected behavior, or technical implementation notes if applicable.
+ value: |
+ 1.
+ 2.
+ 3.
+ validations:
+ required: true
+
+ - type: textarea
+ attributes:
+ label: Criteria to Satisfy Bounty
+ description: Define the conditions that must be met for the PR or contribution to be considered complete and eligible for the bounty. Be specific about functionality, tests, or documentation requirements.
+ value: |
+ 1.
+ 2.
+ 3.
+ validations:
+ required: true
\ No newline at end of file
From fe855cf8d0930d2b0e76994b2ed72634ff8240c8 Mon Sep 17 00:00:00 2001
From: Poul
Date: Mon, 25 May 2026 11:15:08 +0000
Subject: [PATCH 05/30] feat(api): add REST endpoints for destinations
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit
The Destinations section is exposed in the Coolify UI but not via the
REST API. The destination_uuid field is required when creating
applications via create-public-application, but no way to enumerate or
create destinations programmatically existed — this blocks IaC tools
(e.g. an Aspire publisher targeting Coolify).
Adds, scoped to the existing v1 auth:sanctum + ApiAllowed + api.sensitive
group:
GET /api/v1/destinations
GET /api/v1/destinations/{uuid}
DELETE /api/v1/destinations/{uuid}
GET /api/v1/servers/{server_uuid}/destinations
POST /api/v1/servers/{server_uuid}/destinations
The controller uses the existing inline-Validator convention (no Form
Request classes per the API surface's house style), reuses
StandaloneDocker::ownedByCurrentTeamAPI / SwarmDocker::ownedByCurrentTeamAPI
for team scoping (matching ScheduledTasksController etc.), and respects
the `attachedTo()` guard on delete.
No migrations needed — both standalone_dockers and swarm_dockers tables
already carry uuid/name/network/server_id/timestamps.
OpenAPI @OA\ annotations omitted in this commit to keep the diff
minimal; a follow-up can add them in the style of ServersController.
---
.../Api/DestinationsController.php | 105 ++++++++++++++++++
routes/api.php | 8 ++
2 files changed, 113 insertions(+)
create mode 100644 app/Http/Controllers/Api/DestinationsController.php
diff --git a/app/Http/Controllers/Api/DestinationsController.php b/app/Http/Controllers/Api/DestinationsController.php
new file mode 100644
index 000000000..43fb0cba8
--- /dev/null
+++ b/app/Http/Controllers/Api/DestinationsController.php
@@ -0,0 +1,105 @@
+ $d->id,
+ 'uuid' => $d->uuid,
+ 'name' => $d->name,
+ 'network' => $d->network,
+ 'type' => $d instanceof SwarmDocker ? 'swarm' : 'standalone',
+ 'server_uuid' => $d->server?->uuid,
+ 'created_at' => $d->created_at,
+ 'updated_at' => $d->updated_at,
+ ];
+ }
+
+ public function index(Request $request)
+ {
+ $teamId = auth()->user()->currentTeam()->id;
+ $standalone = StandaloneDocker::ownedByCurrentTeamAPI($teamId)->get();
+ $swarm = SwarmDocker::ownedByCurrentTeamAPI($teamId)->get();
+
+ return response()->json($standalone->concat($swarm)->map(fn ($d) => $this->transform($d))->values());
+ }
+
+ public function index_by_server(Request $request, string $server_uuid)
+ {
+ $teamId = auth()->user()->currentTeam()->id;
+ $server = Server::ownedByCurrentTeamAPI($teamId)->whereUuid($server_uuid)->firstOrFail();
+ $list = $server->standaloneDockers->concat($server->swarmDockers);
+
+ return response()->json($list->map(fn ($d) => $this->transform($d))->values());
+ }
+
+ public function show(Request $request, string $uuid)
+ {
+ $teamId = auth()->user()->currentTeam()->id;
+ $d = StandaloneDocker::ownedByCurrentTeamAPI($teamId)->whereUuid($uuid)->first()
+ ?? SwarmDocker::ownedByCurrentTeamAPI($teamId)->whereUuid($uuid)->firstOrFail();
+
+ return response()->json($this->transform($d));
+ }
+
+ public function create(Request $request, string $server_uuid)
+ {
+ $teamId = auth()->user()->currentTeam()->id;
+ $server = Server::ownedByCurrentTeamAPI($teamId)->whereUuid($server_uuid)->firstOrFail();
+
+ $allowed = ['name', 'network', 'type'];
+ $extra = array_diff(array_keys($request->all()), $allowed);
+ if (! empty($extra)) {
+ return response()->json(['message' => 'Unknown fields', 'fields' => array_values($extra)], 422);
+ }
+
+ $validator = Validator::make($request->all(), [
+ 'name' => 'nullable|string|max:255',
+ 'network' => ['required', 'string', 'max:255', 'regex:/^[a-zA-Z0-9][a-zA-Z0-9._-]*$/'],
+ 'type' => 'nullable|in:standalone,swarm',
+ ]);
+ if ($validator->fails()) {
+ return response()->json(['message' => 'Validation failed', 'errors' => $validator->errors()], 422);
+ }
+
+ $type = $request->input('type', 'standalone');
+ $name = $request->input('name') ?: ($server->name.'-'.$request->input('network'));
+ $class = $type === 'swarm' ? SwarmDocker::class : StandaloneDocker::class;
+
+ $exists = $class::where('server_id', $server->id)->where('network', $request->input('network'))->exists();
+ if ($exists) {
+ return response()->json(['message' => 'A destination with this network already exists on the server.'], 409);
+ }
+
+ $d = $class::create([
+ 'name' => $name,
+ 'network' => $request->input('network'),
+ 'server_id' => $server->id,
+ ]);
+
+ return response()->json(['uuid' => $d->uuid], 201);
+ }
+
+ public function delete(Request $request, string $uuid)
+ {
+ $teamId = auth()->user()->currentTeam()->id;
+ $d = StandaloneDocker::ownedByCurrentTeamAPI($teamId)->whereUuid($uuid)->first()
+ ?? SwarmDocker::ownedByCurrentTeamAPI($teamId)->whereUuid($uuid)->firstOrFail();
+ if ($d->attachedTo()) {
+ return response()->json(['message' => 'Destination has attached resources, detach first.'], 409);
+ }
+ $d->delete();
+
+ return response()->json(['message' => 'Deleted.']);
+ }
+}
diff --git a/routes/api.php b/routes/api.php
index cc380b2be..cd98df9ec 100644
--- a/routes/api.php
+++ b/routes/api.php
@@ -4,6 +4,7 @@ use App\Http\Controllers\Api\ApplicationsController;
use App\Http\Controllers\Api\CloudProviderTokensController;
use App\Http\Controllers\Api\DatabasesController;
use App\Http\Controllers\Api\DeployController;
+use App\Http\Controllers\Api\DestinationsController;
use App\Http\Controllers\Api\GithubController;
use App\Http\Controllers\Api\HetznerController;
use App\Http\Controllers\Api\OtherController;
@@ -87,6 +88,13 @@ Route::group([
Route::get('/servers/{uuid}/domains', [ServersController::class, 'domains_by_server'])->middleware(['api.ability:read']);
Route::get('/servers/{uuid}/resources', [ServersController::class, 'resources_by_server'])->middleware(['api.ability:read']);
+ // Destinations — REST surface for the Coolify "Destinations" UI section (added).
+ Route::get('/destinations', [DestinationsController::class, 'index'])->middleware(['api.ability:read']);
+ Route::get('/destinations/{uuid}', [DestinationsController::class, 'show'])->middleware(['api.ability:read']);
+ Route::delete('/destinations/{uuid}', [DestinationsController::class, 'delete'])->middleware(['api.ability:write']);
+ Route::get('/servers/{server_uuid}/destinations', [DestinationsController::class, 'index_by_server'])->middleware(['api.ability:read']);
+ Route::post('/servers/{server_uuid}/destinations', [DestinationsController::class, 'create'])->middleware(['api.ability:write']);
+
Route::get('/servers/{uuid}/validate', [ServersController::class, 'validate_server'])->middleware(['api.ability:write']);
Route::post('/servers', [ServersController::class, 'create_server'])->middleware(['api.ability:write']);
From 789e2c5cab41242659b59e425671a7bc0bf9891e Mon Sep 17 00:00:00 2001
From: Poul
Date: Mon, 25 May 2026 11:36:26 +0000
Subject: [PATCH 06/30] fix(api/destinations): use getTeamIdFromToken() like
other Api controllers
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit
Initial draft called auth()->user()->currentTeam() which returns null in
the API context (Sanctum tokens don't carry the per-user currentTeam
state — that's a session/Livewire concept). Other Api controllers
(ServersController, ScheduledTasksController, etc.) use the canonical
helper getTeamIdFromToken() with a null guard returning 403.
This swap makes all five endpoints work against a real token.
---
.../Api/DestinationsController.php | 35 ++++++++++++++++---
1 file changed, 30 insertions(+), 5 deletions(-)
diff --git a/app/Http/Controllers/Api/DestinationsController.php b/app/Http/Controllers/Api/DestinationsController.php
index 43fb0cba8..cd6c187b6 100644
--- a/app/Http/Controllers/Api/DestinationsController.php
+++ b/app/Http/Controllers/Api/DestinationsController.php
@@ -25,9 +25,22 @@ class DestinationsController extends Controller
];
}
+ private function teamIdOrAbort(): int|\Illuminate\Http\JsonResponse
+ {
+ $teamId = getTeamIdFromToken();
+ if (is_null($teamId)) {
+ return response()->json(['message' => 'You are not allowed to access the API.'], 403);
+ }
+
+ return $teamId;
+ }
+
public function index(Request $request)
{
- $teamId = auth()->user()->currentTeam()->id;
+ $teamId = $this->teamIdOrAbort();
+ if (! is_int($teamId)) {
+ return $teamId;
+ }
$standalone = StandaloneDocker::ownedByCurrentTeamAPI($teamId)->get();
$swarm = SwarmDocker::ownedByCurrentTeamAPI($teamId)->get();
@@ -36,7 +49,10 @@ class DestinationsController extends Controller
public function index_by_server(Request $request, string $server_uuid)
{
- $teamId = auth()->user()->currentTeam()->id;
+ $teamId = $this->teamIdOrAbort();
+ if (! is_int($teamId)) {
+ return $teamId;
+ }
$server = Server::ownedByCurrentTeamAPI($teamId)->whereUuid($server_uuid)->firstOrFail();
$list = $server->standaloneDockers->concat($server->swarmDockers);
@@ -45,7 +61,10 @@ class DestinationsController extends Controller
public function show(Request $request, string $uuid)
{
- $teamId = auth()->user()->currentTeam()->id;
+ $teamId = $this->teamIdOrAbort();
+ if (! is_int($teamId)) {
+ return $teamId;
+ }
$d = StandaloneDocker::ownedByCurrentTeamAPI($teamId)->whereUuid($uuid)->first()
?? SwarmDocker::ownedByCurrentTeamAPI($teamId)->whereUuid($uuid)->firstOrFail();
@@ -54,7 +73,10 @@ class DestinationsController extends Controller
public function create(Request $request, string $server_uuid)
{
- $teamId = auth()->user()->currentTeam()->id;
+ $teamId = $this->teamIdOrAbort();
+ if (! is_int($teamId)) {
+ return $teamId;
+ }
$server = Server::ownedByCurrentTeamAPI($teamId)->whereUuid($server_uuid)->firstOrFail();
$allowed = ['name', 'network', 'type'];
@@ -92,7 +114,10 @@ class DestinationsController extends Controller
public function delete(Request $request, string $uuid)
{
- $teamId = auth()->user()->currentTeam()->id;
+ $teamId = $this->teamIdOrAbort();
+ if (! is_int($teamId)) {
+ return $teamId;
+ }
$d = StandaloneDocker::ownedByCurrentTeamAPI($teamId)->whereUuid($uuid)->first()
?? SwarmDocker::ownedByCurrentTeamAPI($teamId)->whereUuid($uuid)->firstOrFail();
if ($d->attachedTo()) {
From 68e9184b57962c7c5c8f30e531e9ec69a73290b9 Mon Sep 17 00:00:00 2001
From: Poul
Date: Mon, 25 May 2026 11:47:10 +0000
Subject: [PATCH 07/30] fix(api/destinations): use whereHas instead of
ownedByCurrentTeamAPI for back-compat
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit
The ownedByCurrentTeamAPI scope was added to StandaloneDocker/SwarmDocker
*after* 4.0.0-beta.470 — running containers on that beta hit a
BadMethodCallException. Rewrites all team scoping to use
whereHas('server', whereTeamId) which works against any v4.x of
Coolify (StandaloneDocker.server_id -> Server.team_id has been there
since the multi-team change).
Also guards attachedTo() with method_exists and falls back to a manual
attached-resource check covering applications + every standalone DB
relation, so delete() doesn't crash on older versions either.
---
.../Api/DestinationsController.php | 62 +++++++++++++++----
1 file changed, 51 insertions(+), 11 deletions(-)
diff --git a/app/Http/Controllers/Api/DestinationsController.php b/app/Http/Controllers/Api/DestinationsController.php
index cd6c187b6..5db11624b 100644
--- a/app/Http/Controllers/Api/DestinationsController.php
+++ b/app/Http/Controllers/Api/DestinationsController.php
@@ -25,6 +25,9 @@ class DestinationsController extends Controller
];
}
+ /**
+ * Resolve the calling token's team id, or return a 403 response.
+ */
private function teamIdOrAbort(): int|\Illuminate\Http\JsonResponse
{
$teamId = getTeamIdFromToken();
@@ -35,16 +38,33 @@ class DestinationsController extends Controller
return $teamId;
}
+ /**
+ * StandaloneDocker / SwarmDocker scoped to a team via their parent server.
+ * Uses whereHas instead of the model's ownedByCurrentTeamAPI() scope so the
+ * controller works on Coolify versions that pre-date that scope being added
+ * to the destination models (e.g. 4.0.0-beta.470).
+ */
+ private function teamScopedDockers(int $teamId)
+ {
+ return [
+ 'standalone' => StandaloneDocker::whereHas('server', fn ($q) => $q->whereTeamId($teamId))->get(),
+ 'swarm' => SwarmDocker::whereHas('server', fn ($q) => $q->whereTeamId($teamId))->get(),
+ ];
+ }
+
public function index(Request $request)
{
$teamId = $this->teamIdOrAbort();
if (! is_int($teamId)) {
return $teamId;
}
- $standalone = StandaloneDocker::ownedByCurrentTeamAPI($teamId)->get();
- $swarm = SwarmDocker::ownedByCurrentTeamAPI($teamId)->get();
+ $sets = $this->teamScopedDockers($teamId);
- return response()->json($standalone->concat($swarm)->map(fn ($d) => $this->transform($d))->values());
+ return response()->json(
+ $sets['standalone']->concat($sets['swarm'])
+ ->map(fn ($d) => $this->transform($d))
+ ->values()
+ );
}
public function index_by_server(Request $request, string $server_uuid)
@@ -53,7 +73,7 @@ class DestinationsController extends Controller
if (! is_int($teamId)) {
return $teamId;
}
- $server = Server::ownedByCurrentTeamAPI($teamId)->whereUuid($server_uuid)->firstOrFail();
+ $server = Server::whereTeamId($teamId)->whereUuid($server_uuid)->firstOrFail();
$list = $server->standaloneDockers->concat($server->swarmDockers);
return response()->json($list->map(fn ($d) => $this->transform($d))->values());
@@ -65,8 +85,8 @@ class DestinationsController extends Controller
if (! is_int($teamId)) {
return $teamId;
}
- $d = StandaloneDocker::ownedByCurrentTeamAPI($teamId)->whereUuid($uuid)->first()
- ?? SwarmDocker::ownedByCurrentTeamAPI($teamId)->whereUuid($uuid)->firstOrFail();
+ $d = StandaloneDocker::whereHas('server', fn ($q) => $q->whereTeamId($teamId))->whereUuid($uuid)->first()
+ ?? SwarmDocker::whereHas('server', fn ($q) => $q->whereTeamId($teamId))->whereUuid($uuid)->firstOrFail();
return response()->json($this->transform($d));
}
@@ -77,7 +97,7 @@ class DestinationsController extends Controller
if (! is_int($teamId)) {
return $teamId;
}
- $server = Server::ownedByCurrentTeamAPI($teamId)->whereUuid($server_uuid)->firstOrFail();
+ $server = Server::whereTeamId($teamId)->whereUuid($server_uuid)->firstOrFail();
$allowed = ['name', 'network', 'type'];
$extra = array_diff(array_keys($request->all()), $allowed);
@@ -118,10 +138,30 @@ class DestinationsController extends Controller
if (! is_int($teamId)) {
return $teamId;
}
- $d = StandaloneDocker::ownedByCurrentTeamAPI($teamId)->whereUuid($uuid)->first()
- ?? SwarmDocker::ownedByCurrentTeamAPI($teamId)->whereUuid($uuid)->firstOrFail();
- if ($d->attachedTo()) {
- return response()->json(['message' => 'Destination has attached resources, detach first.'], 409);
+ $d = StandaloneDocker::whereHas('server', fn ($q) => $q->whereTeamId($teamId))->whereUuid($uuid)->first()
+ ?? SwarmDocker::whereHas('server', fn ($q) => $q->whereTeamId($teamId))->whereUuid($uuid)->firstOrFail();
+
+ // Guard against deleting destinations with attached resources. attachedTo()
+ // is recent on the destination models; fall back to a manual check for
+ // older Coolify versions (e.g. 4.0.0-beta.470).
+ if (method_exists($d, 'attachedTo')) {
+ if ($d->attachedTo()) {
+ return response()->json(['message' => 'Destination has attached resources, detach first.'], 409);
+ }
+ } else {
+ $hasAttached = $d->applications()->exists()
+ || $d->postgresqls()->exists()
+ || (method_exists($d, 'mysqls') && $d->mysqls()->exists())
+ || (method_exists($d, 'mariadbs') && $d->mariadbs()->exists())
+ || (method_exists($d, 'mongodbs') && $d->mongodbs()->exists())
+ || (method_exists($d, 'redis') && $d->redis()->exists())
+ || (method_exists($d, 'keydbs') && $d->keydbs()->exists())
+ || (method_exists($d, 'dragonflies') && $d->dragonflies()->exists())
+ || (method_exists($d, 'clickhouses') && $d->clickhouses()->exists())
+ || (method_exists($d, 'services') && $d->services()->exists());
+ if ($hasAttached) {
+ return response()->json(['message' => 'Destination has attached resources, detach first.'], 409);
+ }
}
$d->delete();
From 7b5415fdbea32bb90cecb72cdc4a0e0f99db30c7 Mon Sep 17 00:00:00 2001
From: ShadowArcanist <162910371+ShadowArcanist@users.noreply.github.com>
Date: Sat, 13 Jun 2026 20:15:25 +0530
Subject: [PATCH 08/30] fix(repo): remove beta from placeholder values on issue
template
---
.github/ISSUE_TEMPLATE/01_BUG_REPORT.yml | 2 +-
.../ISSUE_TEMPLATE/02_ENHANCEMENT_BOUNTY.yml | 54 -------------------
2 files changed, 1 insertion(+), 55 deletions(-)
delete mode 100644 .github/ISSUE_TEMPLATE/02_ENHANCEMENT_BOUNTY.yml
diff --git a/.github/ISSUE_TEMPLATE/01_BUG_REPORT.yml b/.github/ISSUE_TEMPLATE/01_BUG_REPORT.yml
index b236a07e2..d5106ab75 100644
--- a/.github/ISSUE_TEMPLATE/01_BUG_REPORT.yml
+++ b/.github/ISSUE_TEMPLATE/01_BUG_REPORT.yml
@@ -49,7 +49,7 @@ body:
attributes:
label: Coolify Version
description: Please provide the Coolify version you are using. This can be found in the top left corner of your Coolify dashboard.
- placeholder: "v4.0.0-beta.335"
+ placeholder: "v4.1.2"
validations:
required: true
diff --git a/.github/ISSUE_TEMPLATE/02_ENHANCEMENT_BOUNTY.yml b/.github/ISSUE_TEMPLATE/02_ENHANCEMENT_BOUNTY.yml
deleted file mode 100644
index b71f32bd2..000000000
--- a/.github/ISSUE_TEMPLATE/02_ENHANCEMENT_BOUNTY.yml
+++ /dev/null
@@ -1,54 +0,0 @@
-name: 💎 Enhancement Bounty
-description: "Propose a new feature, service, or improvement with an attached bounty."
-title: "[Enhancement]: "
-labels: ["✨ Enhancement", "🔍 Triage"]
-body:
- - type: markdown
- attributes:
- value: |
- > [!IMPORTANT]
- > **This issue template is exclusively for proposing new features, services, or improvements with an attached bounty.** Enhancements without a bounty can be discussed in the appropriate category of [Github Discussions](https://github.com/coollabsio/coolify/discussions).
-
- # 💎 Add a Bounty (with [algora.io](https://console.algora.io/org/coollabsio/bounties/new))
- - [Click here to add the required bounty](https://console.algora.io/org/coollabsio/bounties/new)
-
- - type: dropdown
- attributes:
- label: Request Type
- description: Select the type of request you are making.
- options:
- - New Feature
- - New Service
- - Improvement
- - Bug Fix
- validations:
- required: true
-
- - type: textarea
- attributes:
- label: Description
- description: Provide a detailed description of the feature, improvement, or service you are proposing.
- validations:
- required: true
-
- - type: textarea
- attributes:
- label: Requirements / How It Should Work
- description: Describe in detail how the feature, service, or improvement should function. Include user flow, expected behavior, or technical implementation notes if applicable.
- value: |
- 1.
- 2.
- 3.
- validations:
- required: true
-
- - type: textarea
- attributes:
- label: Criteria to Satisfy Bounty
- description: Define the conditions that must be met for the PR or contribution to be considered complete and eligible for the bounty. Be specific about functionality, tests, or documentation requirements.
- value: |
- 1.
- 2.
- 3.
- validations:
- required: true
\ No newline at end of file
From 62d9e401861384e884bf44d9ebd422d3a120a429 Mon Sep 17 00:00:00 2001
From: ShadowArcanist <162910371+ShadowArcanist@users.noreply.github.com>
Date: Sat, 13 Jun 2026 20:24:44 +0530
Subject: [PATCH 09/30] fix(repo): remove bounty and beta referrences on
contributors guidelines
---
CONTRIBUTING.md | 27 +++++++--------------------
1 file changed, 7 insertions(+), 20 deletions(-)
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
index 6632cc68f..12a9bdf35 100644
--- a/CONTRIBUTING.md
+++ b/CONTRIBUTING.md
@@ -27,14 +27,14 @@ This is normal for a two-maintainer project.
## State of the Project
-Coolify is currently at v4 and is still in beta. While v4 is stable, it has some limitations, including:
+Coolify is currently at v4. While v4 is stable, it has some limitations, including:
- Limited scaling support
- A more complex user experience
- Other smaller issues that need refinement
-These limitations will be addressed in Coolify v5, which is in the planning stage. However, the maintainers are focused on releasing a stable v4 version before dedicating time to v5 development. Because of this, major features, architectural changes, or significant UI changes will not be accepted for v4 at this stage.
+These limitations will be addressed in Coolify v5, which is in the planning stage. Because of this, major features, architectural changes, or significant UI changes will not be accepted for v4 at this stage.
-We welcome contributions that help stabilize v4, but larger changes will be saved for v5 once we have a stable v4 release.
+We welcome contributions that help stabilize v4 for a bug free experience.
## What Makes a Strong Contribution
@@ -122,7 +122,7 @@ Bug reports must include:
- Expected result
- Actual result
-Incomplete reports may be closed.
+Incomplete reports and reports generated using AI may be closed.
## 3. Code Contributions
@@ -177,7 +177,7 @@ AI-generated pull requests without clear understanding will be closed.
## Test Before Submitting
Before submitting a pull request:
-- Test your changes thoroughly
+- Manually test your changes thoroughly
- Verify they work in a clean environment
- Provide detailed testing steps in the PR description
@@ -186,22 +186,12 @@ If maintainers cannot reproduce working behavior, the PR will be closed without
## Submitting a Pull Request
- GitHub will auto-populate the PR template
-- The contributor agreement must remain intact
+- The contributor agreement in PR description must remain intact
- Pull requests without the contributor agreement will be closed
- All pull requests must target the `next` branch
- PRs targeting other branches will be closed without review
-## Bounty Issues
-Community members may create bounty issues for features or improvements.
-
-Important:
-- Only existing contributors are eligible
-- First-time contributors targeting bounty issues will be automatically closed and maybe excluded from contributing.
-
-This policy exists to prevent spam. We close 30+ bounty-targeted spam PRs per week.
-
-
## FAQ
**Q: Should I ask before fixing a typo or a small bug?**
A: No, small, obvious fixes like typos or narrowly-scoped bug fixes can be submitted as a PR directly.
@@ -210,7 +200,7 @@ A: No, small, obvious fixes like typos or narrowly-scoped bug fixes can be submi
A: Awesome! Discuss it first in GitHub Discussions or Discord. **Do not** open a PR for new features without prior alignment.
**Q: My PR was closed without detailed feedback.**
-A: This usually means it didn’t align with the project’s direction, required more review bandwidth than available, or targeted major changes not allowed in v4. This is normal for a two-maintainer project.
+A: This usually means it didn’t align with the project’s direction, required more review bandwidth than available, or targeted major changes not allowed in v4.
**Q: Can I work on an open issue?**
A: Comment on the issue first to confirm it’s still relevant and that no one else is actively working on it. For anything beyond a small fix, discuss your approach before implementing.
@@ -221,9 +211,6 @@ A: Focus only on your stated goal. Cleanups or refactors should be submitted as
**Q: Can I use AI to help with my PR?**
A: Yes, AI-assisted contributions are allowed. But you must fully understand and verify the changes. PRs that appear to be generated by AI without context understanding will be closed.
-**Q: Can I work on a bounty issue as a first-time contributor?**
-A: No, bounty issues are reserved for existing contributors. First-time contributors targeting bounty issues will have their PRs closed without review. This prevents spam and ensures bounties go to contributors familiar with the project.
-
**Q: My PR was closed without review. Can I submit a new one?**
A: Yes, but keep in mind a PR closure is feedback, not a rejection of your effort. It usually means the PR didn’t match the project goals or guidelines. Address these issues first — repeating the same approach may hurt your standing with maintainers.
From 9665aa292c935004781b90bec0b79270ded873d6 Mon Sep 17 00:00:00 2001
From: Andras Bacsai <5845193+andrasbacsai@users.noreply.github.com>
Date: Mon, 15 Jun 2026 17:03:01 +0200
Subject: [PATCH 10/30] fix(api): block invalid destination types and service
deletions
---
.../Api/DestinationsController.php | 16 +-
app/Models/StandaloneDocker.php | 2 +-
app/Models/SwarmDocker.php | 2 +-
tests/Feature/Api/DestinationsApiTest.php | 200 ++++++++++++++++++
4 files changed, 216 insertions(+), 4 deletions(-)
create mode 100644 tests/Feature/Api/DestinationsApiTest.php
diff --git a/app/Http/Controllers/Api/DestinationsController.php b/app/Http/Controllers/Api/DestinationsController.php
index 5db11624b..8b54913e7 100644
--- a/app/Http/Controllers/Api/DestinationsController.php
+++ b/app/Http/Controllers/Api/DestinationsController.php
@@ -6,6 +6,7 @@ use App\Http\Controllers\Controller;
use App\Models\Server;
use App\Models\StandaloneDocker;
use App\Models\SwarmDocker;
+use Illuminate\Http\JsonResponse;
use Illuminate\Http\Request;
use Illuminate\Support\Facades\Validator;
@@ -28,7 +29,7 @@ class DestinationsController extends Controller
/**
* Resolve the calling token's team id, or return a 403 response.
*/
- private function teamIdOrAbort(): int|\Illuminate\Http\JsonResponse
+ private function teamIdOrAbort(): int|JsonResponse
{
$teamId = getTeamIdFromToken();
if (is_null($teamId)) {
@@ -97,6 +98,12 @@ class DestinationsController extends Controller
if (! is_int($teamId)) {
return $teamId;
}
+
+ $return = validateIncomingRequest($request);
+ if ($return instanceof JsonResponse) {
+ return $return;
+ }
+
$server = Server::whereTeamId($teamId)->whereUuid($server_uuid)->firstOrFail();
$allowed = ['name', 'network', 'type'];
@@ -114,7 +121,12 @@ class DestinationsController extends Controller
return response()->json(['message' => 'Validation failed', 'errors' => $validator->errors()], 422);
}
- $type = $request->input('type', 'standalone');
+ $expectedType = $server->isSwarm() ? 'swarm' : 'standalone';
+ $type = $request->input('type', $expectedType);
+ if ($type !== $expectedType) {
+ return response()->json(['message' => "Destination type must be {$expectedType} for this server."], 422);
+ }
+
$name = $request->input('name') ?: ($server->name.'-'.$request->input('network'));
$class = $type === 'swarm' ? SwarmDocker::class : StandaloneDocker::class;
diff --git a/app/Models/StandaloneDocker.php b/app/Models/StandaloneDocker.php
index 1c5cfd342..c1dd4bf67 100644
--- a/app/Models/StandaloneDocker.php
+++ b/app/Models/StandaloneDocker.php
@@ -144,6 +144,6 @@ class StandaloneDocker extends BaseModel
public function attachedTo()
{
- return $this->applications?->count() > 0 || $this->databases()->count() > 0;
+ return $this->applications()->exists() || $this->databases()->count() > 0 || $this->services()->exists();
}
}
diff --git a/app/Models/SwarmDocker.php b/app/Models/SwarmDocker.php
index 0e9620457..02b8381d9 100644
--- a/app/Models/SwarmDocker.php
+++ b/app/Models/SwarmDocker.php
@@ -124,6 +124,6 @@ class SwarmDocker extends BaseModel
public function attachedTo()
{
- return $this->applications?->count() > 0 || $this->databases()->count() > 0;
+ return $this->applications()->exists() || $this->databases()->count() > 0 || $this->services()->exists();
}
}
diff --git a/tests/Feature/Api/DestinationsApiTest.php b/tests/Feature/Api/DestinationsApiTest.php
new file mode 100644
index 000000000..cbbd6d0a6
--- /dev/null
+++ b/tests/Feature/Api/DestinationsApiTest.php
@@ -0,0 +1,200 @@
+ 'array',
+ 'session.driver' => 'array',
+ 'queue.default' => 'sync',
+ 'app.maintenance.driver' => 'file',
+ ]);
+
+ InstanceSettings::unguarded(fn () => InstanceSettings::firstOrCreate(
+ ['id' => 0],
+ ['is_api_enabled' => true],
+ ));
+
+ $this->team = Team::factory()->create();
+ $this->user = User::factory()->create();
+ $this->team->members()->attach($this->user->id, ['role' => 'owner']);
+ session(['currentTeam' => $this->team]);
+
+ $this->bearerToken = destinationsApiToken($this->user, $this->team, ['*']);
+ $this->server = Server::factory()->create(['team_id' => $this->team->id]);
+ $this->destination = StandaloneDocker::where('server_id', $this->server->id)->first();
+});
+
+function destinationsApiHeaders(string $bearerToken): array
+{
+ return [
+ 'Authorization' => 'Bearer '.$bearerToken,
+ 'Content-Type' => 'application/json',
+ ];
+}
+
+function destinationsApiToken(User $user, Team $team, array $abilities): string
+{
+ $plainTextToken = Str::random(40);
+ $token = $user->tokens()->create([
+ 'name' => 'destinations-api-test-'.Str::random(6),
+ 'token' => hash('sha256', $plainTextToken),
+ 'abilities' => $abilities,
+ 'team_id' => $team->id,
+ ]);
+
+ return $token->getKey().'|'.$plainTextToken;
+}
+
+describe('GET /api/v1/destinations', function () {
+ test('lists only destinations owned by the token team', function () {
+ $otherTeam = Team::factory()->create();
+ $otherServer = Server::factory()->create(['team_id' => $otherTeam->id]);
+ $otherDestination = StandaloneDocker::where('server_id', $otherServer->id)->first();
+
+ $response = $this->withHeaders(destinationsApiHeaders($this->bearerToken))
+ ->getJson('/api/v1/destinations');
+
+ $response->assertOk();
+ $uuids = collect($response->json())->pluck('uuid');
+
+ expect($uuids)->toContain($this->destination->uuid)
+ ->not->toContain($otherDestination->uuid);
+ });
+});
+
+describe('GET /api/v1/destinations/{uuid}', function () {
+ test('does not expose another team destination', function () {
+ $otherTeam = Team::factory()->create();
+ $otherServer = Server::factory()->create(['team_id' => $otherTeam->id]);
+ $otherDestination = StandaloneDocker::where('server_id', $otherServer->id)->first();
+
+ $response = $this->withHeaders(destinationsApiHeaders($this->bearerToken))
+ ->getJson("/api/v1/destinations/{$otherDestination->uuid}");
+
+ $response->assertNotFound();
+ });
+});
+
+describe('GET /api/v1/servers/{server_uuid}/destinations', function () {
+ test('lists destinations for a team server', function () {
+ $response = $this->withHeaders(destinationsApiHeaders($this->bearerToken))
+ ->getJson("/api/v1/servers/{$this->server->uuid}/destinations");
+
+ $response->assertOk();
+ expect($response->json())->toHaveCount(1)
+ ->and($response->json('0.uuid'))->toBe($this->destination->uuid);
+ });
+});
+
+describe('POST /api/v1/servers/{server_uuid}/destinations', function () {
+ test('requires a write token', function () {
+ $readOnlyToken = destinationsApiToken($this->user, $this->team, ['read']);
+
+ $response = $this->withHeaders(destinationsApiHeaders($readOnlyToken))
+ ->postJson("/api/v1/servers/{$this->server->uuid}/destinations", [
+ 'network' => 'new-network',
+ ]);
+
+ $response->assertForbidden();
+ });
+
+ test('rejects non-json requests before creating a destination', function () {
+ $response = $this->withHeaders([
+ 'Authorization' => 'Bearer '.$this->bearerToken,
+ ])->post("/api/v1/servers/{$this->server->uuid}/destinations", [
+ 'network' => 'api-swarm-network',
+ 'type' => 'swarm',
+ ]);
+
+ $response->assertStatus(400);
+ expect(SwarmDocker::where('server_id', $this->server->id)->where('network', 'api-swarm-network')->exists())->toBeFalse();
+ });
+
+ test('rejects unknown fields', function () {
+ $response = $this->withHeaders(destinationsApiHeaders($this->bearerToken))
+ ->postJson("/api/v1/servers/{$this->server->uuid}/destinations", [
+ 'network' => 'new-network',
+ 'unexpected' => 'value',
+ ]);
+
+ $response->assertStatus(422);
+ $response->assertJsonPath('fields.0', 'unexpected');
+ });
+
+ test('rejects unsafe docker network names', function () {
+ $response = $this->withHeaders(destinationsApiHeaders($this->bearerToken))
+ ->postJson("/api/v1/servers/{$this->server->uuid}/destinations", [
+ 'network' => 'bad;network',
+ ]);
+
+ $response->assertStatus(422);
+ $response->assertJsonValidationErrors(['network']);
+ });
+
+ test('rejects a destination type that does not match the server mode', function () {
+ $response = $this->withHeaders(destinationsApiHeaders($this->bearerToken))
+ ->postJson("/api/v1/servers/{$this->server->uuid}/destinations", [
+ 'network' => 'wrong-type-network',
+ 'type' => 'swarm',
+ ]);
+
+ $response->assertStatus(422);
+ expect(SwarmDocker::where('server_id', $this->server->id)->where('network', 'wrong-type-network')->exists())->toBeFalse();
+ });
+
+ test('creates a swarm destination on a swarm server', function () {
+ $this->server->settings()->update(['is_swarm_manager' => true]);
+
+ $response = $this->withHeaders(destinationsApiHeaders($this->bearerToken))
+ ->postJson("/api/v1/servers/{$this->server->uuid}/destinations", [
+ 'name' => 'API Swarm',
+ 'network' => 'api-swarm-network',
+ 'type' => 'swarm',
+ ]);
+
+ $response->assertCreated();
+ $response->assertJsonStructure(['uuid']);
+ expect(SwarmDocker::where('server_id', $this->server->id)->where('network', 'api-swarm-network')->exists())->toBeTrue();
+ });
+
+ test('rejects duplicate networks on the same server and type', function () {
+ $response = $this->withHeaders(destinationsApiHeaders($this->bearerToken))
+ ->postJson("/api/v1/servers/{$this->server->uuid}/destinations", [
+ 'network' => $this->destination->network,
+ ]);
+
+ $response->assertStatus(409);
+ });
+});
+
+describe('DELETE /api/v1/destinations/{uuid}', function () {
+ test('blocks deleting a destination with an attached service', function () {
+ $project = Project::factory()->create(['team_id' => $this->team->id]);
+ $environment = $project->environments()->first();
+
+ Service::factory()->create([
+ 'environment_id' => $environment->id,
+ 'server_id' => $this->server->id,
+ 'destination_id' => $this->destination->id,
+ 'destination_type' => $this->destination->getMorphClass(),
+ ]);
+
+ $response = $this->withHeaders(destinationsApiHeaders($this->bearerToken))
+ ->deleteJson("/api/v1/destinations/{$this->destination->uuid}");
+
+ $response->assertStatus(409);
+ $this->assertModelExists($this->destination);
+ });
+});
From 9e021c4037ff9591511bb02491e9ea9413d929bd Mon Sep 17 00:00:00 2001
From: Andras Bacsai <5845193+andrasbacsai@users.noreply.github.com>
Date: Mon, 15 Jun 2026 17:15:56 +0200
Subject: [PATCH 11/30] fix(api): enforce destination access and cleanup
networks
Require admin team membership for destination mutations, return invalid-token
responses for tokenless requests, and remove standalone Docker networks when
deleting destinations.
---
.../RemoveStandaloneDockerNetwork.php | 16 ++
.../Api/DestinationsController.php | 139 +++++++++++-------
tests/Feature/Api/DestinationsApiTest.php | 62 +++++++-
3 files changed, 162 insertions(+), 55 deletions(-)
create mode 100644 app/Actions/Destination/RemoveStandaloneDockerNetwork.php
diff --git a/app/Actions/Destination/RemoveStandaloneDockerNetwork.php b/app/Actions/Destination/RemoveStandaloneDockerNetwork.php
new file mode 100644
index 000000000..21c40a50a
--- /dev/null
+++ b/app/Actions/Destination/RemoveStandaloneDockerNetwork.php
@@ -0,0 +1,16 @@
+network);
+
+ instant_remote_process(["docker network disconnect {$safeNetwork} coolify-proxy"], $destination->server, throwError: false);
+ instant_remote_process(["docker network rm -f {$safeNetwork}"], $destination->server);
+ }
+}
diff --git a/app/Http/Controllers/Api/DestinationsController.php b/app/Http/Controllers/Api/DestinationsController.php
index 8b54913e7..26836b89a 100644
--- a/app/Http/Controllers/Api/DestinationsController.php
+++ b/app/Http/Controllers/Api/DestinationsController.php
@@ -2,38 +2,37 @@
namespace App\Http\Controllers\Api;
+use App\Actions\Destination\RemoveStandaloneDockerNetwork;
use App\Http\Controllers\Controller;
use App\Models\Server;
use App\Models\StandaloneDocker;
use App\Models\SwarmDocker;
use Illuminate\Http\JsonResponse;
use Illuminate\Http\Request;
-use Illuminate\Support\Facades\Validator;
class DestinationsController extends Controller
{
- private function transform($d): array
+ private function transform(StandaloneDocker|SwarmDocker $destination): array
{
return [
- 'id' => $d->id,
- 'uuid' => $d->uuid,
- 'name' => $d->name,
- 'network' => $d->network,
- 'type' => $d instanceof SwarmDocker ? 'swarm' : 'standalone',
- 'server_uuid' => $d->server?->uuid,
- 'created_at' => $d->created_at,
- 'updated_at' => $d->updated_at,
+ 'uuid' => $destination->uuid,
+ 'name' => $destination->name,
+ 'network' => $destination->network,
+ 'type' => $destination instanceof SwarmDocker ? 'swarm' : 'standalone',
+ 'server_uuid' => $destination->server?->uuid,
+ 'created_at' => $destination->created_at,
+ 'updated_at' => $destination->updated_at,
];
}
/**
- * Resolve the calling token's team id, or return a 403 response.
+ * Resolve the calling token's team id, or return an invalid-token response.
*/
private function teamIdOrAbort(): int|JsonResponse
{
$teamId = getTeamIdFromToken();
if (is_null($teamId)) {
- return response()->json(['message' => 'You are not allowed to access the API.'], 403);
+ return invalidTokenResponse();
}
return $teamId;
@@ -45,15 +44,21 @@ class DestinationsController extends Controller
* controller works on Coolify versions that pre-date that scope being added
* to the destination models (e.g. 4.0.0-beta.470).
*/
- private function teamScopedDockers(int $teamId)
+ private function teamScopedDockers(int $teamId): array
{
return [
- 'standalone' => StandaloneDocker::whereHas('server', fn ($q) => $q->whereTeamId($teamId))->get(),
- 'swarm' => SwarmDocker::whereHas('server', fn ($q) => $q->whereTeamId($teamId))->get(),
+ 'standalone' => StandaloneDocker::with('server:id,uuid')->whereHas('server', fn ($query) => $query->whereTeamId($teamId))->get(),
+ 'swarm' => SwarmDocker::with('server:id,uuid')->whereHas('server', fn ($query) => $query->whereTeamId($teamId))->get(),
];
}
- public function index(Request $request)
+ private function findDestinationForTeam(int $teamId, string $uuid): StandaloneDocker|SwarmDocker
+ {
+ return StandaloneDocker::with('server:id,uuid,team_id,ip,user,port,private_key_id')->whereHas('server', fn ($query) => $query->whereTeamId($teamId))->whereUuid($uuid)->first()
+ ?? SwarmDocker::with('server:id,uuid,team_id')->whereHas('server', fn ($query) => $query->whereTeamId($teamId))->whereUuid($uuid)->firstOrFail();
+ }
+
+ public function index(Request $request): JsonResponse
{
$teamId = $this->teamIdOrAbort();
if (! is_int($teamId)) {
@@ -63,36 +68,38 @@ class DestinationsController extends Controller
return response()->json(
$sets['standalone']->concat($sets['swarm'])
- ->map(fn ($d) => $this->transform($d))
+ ->map(fn ($destination) => $this->transform($destination))
->values()
);
}
- public function index_by_server(Request $request, string $server_uuid)
+ public function index_by_server(Request $request, string $server_uuid): JsonResponse
{
$teamId = $this->teamIdOrAbort();
if (! is_int($teamId)) {
return $teamId;
}
- $server = Server::whereTeamId($teamId)->whereUuid($server_uuid)->firstOrFail();
+ $server = Server::with(['standaloneDockers.server:id,uuid', 'swarmDockers.server:id,uuid'])
+ ->whereTeamId($teamId)
+ ->whereUuid($server_uuid)
+ ->firstOrFail();
$list = $server->standaloneDockers->concat($server->swarmDockers);
- return response()->json($list->map(fn ($d) => $this->transform($d))->values());
+ return response()->json($list->map(fn ($destination) => $this->transform($destination))->values());
}
- public function show(Request $request, string $uuid)
+ public function show(Request $request, string $uuid): JsonResponse
{
$teamId = $this->teamIdOrAbort();
if (! is_int($teamId)) {
return $teamId;
}
- $d = StandaloneDocker::whereHas('server', fn ($q) => $q->whereTeamId($teamId))->whereUuid($uuid)->first()
- ?? SwarmDocker::whereHas('server', fn ($q) => $q->whereTeamId($teamId))->whereUuid($uuid)->firstOrFail();
+ $destination = $this->findDestinationForTeam($teamId, $uuid);
- return response()->json($this->transform($d));
+ return response()->json($this->transform($destination));
}
- public function create(Request $request, string $server_uuid)
+ public function create(Request $request, string $server_uuid): JsonResponse
{
$teamId = $this->teamIdOrAbort();
if (! is_int($teamId)) {
@@ -107,18 +114,22 @@ class DestinationsController extends Controller
$server = Server::whereTeamId($teamId)->whereUuid($server_uuid)->firstOrFail();
$allowed = ['name', 'network', 'type'];
- $extra = array_diff(array_keys($request->all()), $allowed);
- if (! empty($extra)) {
- return response()->json(['message' => 'Unknown fields', 'fields' => array_values($extra)], 422);
- }
- $validator = Validator::make($request->all(), [
+ $validator = customApiValidator($request->all(), [
'name' => 'nullable|string|max:255',
'network' => ['required', 'string', 'max:255', 'regex:/^[a-zA-Z0-9][a-zA-Z0-9._-]*$/'],
'type' => 'nullable|in:standalone,swarm',
]);
- if ($validator->fails()) {
- return response()->json(['message' => 'Validation failed', 'errors' => $validator->errors()], 422);
+ $extra = array_diff(array_keys($request->all()), $allowed);
+ if ($validator->fails() || ! empty($extra)) {
+ $errors = $validator->errors();
+ if (! empty($extra)) {
+ foreach ($extra as $field) {
+ $errors->add($field, 'This field is not allowed.');
+ }
+ }
+
+ return response()->json(['message' => 'Validation failed.', 'errors' => $errors], 422);
}
$expectedType = $server->isSwarm() ? 'swarm' : 'standalone';
@@ -130,52 +141,80 @@ class DestinationsController extends Controller
$name = $request->input('name') ?: ($server->name.'-'.$request->input('network'));
$class = $type === 'swarm' ? SwarmDocker::class : StandaloneDocker::class;
+ $this->authorize('create', $class);
+
$exists = $class::where('server_id', $server->id)->where('network', $request->input('network'))->exists();
if ($exists) {
return response()->json(['message' => 'A destination with this network already exists on the server.'], 409);
}
- $d = $class::create([
+ $destination = $class::create([
'name' => $name,
'network' => $request->input('network'),
'server_id' => $server->id,
]);
- return response()->json(['uuid' => $d->uuid], 201);
+ auditLog('api.destination.created', [
+ 'team_id' => $teamId,
+ 'destination_uuid' => $destination->uuid,
+ 'destination_name' => $destination->name,
+ 'destination_type' => $type,
+ 'server_uuid' => $server->uuid,
+ ]);
+
+ return response()->json($this->transform($destination->load('server:id,uuid')), 201);
}
- public function delete(Request $request, string $uuid)
+ public function delete(Request $request, string $uuid): JsonResponse
{
$teamId = $this->teamIdOrAbort();
if (! is_int($teamId)) {
return $teamId;
}
- $d = StandaloneDocker::whereHas('server', fn ($q) => $q->whereTeamId($teamId))->whereUuid($uuid)->first()
- ?? SwarmDocker::whereHas('server', fn ($q) => $q->whereTeamId($teamId))->whereUuid($uuid)->firstOrFail();
+ $destination = $this->findDestinationForTeam($teamId, $uuid);
+
+ $this->authorize('delete', $destination);
// Guard against deleting destinations with attached resources. attachedTo()
// is recent on the destination models; fall back to a manual check for
// older Coolify versions (e.g. 4.0.0-beta.470).
- if (method_exists($d, 'attachedTo')) {
- if ($d->attachedTo()) {
+ if (method_exists($destination, 'attachedTo')) {
+ if ($destination->attachedTo()) {
return response()->json(['message' => 'Destination has attached resources, detach first.'], 409);
}
} else {
- $hasAttached = $d->applications()->exists()
- || $d->postgresqls()->exists()
- || (method_exists($d, 'mysqls') && $d->mysqls()->exists())
- || (method_exists($d, 'mariadbs') && $d->mariadbs()->exists())
- || (method_exists($d, 'mongodbs') && $d->mongodbs()->exists())
- || (method_exists($d, 'redis') && $d->redis()->exists())
- || (method_exists($d, 'keydbs') && $d->keydbs()->exists())
- || (method_exists($d, 'dragonflies') && $d->dragonflies()->exists())
- || (method_exists($d, 'clickhouses') && $d->clickhouses()->exists())
- || (method_exists($d, 'services') && $d->services()->exists());
+ $hasAttached = $destination->applications()->exists()
+ || $destination->postgresqls()->exists()
+ || (method_exists($destination, 'mysqls') && $destination->mysqls()->exists())
+ || (method_exists($destination, 'mariadbs') && $destination->mariadbs()->exists())
+ || (method_exists($destination, 'mongodbs') && $destination->mongodbs()->exists())
+ || (method_exists($destination, 'redis') && $destination->redis()->exists())
+ || (method_exists($destination, 'keydbs') && $destination->keydbs()->exists())
+ || (method_exists($destination, 'dragonflies') && $destination->dragonflies()->exists())
+ || (method_exists($destination, 'clickhouses') && $destination->clickhouses()->exists())
+ || (method_exists($destination, 'services') && $destination->services()->exists());
if ($hasAttached) {
return response()->json(['message' => 'Destination has attached resources, detach first.'], 409);
}
}
- $d->delete();
+ if ($destination instanceof StandaloneDocker) {
+ app(RemoveStandaloneDockerNetwork::class)->handle($destination);
+ }
+
+ $destinationUuid = $destination->uuid;
+ $destinationName = $destination->name;
+ $destinationType = $destination instanceof SwarmDocker ? 'swarm' : 'standalone';
+ $serverUuid = $destination->server?->uuid;
+
+ $destination->delete();
+
+ auditLog('api.destination.deleted', [
+ 'team_id' => $teamId,
+ 'destination_uuid' => $destinationUuid,
+ 'destination_name' => $destinationName,
+ 'destination_type' => $destinationType,
+ 'server_uuid' => $serverUuid,
+ ]);
return response()->json(['message' => 'Deleted.']);
}
diff --git a/tests/Feature/Api/DestinationsApiTest.php b/tests/Feature/Api/DestinationsApiTest.php
index cbbd6d0a6..9639c5d9e 100644
--- a/tests/Feature/Api/DestinationsApiTest.php
+++ b/tests/Feature/Api/DestinationsApiTest.php
@@ -1,5 +1,6 @@
assertOk();
$uuids = collect($response->json())->pluck('uuid');
- expect($uuids)->toContain($this->destination->uuid)
+ expect($response->json('0'))->not->toHaveKey('id')
+ ->and($uuids)->toContain($this->destination->uuid)
->not->toContain($otherDestination->uuid);
});
});
@@ -110,6 +112,20 @@ describe('POST /api/v1/servers/{server_uuid}/destinations', function () {
$response->assertForbidden();
});
+ test('rejects create requests from non-admin team members', function () {
+ $member = User::factory()->create();
+ $this->team->members()->attach($member->id, ['role' => 'member']);
+ $memberToken = destinationsApiToken($member, $this->team, ['*']);
+
+ $response = $this->withHeaders(destinationsApiHeaders($memberToken))
+ ->postJson("/api/v1/servers/{$this->server->uuid}/destinations", [
+ 'network' => 'member-network',
+ ]);
+
+ $response->assertForbidden();
+ expect(StandaloneDocker::where('server_id', $this->server->id)->where('network', 'member-network')->exists())->toBeFalse();
+ });
+
test('rejects non-json requests before creating a destination', function () {
$response = $this->withHeaders([
'Authorization' => 'Bearer '.$this->bearerToken,
@@ -129,8 +145,8 @@ describe('POST /api/v1/servers/{server_uuid}/destinations', function () {
'unexpected' => 'value',
]);
- $response->assertStatus(422);
- $response->assertJsonPath('fields.0', 'unexpected');
+ $response->assertUnprocessable();
+ $response->assertJsonValidationErrors(['unexpected']);
});
test('rejects unsafe docker network names', function () {
@@ -139,7 +155,7 @@ describe('POST /api/v1/servers/{server_uuid}/destinations', function () {
'network' => 'bad;network',
]);
- $response->assertStatus(422);
+ $response->assertUnprocessable();
$response->assertJsonValidationErrors(['network']);
});
@@ -150,7 +166,7 @@ describe('POST /api/v1/servers/{server_uuid}/destinations', function () {
'type' => 'swarm',
]);
- $response->assertStatus(422);
+ $response->assertUnprocessable();
expect(SwarmDocker::where('server_id', $this->server->id)->where('network', 'wrong-type-network')->exists())->toBeFalse();
});
@@ -180,6 +196,42 @@ describe('POST /api/v1/servers/{server_uuid}/destinations', function () {
});
describe('DELETE /api/v1/destinations/{uuid}', function () {
+ test('requires a write token', function () {
+ $readOnlyToken = destinationsApiToken($this->user, $this->team, ['read']);
+
+ $response = $this->withHeaders(destinationsApiHeaders($readOnlyToken))
+ ->deleteJson("/api/v1/destinations/{$this->destination->uuid}");
+
+ $response->assertForbidden();
+ $this->assertModelExists($this->destination);
+ });
+
+ test('rejects delete requests from non-admin team members', function () {
+ $member = User::factory()->create();
+ $this->team->members()->attach($member->id, ['role' => 'member']);
+ $memberToken = destinationsApiToken($member, $this->team, ['*']);
+
+ $response = $this->withHeaders(destinationsApiHeaders($memberToken))
+ ->deleteJson("/api/v1/destinations/{$this->destination->uuid}");
+
+ $response->assertForbidden();
+ $this->assertModelExists($this->destination);
+ });
+
+ test('deletes standalone destinations after removing the docker network', function () {
+ $cleanup = Mockery::mock(RemoveStandaloneDockerNetwork::class);
+ $cleanup->shouldReceive('handle')
+ ->once()
+ ->with(Mockery::on(fn (StandaloneDocker $destination) => $destination->is($this->destination)));
+ $this->app->instance(RemoveStandaloneDockerNetwork::class, $cleanup);
+
+ $response = $this->withHeaders(destinationsApiHeaders($this->bearerToken))
+ ->deleteJson("/api/v1/destinations/{$this->destination->uuid}");
+
+ $response->assertOk();
+ $this->assertModelMissing($this->destination);
+ });
+
test('blocks deleting a destination with an attached service', function () {
$project = Project::factory()->create(['team_id' => $this->team->id]);
$environment = $project->environments()->first();
From bef94a9ce285469aa4f55e44b7374f9e36018320 Mon Sep 17 00:00:00 2001
From: Andras Bacsai <5845193+andrasbacsai@users.noreply.github.com>
Date: Thu, 25 Jun 2026 11:42:19 +0200
Subject: [PATCH 12/30] feat(mcp): add per-team server toggle
---
app/Http/Kernel.php | 2 ++
app/Http/Middleware/EnsureTeamMcpEnabled.php | 26 +++++++++++++++++++
app/Livewire/Team/Index.php | 5 ++++
app/Models/Team.php | 2 ++
...d_is_mcp_server_enabled_to_teams_table.php | 22 ++++++++++++++++
.../livewire/settings/advanced.blade.php | 2 +-
resources/views/livewire/team/index.blade.php | 2 ++
routes/ai.php | 2 +-
.../Authorization/TeamAuthorizationTest.php | 12 +++++++++
tests/Feature/Mcp/McpEndpointTest.php | 10 +++++++
10 files changed, 83 insertions(+), 2 deletions(-)
create mode 100644 app/Http/Middleware/EnsureTeamMcpEnabled.php
create mode 100644 database/migrations/2026_06_25_000000_add_is_mcp_server_enabled_to_teams_table.php
diff --git a/app/Http/Kernel.php b/app/Http/Kernel.php
index 02a49aaa8..9e8dee83e 100644
--- a/app/Http/Kernel.php
+++ b/app/Http/Kernel.php
@@ -12,6 +12,7 @@ use App\Http\Middleware\CheckForcePasswordReset;
use App\Http\Middleware\DecideWhatToDoWithUser;
use App\Http\Middleware\EncryptCookies;
use App\Http\Middleware\EnsureMcpEnabled;
+use App\Http\Middleware\EnsureTeamMcpEnabled;
use App\Http\Middleware\EnsureTokenBelongsToCurrentTeamMember;
use App\Http\Middleware\PreventRequestsDuringMaintenance;
use App\Http\Middleware\RedirectIfAuthenticated;
@@ -110,5 +111,6 @@ class Kernel extends HttpKernel
'can.update.resource' => CanUpdateResource::class,
'can.access.terminal' => CanAccessTerminal::class,
'mcp.enabled' => EnsureMcpEnabled::class,
+ 'mcp.team.enabled' => EnsureTeamMcpEnabled::class,
];
}
diff --git a/app/Http/Middleware/EnsureTeamMcpEnabled.php b/app/Http/Middleware/EnsureTeamMcpEnabled.php
new file mode 100644
index 000000000..5c76d2a1b
--- /dev/null
+++ b/app/Http/Middleware/EnsureTeamMcpEnabled.php
@@ -0,0 +1,26 @@
+user();
+ $teamId = $user?->currentAccessToken()?->team_id;
+
+ $team = $user?->teams()
+ ->where('teams.id', $teamId)
+ ->first();
+
+ if (! $team?->is_mcp_server_enabled) {
+ return response()->json(['message' => 'MCP server is disabled for this team.'], 403);
+ }
+
+ return $next($request);
+ }
+}
diff --git a/app/Livewire/Team/Index.php b/app/Livewire/Team/Index.php
index 140d9f5cc..406d385da 100644
--- a/app/Livewire/Team/Index.php
+++ b/app/Livewire/Team/Index.php
@@ -24,11 +24,14 @@ class Index extends Component
public ?string $description = null;
+ public bool $is_mcp_server_enabled = true;
+
protected function rules(): array
{
return [
'name' => ValidationPatterns::nameRules(),
'description' => ValidationPatterns::descriptionRules(),
+ 'is_mcp_server_enabled' => 'boolean',
];
}
@@ -58,10 +61,12 @@ class Index extends Component
// Sync TO model (before save)
$this->team->name = $this->name;
$this->team->description = $this->description;
+ $this->team->is_mcp_server_enabled = $this->is_mcp_server_enabled;
} else {
// Sync FROM model (on load/refresh)
$this->name = $this->team->name;
$this->description = $this->team->description;
+ $this->is_mcp_server_enabled = $this->team->is_mcp_server_enabled;
}
}
diff --git a/app/Models/Team.php b/app/Models/Team.php
index 23e2badb3..a979b44fb 100644
--- a/app/Models/Team.php
+++ b/app/Models/Team.php
@@ -47,10 +47,12 @@ class Team extends Model implements SendsDiscord, SendsEmail, SendsPushover, Sen
'personal_team',
'show_boarding',
'custom_server_limit',
+ 'is_mcp_server_enabled',
];
protected $casts = [
'personal_team' => 'boolean',
+ 'is_mcp_server_enabled' => 'boolean',
];
protected static function booted()
diff --git a/database/migrations/2026_06_25_000000_add_is_mcp_server_enabled_to_teams_table.php b/database/migrations/2026_06_25_000000_add_is_mcp_server_enabled_to_teams_table.php
new file mode 100644
index 000000000..3162a8613
--- /dev/null
+++ b/database/migrations/2026_06_25_000000_add_is_mcp_server_enabled_to_teams_table.php
@@ -0,0 +1,22 @@
+boolean('is_mcp_server_enabled')->default(true);
+ });
+ }
+
+ public function down(): void
+ {
+ Schema::table('teams', function (Blueprint $table) {
+ $table->dropColumn('is_mcp_server_enabled');
+ });
+ }
+};
diff --git a/resources/views/livewire/settings/advanced.blade.php b/resources/views/livewire/settings/advanced.blade.php
index 544ed7d4c..fb7da30a7 100644
--- a/resources/views/livewire/settings/advanced.blade.php
+++ b/resources/views/livewire/settings/advanced.blade.php
@@ -72,7 +72,7 @@
@endif