A NethServer 8 module that integrates Coolify - an open-source, self-hosted alternative to Heroku/Netlify for deploying web applications.
Coolify is a self-hosted platform that allows you to deploy web applications (static sites, Node.js, PHP, Python, etc.) with automatic HTTPS, database provisioning, and more. It provides:
- One-click deployments from Git repositories
- Automatic HTTPS certificates via Let's Encrypt
- Database management (PostgreSQL, MySQL, MongoDB, Redis)
- Docker container orchestration
- Webhook integrations for CI/CD
- Team collaboration features
This module brings Coolify's powerful deployment capabilities to your NethServer infrastructure.
- π Easy deployment of web applications
- π Integrated with NethServer's security model
- π Automatic domain configuration with Traefik
- π Web-based management interface
- π Automated updates and rollbacks
- ποΈ Database provisioning and management
- π± Mobile-friendly UI
- NethServer 8 cluster
- At least 2GB RAM available
- Docker/Podman support
Instantiate the module with:
add-module ghcr.io/geniusdynamics/coolify:latest 1The output will return the instance name:
{
"module_id": "coolify1",
"image_name": "coolify",
"image_url": "ghcr.io/geniusdynamics/coolify:latest"
}The module runs Coolify 4.7.5 (ghcr.io/coollabsio/coolify:4.7.5) with
PostgreSQL 15 (docker.io/postgres:15.20-alpine3.24) and Redis 7
(docker.io/redis:7.4.12-alpine3.22). Module 1.8.0 and older ran Coolify 4.0.1.
- The realtime container is gone. Since Coolify 4.4 the realtime server
(Laravel Reverb, port 6001) and the terminal server (port 6002) run inside
the Coolify container, and its nginx proxies them on the dashboard host name
(
/app/and/terminal/ws). The module no longer runssoketi-appor pullsghcr.io/coollabsio/coolify-realtime. - The realtime keys must match. Reverb checks the
PUSHER_APP_*keys, which module 1.8.0 left empty. The module now generates them. - New storage for avatars and project icons, in the
coolify-imagesvolume. - SSH host key pinning (Coolify 4.7): the new
ssh_host_key_checkingsetting picks the mode. - Root account window: a new Coolify accepts the first (root) account
registration only for 10 minutes after Coolify starts. If the window
closed before you registered, restart the module services
(
runagent -m coolify1 systemctl --user restart coolify-app.service) and register within 10 minutes. - PostgreSQL and Redis keep their major versions (upstream still uses
postgres:15andredis:7), so the update needs no database dump and restore.
The update-module.d/10migrate_coolify_4_7 step runs before the restart and:
- stops and removes the legacy
soketi-appcontainer, its unit and its image; - keeps every existing secret (
APP_KEY, database password) and generates the missing ones once: a Redis password (Redis now requires it) and the realtime app keys. All of them are instate/*.envfiles with mode 0600; - converts the settings: the containers reach PostgreSQL and Redis on
127.0.0.1instead of container names,APP_URLgets itshttps://scheme,PHP_PM_*become thePHP_FPM_PM_*names that the image reads (custom values are kept), andAUTOUPDATEis turned off because NethServer updates the module; - then
20restartrestarts the pod, PostgreSQL, Redis and Coolify. Coolify runs its database migrations from 4.0.1 to 4.7.5 when it starts: the first start can take a few minutes.
Admins have nothing to do. The socket.<host> and websocket.<host> routes
stay for compatibility, but Coolify 4.7.5 no longer needs them: the browser uses
the dashboard host name for everything.
Backups now include the PostgreSQL dump (state/coolify.pg_dump) and the
coolify-images volume. Backups made by module 1.8.0 or older contain no
database, because their include list did not have the dump. Restoring one
now works (before, the restore failed). It brings back the settings, secrets
and Coolify volumes, but Coolify starts with an empty database. Take a new
backup after the update. Restore and clone never turn on Let's Encrypt: enable
it again once the DNS points to the new node.
Launch configure-module with the following parameters:
host: Fully qualified domain name for Coolifyhttp2https: Enable/disable HTTP to HTTPS redirection (true/false)lets_encrypt: Enable/disable Let's Encrypt certificate (true/false)ssh_host_key_checking(optional, defaultwarn): what Coolify does when the SSH host key of a server changes.warnconnects and notifies the team,enforcerefuses the connection, andoffdisables the check. The UI shows it under Settings > Advanced.
api-cli run configure-module --agent module/coolify1 --data - <<EOF
{
"host": "coolify.yourdomain.com",
"http2https": true,
"lets_encrypt": true,
"ssh_host_key_checking": "warn"
}
EOFThis will:
- Start and configure the Coolify instance
- Set up a virtual host in Traefik for external access
- Configure automatic HTTPS if enabled
- Access Coolify: Navigate to
https://coolify.yourdomain.com - Initial Setup: Register your admin account within 10 minutes of the first start (see above)
- Deploy Applications: Connect your Git repositories and deploy
- Manage Resources: Use the web interface to monitor and manage your deployments
api-cli run get-configuration --agent module/coolify1api-cli run update-module --data '{"module_url":"ghcr.io/geniusdynamics/coolify:latest","instances":["coolify1"],"force":true}'remove-module --no-preserve coolify1The module automatically discovers and integrates with NethServer's centralized smarthost setup. When the smarthost configuration changes, the module automatically reloads its services.
The module runs with comprehensive environment variables managed by the NethServer agent. Key variables include database connection details, service ports, and security settings.
Check environment variables:
runagent -m coolify1 envEnter the module's runtime environment:
runagent -m coolify1Inspect running containers:
runagent -m coolify1
podman psAccess container environment:
podman exec coolify-app envOpen shell in container:
podman exec -ti coolify-app shThe module includes a Vue.js-based web interface. For UI development:
- Navigate to the
ui/directory - Follow the NethServer UI development guide
Test the module using the provided script:
./test-module.sh <NODE_ADDR> ghcr.io/geniusdynamics/gccoolify:latestTests are written using Robot Framework.
The UI supports multiple languages and is translated via Weblate.
To contribute translations:
- Add the GitHub Weblate app to your repository
- Add your repository to hosted.weblate.org or request addition to the NS8 Weblate project
- π NethServer Documentation
- π Report Issues
- π¬ Community Forum
- π€ Contributing Guide
This project is licensed under the GPL-3.0 License - see the LICENSE file for details.