Contributing to Coolify
Set up the local Coolify development environment and prepare code contributions for the core repository.
Set up Docker, Spin, and a local fork of coollabsio/coolify. Start the stack with spin up, test at http://localhost:8000, and open pull requests against the next branch.
After installing Docker or OrbStack and Spin, confirm both commands are available.
docker --version
spin --versionWork from your own fork, then open a pull request back to Coolify when the change is ready.
Fork the Coolify repository
Clone your fork locally
Open the repository in your code editor
Keep each change focused on one issue or feature
- You can clone with Git, or use GitHub Desktop.
- Editors that work well include VS Code, Cursor, and Zed.
- Use a branch name that describes the change you are making.
Coolify ships a development environment example file. Copy it before starting the stack.
Find .env.development.example in the repository root
Duplicate it and rename the copy to .env
Review the values and adjust them for your machine
Save the file before starting Spin
- Keep local secrets in
.envand do not commit that file. - Review the example values before starting the stack.
- Restart Spin after changing environment variables.
Open a terminal in the local Coolify repository and leave the process running.
spin upIf you hit permission errors, especially on macOS, run:
sudo spin upYou may see some errors during startup. That can be expected while the development stack is booting.
Use the seeded development account to sign in locally.
| Tool | URL | Note |
|---|---|---|
| Coolify app | http://localhost:8000 | Use [email protected] and password. |
| Laravel Horizon | http://localhost:8000/horizon | Only available when logged in as the root user. |
| Mailpit | http://localhost:8025 | Catch local development emails. |
| Telescope | http://localhost:8000/telescope | Disabled by default; enable it with TELESCOPE_ENABLED=true. |
Telescope is disabled by default. Add this to your .env file when you need the debugging dashboard.
TELESCOPE_ENABLED=true- Commit and push your changes to your fork.
- Open the pull request against the Coolify repository.
- Set the base branch to
next, notv4.x. - Manually test the changed flow in the local app, not only through test files.
- Fill in the pull request template with the details maintainers need.
- Move the pull request out of draft as soon as it is ready for review.
Pull requests that stay in draft for a long time may be closed by maintainers.
Run migrations after switching branches, pulling updates, or changing database structure.
docker exec -it coolify php artisan migrateTo reset the development database with default seed data, run:
docker exec -it coolify php artisan migrate:fresh --seedIf the local stack or database is broken, remove the development containers and volumes, then start from a clean slate.
Stop the running Spin process
Press Ctrl+C in the terminal where Spin is running.
Remove development containers
docker rm coolify coolify-db coolify-redis coolify-realtime coolify-testing-host coolify-minio coolify-vite-1 coolify-mailRemove development volumes
docker volume rm coolify_dev_backups_data coolify_dev_postgres_data coolify_dev_coolify_data coolify_dev_minio_dataIf your volume names do not use the coolify prefix, remove the prefix from the volume command before running it.
Remove unused images
docker image prune -aStart Coolify again
spin upRun migrations and seeders
docker exec -it coolify php artisan migrate:fresh --seedService Templates
Add one-click service templates with the expected structure and verification.
- Template structure
- Metadata rules
- Testing checklist
Documentation
Improve these docs while keeping the existing writing style and component patterns.
- MDX patterns
- Docs structure
- Review expectations