An open-source, self-hostable PaaS alternative to Vercel, Heroku & Netlify that lets you easily deploy static sites, databases, full-stack applications and 360+ one-click services on your own servers.
PHP coolifydatabasesdeploymentdockerdocker-composeinertiajslaravelmariadbmysqlnextjsnodejsphppostgresredisself-hostedself-hostingserverstatic-sitesveltesvelte5
fix(applications): allow environment variable references in image tags
Andras Bacsai4f9ad86e52c2
diff --git a/app/Http/Controllers/Api/ApplicationsController.php b/app/Http/Controllers/Api/ApplicationsController.phpindex 91161f4000..d5114dd7a3 100644--- a/app/Http/Controllers/Api/ApplicationsController.php+++ b/app/Http/Controllers/Api/ApplicationsController.php@@ -2395,7 +2395,7 @@ class ApplicationsController extends Controller]))->setStatusCode(201);} elseif ($type === 'dockerimage') {$validationRules = [- 'docker_registry_image_name' => ['required', 'string', 'max:255', new DockerImageFormat],+ 'docker_registry_image_name' => ['required', 'string', 'max:255', new DockerImageFormat(allowVariableTag: true)],'docker_registry_image_tag' => ValidationPatterns::dockerImageTagRules(),'ports_exposes' => 'string|regex:/^(\d+)(,\d+)*$/|nullable',];diff --git a/app/Rules/DockerImageFormat.php b/app/Rules/DockerImageFormat.phpindex 038cc27619..4c1acf2066 100644--- a/app/Rules/DockerImageFormat.php+++ b/app/Rules/DockerImageFormat.php@@ -9,6 +9,11 @@ use Illuminate\Translation\PotentiallyTranslatedString;class DockerImageFormat implements ValidationRule{+ /**+ * @param bool $allowVariableTag Allow $VAR tags. Use it only for images that Docker Compose runs, because only Compose fills in the variables.+ */+ public function __construct(private bool $allowVariableTag = false) {}+/*** Run the validation rule.*@@ -35,15 +40,15 @@ class DockerImageFormat implements ValidationRuleif (preg_match('/\A(.+)@sha256:([a-f0-9]{64})\z/i', $value, $matches) === 1) {$imageName = $matches[1];} else {- $lastColon = strrpos($value, ':');$lastSlash = strrpos($value, '/');- if ($lastColon !== false && ($lastSlash === false || $lastColon > $lastSlash)) {- $imageName = substr($value, 0, $lastColon);- $tag = substr($value, $lastColon + 1);+ $tagColon = strpos($value, ':', $lastSlash === false ? 0 : $lastSlash + 1);+ if ($tagColon !== false) {+ $imageName = substr($value, 0, $tagColon);+ $tag = substr($value, $tagColon + 1);}}- if (! ValidationPatterns::isValidDockerImageName($imageName) || ! ValidationPatterns::isValidDockerImageTag($tag)) {+ if (! ValidationPatterns::isValidDockerImageName($imageName) || ! ValidationPatterns::isValidDockerImageTag($tag, allowVariables: $this->allowVariableTag)) {$fail('The :attribute format is invalid. Use image:tag or image@sha256:hash format.');}}diff --git a/app/Services/DockerImageParser.php b/app/Services/DockerImageParser.phpindex b483c979a3..b74a96f7f3 100644--- a/app/Services/DockerImageParser.php+++ b/app/Services/DockerImageParser.php@@ -20,15 +20,15 @@ class DockerImageParser$this->tag = $matches[2];$this->isImageHash = true;} else {- // Split by : to handle the tag, but be careful with registry ports- $lastColon = strrpos($imageString, ':');- $hasSlash = str_contains($imageString, '/');-- // If the last colon appears after the last slash, it's a tag- // Otherwise it might be a port in the registry URL- if ($lastColon !== false && (! $hasSlash || $lastColon > strrpos($imageString, '/'))) {- $mainPart = substr($imageString, 0, $lastColon);- $this->tag = substr($imageString, $lastColon + 1);+ // The tag starts at the first colon after the last slash. A colon before+ // the last slash is a registry port, and a later colon can be part of a+ // ${VAR:-default} tag.+ $lastSlash = strrpos($imageString, '/');+ $tagColon = strpos($imageString, ':', $lastSlash === false ? 0 : $lastSlash + 1);++ if ($tagColon !== false) {+ $mainPart = substr($imageString, 0, $tagColon);+ $this->tag = substr($imageString, $tagColon + 1);// Check if the tag is a SHA256 hash$this->isImageHash = $this->isSha256Hash($this->tag);diff --git a/app/Support/ValidationPatterns.php b/app/Support/ValidationPatterns.phpindex 53bc945c18..77c89f2fbe 100644--- a/app/Support/ValidationPatterns.php+++ b/app/Support/ValidationPatterns.php@@ -144,12 +144,23 @@ class ValidationPatternspublic const DOCKER_IMAGE_NAME_PATTERN = '/\A(?=.{1,255}\z)(?:(?:(?:[a-z0-9](?:[a-z0-9.-]*[a-z0-9])?|\[[0-9a-f:.]+\])(?::[0-9]+)?\/)?[a-z0-9]+(?:(?:[._]|__|-+)[a-z0-9]+)*(?:\/[a-z0-9]+(?:(?:[._]|__|-+)[a-z0-9]+)*)*)(?:@sha256)?\z/';/**- * Pattern for Docker image tags.+ * Pattern for literal Docker image tags.** Docker tags may contain letters, digits, underscores, dots, and hyphens,* must start with an alphanumeric/underscore, and are limited to 128 chars.*/- public const DOCKER_IMAGE_TAG_PATTERN = '/\A[A-Za-z0-9_][A-Za-z0-9_.-]{0,127}\z/';+ public const DOCKER_IMAGE_LITERAL_TAG_PATTERN = '/\A[A-Za-z0-9_][A-Za-z0-9_.-]{0,127}\z/';++ /**+ * Pattern for Docker image tags of applications.+ *+ * Same as DOCKER_IMAGE_LITERAL_TAG_PATTERN, but+ * $VAR, ${VAR}, ${VAR:-default} and ${VAR-default} references are also allowed,+ * because Docker Compose fills them in from the application's environment+ * variables at deploy time. A default may only hold tag characters. Other+ * expansions ($(...), ${VAR:?...}, nested references, $1, $$) are rejected.+ */+ public const DOCKER_IMAGE_TAG_PATTERN = '/\A(?=.{1,128}\z)(?:[A-Za-z0-9_]|\$(?:[A-Za-z_][A-Za-z0-9_]*+|\{[A-Za-z_][A-Za-z0-9_]*+(?::?-[A-Za-z0-9_.-]*+)?\}))(?:[A-Za-z0-9_.-]|\$(?:[A-Za-z_][A-Za-z0-9_]*+|\{[A-Za-z_][A-Za-z0-9_]*+(?::?-[A-Za-z0-9_.-]*+)?\}))*\z/';/*** Normalize environment variable keys before validation and storage.@@ -312,7 +323,7 @@ class ValidationPatterns{return ["{$nameField}.regex" => 'The Docker registry image name must be a valid image repository without a tag and may not contain shell metacharacters.',- "{$tagField}.regex" => 'The Docker registry image tag must be a valid Docker tag and may not contain shell metacharacters.',+ "{$tagField}.regex" => 'The Docker registry image tag must be a valid Docker tag or a $VARIABLE reference and may not contain shell metacharacters.',];}@@ -348,14 +359,17 @@ class ValidationPatterns/*** Check if a string is a valid Docker image tag.+ *+ * Set $allowVariables to false where Docker Compose does not fill in the tag,+ * for example for images that Coolify runs with docker run.*/- public static function isValidDockerImageTag(?string $value): bool+ public static function isValidDockerImageTag(?string $value, bool $allowVariables = true): bool{if (blank($value)) {return true;}- return preg_match(self::DOCKER_IMAGE_TAG_PATTERN, $value) === 1;+ return preg_match($allowVariables ? self::DOCKER_IMAGE_TAG_PATTERN : self::DOCKER_IMAGE_LITERAL_TAG_PATTERN, $value) === 1;}/**diff --git a/tests/Feature/Livewire/ApplicationGeneralDockerRegistryImageValidationTest.php b/tests/Feature/Livewire/ApplicationGeneralDockerRegistryImageValidationTest.phpindex 3ed6b85448..a8a08285e2 100644--- a/tests/Feature/Livewire/ApplicationGeneralDockerRegistryImageValidationTest.php+++ b/tests/Feature/Livewire/ApplicationGeneralDockerRegistryImageValidationTest.php@@ -53,3 +53,17 @@ it('uses safe docker registry image validation rules in the application general->and($validator->errors()->has('dockerRegistryImageName'))->toBeTrue()->and($validator->errors()->has('dockerRegistryImageTag'))->toBeTrue();});++it('accepts an environment variable reference as the docker registry image tag in the application general form', function () {+ $component = new General;+ $method = new ReflectionMethod($component, 'rules');+ $rules = $method->invoke($component);++ $validator = validator([+ 'dockerRegistryImageTag' => '$API_VERSION',+ ], [+ 'dockerRegistryImageTag' => $rules['dockerRegistryImageTag'],+ ]);++ expect($validator->passes())->toBeTrue();+});diff --git a/tests/Unit/DockerImageParserTest.php b/tests/Unit/DockerImageParserTest.phpindex 43de9797f2..dea8ffddad 100644--- a/tests/Unit/DockerImageParserTest.php+++ b/tests/Unit/DockerImageParserTest.php@@ -139,3 +139,15 @@ it('correctly parses image when user provides digest-decorated name with colon h->and($parser->getTag())->toBe($hash)->and($parser->isImageHash())->toBeTrue();});++it('parses a tag with a default value as one tag', function (string $imageString, string $imageName) {+ $parser = new DockerImageParser;+ $parser->parse($imageString);++ expect($parser->getFullImageNameWithoutTag())->toBe($imageName)+ ->and($parser->getTag())->toBe('${API_VERSION:-latest}')+ ->and($parser->isImageHash())->toBeFalse();+})->with([+ 'image' => ['nginx:${API_VERSION:-latest}', 'nginx'],+ 'registry image with port' => ['localhost:5000/team/app:${API_VERSION:-latest}', 'localhost:5000/team/app'],+]);diff --git a/tests/Unit/DockerImageReferenceValidationTest.php b/tests/Unit/DockerImageReferenceValidationTest.phpindex 05f2bce7ff..b1e65c5eb5 100644--- a/tests/Unit/DockerImageReferenceValidationTest.php+++ b/tests/Unit/DockerImageReferenceValidationTest.php@@ -46,6 +46,11 @@ it('accepts valid docker registry image tags', function (string $tag) {'uppercase and underscore' => 'PR_123','sha256 hash' => '1234567890abcdef1234567890abcdef1234567890abcdef1234567890abcdef','legacy sha256 prefixed hash' => 'sha256-1234567890abcdef1234567890abcdef1234567890abcdef1234567890abcdef',+ 'environment variable reference' => '$API_VERSION',+ 'braced environment variable reference' => '${API_VERSION}',+ 'environment variable reference with literal parts' => 'v${API_VERSION}-alpine',+ 'environment variable reference with default for empty or unset' => '${API_VERSION:-latest}',+ 'environment variable reference with default for unset' => '${API_VERSION-1.27-alpine}',]);it('rejects docker registry image tags with shell metacharacters', function (string $tag) {@@ -57,6 +62,14 @@ it('rejects docker registry image tags with shell metacharacters', function (str'pipe' => 'latest|id','logical and' => 'latest&&id','newline' => "latest\nid",+ 'bare dollar' => '$',+ 'positional parameter' => '$1',+ 'special parameter' => '$$',+ 'unclosed braced reference' => '${API_VERSION',+ 'parameter expansion with command substitution default' => '${API_VERSION:-$(id)}',+ 'parameter expansion with nested reference default' => '${API_VERSION:-${OTHER}}',+ 'parameter expansion with required error' => '${API_VERSION:?missing}',+ 'parameter expansion with assignment' => '${API_VERSION:=latest}',]);it('accepts supported full docker image reference formats', function (string $imageReference) {@@ -76,6 +89,21 @@ it('accepts supported full docker image reference formats', function (string $im'IPv6 registry port image with tag' => '[2a01:4f8::1]:5000/app:latest',]);+it('accepts an environment variable tag in a full docker image reference only when variable tags are allowed', function () {+ $validate = function (DockerImageFormat $rule): array {+ $failures = [];++ $rule->validate('image', 'ghcr.io/user/app:${API_VERSION:-latest}', function (string $message) use (&$failures): void {+ $failures[] = $message;+ });++ return $failures;+ };++ expect($validate(new DockerImageFormat(allowVariableTag: true)))->toBeEmpty()+ ->and($validate(new DockerImageFormat))->not->toBeEmpty();+});+it('rejects unsupported full docker image reference formats', function (string $imageReference) {$failures = [];@@ -115,3 +143,20 @@ it('stops deployments when a stored docker registry image value is unsafe', funcexpect(fn () => $method->invoke($job))->toThrow(DeploymentException::class);});++it('allows deployments when the stored docker registry image tag is an environment variable reference', function () {+ $job = (new ReflectionClass(ApplicationDeploymentJob::class))->newInstanceWithoutConstructor();++ $jobReflection = new ReflectionClass($job);+ foreach ([+ 'application' => new Application([+ 'docker_registry_image_name' => 'ghcr.io/user/app',+ 'docker_registry_image_tag' => '$API_VERSION',+ ]),+ 'dockerImagePreviewTag' => null,+ ] as $property => $value) {+ $jobReflection->getProperty($property)->setValue($job, $value);+ }++ $jobReflection->getMethod('validateDockerRegistryImageConfiguration')->invoke($job);+})->throwsNoExceptions();