From f315e4bd9c5a529fdf8be0cc289fdbdbe2f2dc3e Mon Sep 17 00:00:00 2001
From: Andras Bacsai <5845193+andrasbacsai@users.noreply.github.com>
Date: Mon, 3 Nov 2025 08:38:43 +0100
Subject: [PATCH] feat: add dev_helper_version to instance settings and update
 related functionality

---
 app/Actions/Server/CleanupDocker.php          |  2 +-
 app/Jobs/ApplicationDeploymentJob.php         |  3 +-
 app/Jobs/DatabaseBackupJob.php                |  3 +-
 app/Jobs/PullHelperImageJob.php               |  2 +-
 app/Livewire/Settings/Index.php               |  5 ++++
 bootstrap/helpers/shared.php                  | 12 ++++++++
 ...ev_helper_version_to_instance_settings.php | 28 +++++++++++++++++++
 .../views/livewire/settings/index.blade.php   |  7 +++++
 8 files changed, 56 insertions(+), 6 deletions(-)
 create mode 100644 database/migrations/2025_11_02_161923_add_dev_helper_version_to_instance_settings.php

diff --git a/app/Actions/Server/CleanupDocker.php b/app/Actions/Server/CleanupDocker.php
index 392562167..6bf094c32 100644
--- a/app/Actions/Server/CleanupDocker.php
+++ b/app/Actions/Server/CleanupDocker.php
@@ -20,7 +20,7 @@ public function handle(Server $server, bool $deleteUnusedVolumes = false, bool $
         $realtimeImageWithoutPrefix = 'coollabsio/coolify-realtime';
         $realtimeImageWithoutPrefixVersion = "coollabsio/coolify-realtime:$realtimeImageVersion";
 
-        $helperImageVersion = data_get($settings, 'helper_version');
+        $helperImageVersion = getHelperVersion();
         $helperImage = config('constants.coolify.helper_image');
         $helperImageWithVersion = "$helperImage:$helperImageVersion";
         $helperImageWithoutPrefix = 'coollabsio/coolify-helper';
diff --git a/app/Jobs/ApplicationDeploymentJob.php b/app/Jobs/ApplicationDeploymentJob.php
index 9bbf048b9..a240a759a 100644
--- a/app/Jobs/ApplicationDeploymentJob.php
+++ b/app/Jobs/ApplicationDeploymentJob.php
@@ -1780,9 +1780,8 @@ private function create_workdir()
     private function prepare_builder_image(bool $firstTry = true)
     {
         $this->checkForCancellation();
-        $settings = instanceSettings();
         $helperImage = config('constants.coolify.helper_image');
-        $helperImage = "{$helperImage}:{$settings->helper_version}";
+        $helperImage = "{$helperImage}:".getHelperVersion();
         // Get user home directory
         $this->serverUserHomeDir = instant_remote_process(['echo $HOME'], $this->server);
         $this->dockerConfigFileExists = instant_remote_process(["test -f {$this->serverUserHomeDir}/.docker/config.json && echo 'OK' || echo 'NOK'"], $this->server);
diff --git a/app/Jobs/DatabaseBackupJob.php b/app/Jobs/DatabaseBackupJob.php
index 11da6fac1..45586f0d0 100644
--- a/app/Jobs/DatabaseBackupJob.php
+++ b/app/Jobs/DatabaseBackupJob.php
@@ -653,9 +653,8 @@ private function upload_to_s3(): void
 
     private function getFullImageName(): string
     {
-        $settings = instanceSettings();
         $helperImage = config('constants.coolify.helper_image');
-        $latestVersion = $settings->helper_version;
+        $latestVersion = getHelperVersion();
 
         return "{$helperImage}:{$latestVersion}";
     }
diff --git a/app/Jobs/PullHelperImageJob.php b/app/Jobs/PullHelperImageJob.php
index b92886d38..7cdf1b81a 100644
--- a/app/Jobs/PullHelperImageJob.php
+++ b/app/Jobs/PullHelperImageJob.php
@@ -24,7 +24,7 @@ public function __construct(public Server $server)
     public function handle(): void
     {
         $helperImage = config('constants.coolify.helper_image');
-        $latest_version = instanceSettings()->helper_version;
+        $latest_version = getHelperVersion();
         instant_remote_process(["docker pull -q {$helperImage}:{$latest_version}"], $this->server, false);
     }
 }
diff --git a/app/Livewire/Settings/Index.php b/app/Livewire/Settings/Index.php
index 13d690352..96f13b173 100644
--- a/app/Livewire/Settings/Index.php
+++ b/app/Livewire/Settings/Index.php
@@ -35,6 +35,9 @@ class Index extends Component
     #[Validate('required|string|timezone')]
     public string $instance_timezone;
 
+    #[Validate('nullable|string|max:50')]
+    public ?string $dev_helper_version = null;
+
     public array $domainConflicts = [];
 
     public bool $showDomainConflictModal = false;
@@ -60,6 +63,7 @@ public function mount()
         $this->public_ipv4 = $this->settings->public_ipv4;
         $this->public_ipv6 = $this->settings->public_ipv6;
         $this->instance_timezone = $this->settings->instance_timezone;
+        $this->dev_helper_version = $this->settings->dev_helper_version;
     }
 
     #[Computed]
@@ -81,6 +85,7 @@ public function instantSave($isSave = true)
         $this->settings->public_ipv4 = $this->public_ipv4;
         $this->settings->public_ipv6 = $this->public_ipv6;
         $this->settings->instance_timezone = $this->instance_timezone;
+        $this->settings->dev_helper_version = $this->dev_helper_version;
         if ($isSave) {
             $this->settings->save();
             $this->dispatch('success', 'Settings updated!');
diff --git a/bootstrap/helpers/shared.php b/bootstrap/helpers/shared.php
index 0f5b6f553..effde712a 100644
--- a/bootstrap/helpers/shared.php
+++ b/bootstrap/helpers/shared.php
@@ -2879,6 +2879,18 @@ function instanceSettings()
     return InstanceSettings::get();
 }
 
+function getHelperVersion(): string
+{
+    $settings = instanceSettings();
+
+    // In development mode, use the dev_helper_version if set, otherwise fallback to config
+    if (isDev() && ! empty($settings->dev_helper_version)) {
+        return $settings->dev_helper_version;
+    }
+
+    return config('constants.coolify.helper_version');
+}
+
 function loadConfigFromGit(string $repository, string $branch, string $base_directory, int $server_id, int $team_id)
 {
     $server = Server::find($server_id)->where('team_id', $team_id)->first();
diff --git a/database/migrations/2025_11_02_161923_add_dev_helper_version_to_instance_settings.php b/database/migrations/2025_11_02_161923_add_dev_helper_version_to_instance_settings.php
new file mode 100644
index 000000000..56ed2239a
--- /dev/null
+++ b/database/migrations/2025_11_02_161923_add_dev_helper_version_to_instance_settings.php
@@ -0,0 +1,28 @@
+<?php
+
+use Illuminate\Database\Migrations\Migration;
+use Illuminate\Database\Schema\Blueprint;
+use Illuminate\Support\Facades\Schema;
+
+return new class extends Migration
+{
+    /**
+     * Run the migrations.
+     */
+    public function up(): void
+    {
+        Schema::table('instance_settings', function (Blueprint $table) {
+            $table->string('dev_helper_version')->nullable();
+        });
+    }
+
+    /**
+     * Reverse the migrations.
+     */
+    public function down(): void
+    {
+        Schema::table('instance_settings', function (Blueprint $table) {
+            $table->dropColumn('dev_helper_version');
+        });
+    }
+};
diff --git a/resources/views/livewire/settings/index.blade.php b/resources/views/livewire/settings/index.blade.php
index 61a73d25c..4ceb2043a 100644
--- a/resources/views/livewire/settings/index.blade.php
+++ b/resources/views/livewire/settings/index.blade.php
@@ -76,6 +76,13 @@ class="px-4 py-2 text-gray-800 cursor-pointer hover:bg-gray-100 dark:hover:bg-co
                             helper="Enter the IPv6 address of the instance.<br><br>It is useful if you have several IPv6 addresses and Coolify could not detect the correct one."
                             placeholder="2001:db8::1" autocomplete="new-password" />
                     </div>
+                    @if(isDev())
+                    <div class="flex gap-2 md:flex-row flex-col w-full">
+                        <x-forms.input id="dev_helper_version" label="Dev Helper Version (Development Only)"
+                            helper="Override the default coolify-helper image version. Leave empty to use the default version from config ({{ config('constants.coolify.helper_version') }}). Examples: 1.0.11, latest, dev"
+                            placeholder="{{ config('constants.coolify.helper_version') }}" />
+                    </div>
+                    @endif
                 </div>
             </div>
         </form>