feat: add dev_helper_version to instance settings and update related functionality

app/Actions/Server/CleanupDocker.php

@@ -20,7 +20,7 @@ class CleanupDocker
         $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';

app/Jobs/ApplicationDeploymentJob.php

@@ -1780,9 +1780,8 @@ class ApplicationDeploymentJob implements ShouldBeEncrypted, ShouldQueue
     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);

app/Jobs/DatabaseBackupJob.php

@@ -653,9 +653,8 @@ class DatabaseBackupJob implements ShouldBeEncrypted, ShouldQueue
 
     private function getFullImageName(): string
     {
-        $settings = instanceSettings();
         $helperImage = config('constants.coolify.helper_image');
-        $latestVersion = $settings->helper_version;
+        $latestVersion = getHelperVersion();
 
         return "{$helperImage}:{$latestVersion}";
     }

app/Jobs/PullHelperImageJob.php

@@ -24,7 +24,7 @@ class PullHelperImageJob implements ShouldBeEncrypted, ShouldQueue
     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);
     }
 }

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 @@ class Index extends Component
         $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 @@ class Index extends Component
         $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!');

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();

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');
+        });
+    }
+};

resources/views/livewire/settings/index.blade.php

@@ -76,6 +76,13 @@
                             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>