Add IMGPROXY_SOURCE_URL_QUERY_SEPARATOR docs

imgproxy · Jan 7, 2025 · 06b6143 · 06b6143
1 parent ce3097f
commit 06b6143
Show file tree

Hide file tree

Showing 6 changed files with 38 additions and 0 deletions.
diff --git a/docs/configuration/options.mdx b/docs/configuration/options.mdx
@@ -431,6 +431,12 @@ imgproxy can be switched into "presets-only mode". In this mode, imgproxy accept
 
 ## Image sources
 
+* [`IMGPROXY_SOURCE_URL_QUERY_SEPARATOR`]: a string that will be used as a separator between non-HTTP(S) source URLs' paths and their query strings. When blank, imgproxy won't extract query string from non-HTTP(S) source URLs. Default: `?`
+
+:::tip
+If filenames in your S3/Google Cloud Storage/local filesystem/etc may contain `?`, you may want to set `IMGPROXY_SOURCE_URL_QUERY_SEPARATOR` to another string that is not used in filenames or set it to blank to disable query string extraction.
+:::
+
 ### Local files {#serving-local-files}
 
 imgproxy can serve your local images, but this feature is disabled by default. To enable it, specify your local filesystem root:

diff --git a/docs/image_sources/amazon_s3.mdx b/docs/image_sources/amazon_s3.mdx
@@ -22,6 +22,16 @@ If you need to specify the version of the source object, you can use the query s
 s3://%bucket_name/%file_key?%version_id
 ```
 
+:::tip
+If filenames in your S3 may contain `?`, you may want to set [IMGPROXY_SOURCE_URL_QUERY_SEPARATOR](../configuration/options.mdx#IMGPROXY_SOURCE_URL_QUERY_SEPARATOR) to another string that is not used in filenames or set it to blank to disable query string extraction.
+
+For example, if you set `IMGPROXY_SOURCE_URL_QUERY_SEPARATOR` to `?version=`, you can specify the version like this:
+
+```
+s3://%bucket_name/%file_key?version=%version_id
+```
+:::
+
 ### Set up credentials
 
 There are three ways to specify your AWS credentials. The credentials need to have read rights for all of the buckets given in the source URLs:

diff --git a/docs/image_sources/azure_blob_storage.mdx b/docs/image_sources/azure_blob_storage.mdx
@@ -12,6 +12,10 @@ imgproxy can process images from Azure Blob Storage containers. To use this feat
 4. _(optional)_ Specify the Azure Blob Storage endpoint with `IMGPROXY_ABS_ENDPOINT`
 5. Use `abs://%bucket_name/%file_key` as the source image URL
 
+:::tip
+If filenames in your Azure Blob Storage may contain `?`, you may want to set [IMGPROXY_SOURCE_URL_QUERY_SEPARATOR](../configuration/options.mdx#IMGPROXY_SOURCE_URL_QUERY_SEPARATOR) to another string that is not used in filenames or set it to blank to disable query string extraction.
+:::
+
 ## Set up credentials
 
 ### Leverage Azure Managed Identity or Service Principal

diff --git a/docs/image_sources/google_cloud_storage.mdx b/docs/image_sources/google_cloud_storage.mdx
@@ -17,6 +17,16 @@ If you need to specify generation of the source object, you can use the query st
 gs://%bucket_name/%file_key?%generation
 ```
 
+:::tip
+If filenames in your Google Cloud Storage may contain `?`, you may want to set [IMGPROXY_SOURCE_URL_QUERY_SEPARATOR](../configuration/options.mdx#IMGPROXY_SOURCE_URL_QUERY_SEPARATOR) to another string that is not used in filenames or set it to blank to disable query string extraction.
+
+For example, if you set `IMGPROXY_SOURCE_URL_QUERY_SEPARATOR` to `?generation=`, you can specify the generation like this:
+
+```
+gs://%bucket_name/%file_key?generation=%generation
+```
+:::
+
 ### Setup credentials
 
 If you run imgproxy inside Google Cloud infrastructure (Compute Engine, Kubernetes Engine, App Engine, and Cloud Functions, etc), and you have granted access to your bucket to the service account, you probably don't need to do anything here. imgproxy will try to use the credentials provided by Google.

diff --git a/docs/image_sources/local_files.mdx b/docs/image_sources/local_files.mdx
@@ -9,6 +9,10 @@ imgproxy can be configured to process files from your local filesystem. To use t
 1. Set `IMGPROXY_LOCAL_FILESYSTEM_ROOT` environment variable to your local images directory path.
 2. Use `local:///path/to/image.jpg` as the source image URL.
 
+:::tip
+If filenames in your local filesystem may contain `?`, you may want to set [IMGPROXY_SOURCE_URL_QUERY_SEPARATOR](../configuration/options.mdx#IMGPROXY_SOURCE_URL_QUERY_SEPARATOR) to another string that is not used in filenames or set it to blank to disable query string extraction.
+:::
+
 ### Example
 
 Assume you want to process an image that is stored locally at `/path/to/project/images/logos/imgproxy.png`. Run imgproxy with `IMGPROXY_LOCAL_FILESYSTEM_ROOT` set to your images directory:

diff --git a/docs/image_sources/openstack_swift.mdx b/docs/image_sources/openstack_swift.mdx
@@ -16,3 +16,7 @@ imgproxy can process images from OpenStack Object Storage, also known as Swift.
    * `IMGPROXY_SWIFT_DOMAIN`: the Swift domain name (optional, v3 auth only): Default: blank
 
 3. Use `swift://%{container}/%{object_path}` as the source image URL, e.g. an original object storage URL in the format of `/v1/{account}/{container}/{object_path}`, such as `http://127.0.0.1:8080/v1/AUTH_test/images/flowers/rose.jpg`, should be converted to `swift://images/flowers/rose.jpg`.
+
+:::tip
+If filenames in your OpenStack Object Storage may contain `?`, you may want to set [IMGPROXY_SOURCE_URL_QUERY_SEPARATOR](../configuration/options.mdx#IMGPROXY_SOURCE_URL_QUERY_SEPARATOR) to another string that is not used in filenames or set it to blank to disable query string extraction.
+:::