imageproxy

https://github.com/willnorris/imageproxy
Admin
imageproxy is a caching image proxy server written in Go that provides image resizing, cropping,...
Tokens:14,877
Snippets:109
Trust Score:10
License:Apache-2.0
Update:1 month ago
Show doc for...
Tokens:
Raw
### Install imageproxy with go install

Source: https://github.com/willnorris/imageproxy/blob/main/README.md

Installs the imageproxy command-line tool. After installation, ensure $GOPATH/bin is in your $PATH before running the proxy.

```sh
go install willnorris.com/go/imageproxy/cmd/imageproxy@latest
```

--------------------------------

### Run imageproxy with default base URL

Source: https://github.com/willnorris/imageproxy/blob/main/README.md

Starts imageproxy with a base URL so remote images can be specified relative to that base. For example, loading /500/images/codercat.jpg proxies the image from the base URL. This does not mask the true source; absolute URLs still work.

```sh
imageproxy -baseURL https://octodex.github.com/
```

--------------------------------

### Run imageproxy with allowed hosts list

Source: https://github.com/willnorris/imageproxy/blob/main/README.md

Starts imageproxy with an allowlist of remote hosts it will fetch images from. Only hosts matching example.com are allowed; multiple hosts can be comma-separated, and `*.` prefixes allow subdomains. Reloading the codercat URL after this returns an error because octodex.github.com is not allowed.

```sh
imageproxy -allowHosts example.com
```

--------------------------------

### Run imageproxy server

Source: https://github.com/willnorris/imageproxy/blob/main/README.md

Starts the imageproxy server on port 8080 with no caching and no allowed host list, meaning any remote URL can be proxied. Test by navigating to http://localhost:8080/500/https://octodex.github.com/images/codercat.jpg.

```sh
imageproxy
```

--------------------------------

### Run imageproxy with allowed referrer list

Source: https://github.com/willnorris/imageproxy/blob/main/README.md

Starts imageproxy with a referrer allowlist so only requests with an HTTP Referer header matching example.com are served. Multiple hosts can be comma-separated, and a host value prefixed with `*.` allows all subdomains. After enabling, reloading the codercat URL returns an error.

```sh
imageproxy  -referrers example.com
```

--------------------------------

### OpenSSL: Generate signed request using command line

Source: https://github.com/willnorris/imageproxy/wiki/URL-signing

Uses openssl dgst with HMAC-SHA256 to sign the data with the key 'test', then base64 encodes and replaces '/' and '+' with '_' and '-' to make it URL-safe. The example produces a signature starting with 'RYif...'.

```shell
$ echo -n "https://www.google.fr/images/srpr/logo11w.png" | openssl dgst -sha256 -hmac "test" -binary|base64| tr '/+' '_-'
RYifAJRfbhsitJeOrDNxWURCCkPsVR4ihCPXNv-ePbA=
```

--------------------------------

### Run imageproxy with denied hosts list

Source: https://github.com/willnorris/imageproxy/blob/main/README.md

Starts imageproxy with a denylist of remote hosts it will not fetch images from. Requests to octodex.github.com are denied, so reloading the codercat URL returns an error. Multiple hosts can be comma-separated, and `*.` prefixes deny subdomains. If a host matches both allow and deny lists, the request is denied.

```sh
imageproxy -denyHosts octodex.github.com
```

--------------------------------

### Run imageproxy with signature key

Source: https://github.com/willnorris/imageproxy/blob/main/README.md

Starts imageproxy requiring signed requests using the given HMAC key. The key can be prefixed with `@` to load it from a file. After enabling, unsigned requests to the codercat URL return an error, while a signed URL loads properly. Multiple keys can be provided by repeating the flag or space-separated list.

```sh
imageproxy -signatureKey "secretkey"
```

--------------------------------

### Run imageproxy with scaleUp flag

Source: https://github.com/willnorris/imageproxy/blob/main/README.md

Starts imageproxy with the `scaleUp` flag to allow scaling images beyond their original size. By default, imageproxy does not scale images beyond their original size.

```sh
imageproxy -scaleUp true
```

--------------------------------

### Signed URL with valid-until option

Source: https://github.com/willnorris/imageproxy/blob/main/README.md

Example signed URL with a `vu` option specifying a Unix timestamp (1577836800) as the valid-until time. The URL is only valid until 2020-01-01.

```text
http://localhost:8080/vu1577836800,sjNcVf6LxzKEvR6Owgg3zhEMN7xbWxlpf-eyYbRfFK4A=/https://example.com/image
```

--------------------------------

### S3 cache URL for Digital Ocean Spaces

Source: https://github.com/willnorris/imageproxy/blob/main/README.md

Example S3 cache URL for Digital Ocean Spaces. Provide a dummy region value and the appropriate endpoint for your space.

```text
s3://fake-region/bucket/folder?endpoint=sfo2.digitaloceanspaces.com
```

--------------------------------

### JavaScript: Generate signed request with crypto and urlsafe-base64

Source: https://github.com/willnorris/imageproxy/wiki/URL-signing

Uses the crypto module to create an HMAC-SHA256 hash of the data with the given key, then encodes it with the URLSafeBase64 library. The example uses ES6 import and let syntax.

```javascript
import crypto from 'crypto';
import URLSafeBase64 from 'urlsafe-base64';

let key = 'secret key';
let data = 'https://octodex.github.com/images/codercat.jpg';
console.log(URLSafeBase64.encode(crypto.createHmac('sha256', key).update(data).digest()));
```

--------------------------------

### S3 cache URL for Minio

Source: https://github.com/willnorris/imageproxy/blob/main/README.md

Example S3 cache URL for Minio, which does not use regions. Provide a dummy region value and custom endpoint, with disableSSL and s3ForcePathStyle set to 1.

```text
s3://fake-region/bucket/folder?endpoint=minio:9000&disableSSL=1&s3ForcePathStyle=1
```

--------------------------------

### Go signature calculation with HMAC-SHA256

Source: https://github.com/willnorris/imageproxy/blob/main/docs/url-signing.md

Go implementation of HMAC-SHA256 signature calculation for imageproxy. The program takes the signature key and URL as command-line arguments, computes the HMAC digest, and outputs the base64url-encoded result. The shell command shows the expected output for the example URL and key.

```go
package main

import (
        "os"
        "fmt"
        "crypto/hmac"
        "crypto/sha256"
        "encoding/base64"
)

func main() {
        key, url := os.Args[1], os.Args[2]
        mac := hmac.New(sha256.New, []byte(key))
        mac.Write([]byte(url))
        result := mac.Sum(nil)
        fmt.Println(base64.URLEncoding.EncodeToString(result))
}
```

```shell
$ go run sign.go "secretkey" "https://octodex.github.com/images/codercat.jpg"
cw34eyalj8YvpLpETxSIxv2k8QkLel2UAR5Cku2FzGM=
```

--------------------------------

### Dockerfile ENTRYPOINT for imageproxy

Source: https://github.com/willnorris/imageproxy/blob/main/README.md

Sets the entrypoint for a Dockerfile to run imageproxy with the -addr flag. When using a bind-mounted on-disk cache, ensure the container runs as a user with write permission to the mounted host directory.

```Dockerfile
ENTRYPOINT ["/app/imageproxy", "-addr 0.0.0.0:8080"]
```

--------------------------------

### Run imageproxy with tiered memory and GCS caches

Source: https://github.com/willnorris/imageproxy/blob/main/README.md

Configures multiple caches in a tiered fashion, with an in-memory cache checked first followed by a GCS bucket. Caches can be separated by spaces or by repeating the -cache flag.

```sh
imageproxy -cache memory -cache gcs://my-bucket/
```

--------------------------------

### Caddy imageproxy directive with environment variables

Source: https://github.com/willnorris/imageproxy/blob/main/README.md

Caddy configuration using the imageproxy directive to run an embedded imageproxy instance. Requires a custom Caddy build with the imageproxy module. Configuration options are set via environment variables.

```Caddyfile
@imageproxy path /api/imageproxy/*
handle @imageproxy {
  uri replace /api/imageproxy/ /

  imageproxy {
    cache /data/imageproxy-cache
    default_base_url {$IMAGEPROXY_BASEURL}
    allow_hosts {$IMAGEPROXY_ALLOWHOSTS}
    signature_key {$IMAGEPROXY_SIGNATUREKEY}
  }
}
```

--------------------------------

### Run imageproxy with minimum cache duration

Source: https://github.com/willnorris/imageproxy/blob/main/README.md

Sets a minimum cache duration of 5 minutes, extending the cache duration if the response header indicates a shorter value. Without -forceCache, this has no effect on responses with no-store or private directives.

```sh
imageproxy -cache /tmp/imageproxy -minCacheDuration 5m
```

--------------------------------

### Go: Generate signed request with main.go

Source: https://github.com/willnorris/imageproxy/wiki/URL-signing

Calculates an HMAC-SHA256 signature from the provided key and data, then base64url-encodes it. The key and data are passed as command-line arguments. Output is printed as 'result: <signed>'. The code uses standard library packages only.

```go
package main

import (
        "os"
        "fmt"
        "crypto/hmac"
        "crypto/sha256"
        "encoding/base64"
)

func main() {
        mac := hmac.New(sha256.New, []byte(os.Args[1]))
        mac.Write([]byte(os.Args[2]))
        want := mac.Sum(nil)
        fmt.Println("result: ",base64.URLEncoding.EncodeToString(want))
}
```

```shell
$ go run main.go "test" "https://www.google.fr/images/srpr/logo11w.png"
result:  RYifAJRfbhsitJeOrDNxWURCCkPsVR4ihCPXNv-ePbA=
```

--------------------------------

### Plugin type and RegisterPlugin function signature

Source: https://github.com/willnorris/imageproxy/blob/main/docs/plugin-design.md

Plugins are loaded by importing their package and having an init function that calls imageproxy.RegisterPlugin. The Plugin type is a placeholder for the plugin struct, and RegisterPlugin takes a name and a Plugin instance.

```go
type Plugin struct {
}

func RegisterPlugin(name string, plugin Plugin)
```

--------------------------------

### Run imageproxy with disk cache

Source: https://github.com/willnorris/imageproxy/blob/main/README.md

Runs imageproxy with disk caching in the /tmp/imageproxy directory. After reloading the codercat URL, the cache will contain two files: the original full-size image and the resized 500px version.

```sh
imageproxy -cache /tmp/imageproxy
```

--------------------------------

### Configure on-disk cache with IMAGEPROXY_CACHE environment variable

Source: https://github.com/willnorris/imageproxy/blob/main/README.md

Sets the IMAGEPROXY_CACHE environment variable to configure an on-disk cache. All configuration flags have equivalent environment variables of the form IMAGEPROXY_$NAME.

```sh
IMAGEPROXY_CACHE="/tmp/imageproxy" imageproxy
```

--------------------------------

### Run imageproxy Docker container

Source: https://github.com/willnorris/imageproxy/blob/main/README.md

Runs the imageproxy Docker container, mapping port 8080 and setting the listen address. The image is available at ghcr.io/willnorris/imageproxy.

```sh
docker run -p 8080:8080 ghcr.io/willnorris/imageproxy -addr 0.0.0.0:8080
```

--------------------------------

### Caddy reverse_proxy for imageproxy

Source: https://github.com/willnorris/imageproxy/blob/main/README.md

Caddy configuration using the reverse_proxy directive to proxy requests to an imageproxy instance. The uri replace directive strips the /api/imageproxy/ prefix before forwarding.

```Caddyfile
@imageproxy path /api/imageproxy/*
handle @imageproxy {
  uri replace /api/imageproxy/ /
  reverse_proxy http://localhost:4593
}
```

--------------------------------

### RequestAuthorizer and ResponseAuthorizer interfaces

Source: https://github.com/willnorris/imageproxy/blob/main/docs/plugin-design.md

These interfaces allow plugins to authorize requests before the remote resource is retrieved and responses before they are returned to the client. Implement them to enforce security policies such as signature validation or host whitelisting.

```go
// A RequestAuthorizer determines if a request is authorized to be processed.
// Requests are processed before the remote resource is retrieved.
type RequestAuthorizer interface {
    // Authorize returns an error if the request should not
    // be processed further (for example, it doesn't have a
    // valid signature, is not for a whitelisted host, etc).
    AuthorizeRequest(req *http.Request) error
}

// A ResponseAuthorizer determines if a response from a remote server
// is authorized to be returned.
type ResponseAuthorizer interface {
    // AuthorizeResponse returns an error if a response should not be
    // returned to a client (for example, it is not for an image
    // resource, etc).
    AuthorizeResponse(res http.Response) error
}
```

--------------------------------

### Ruby: Generate signed request with openssl and base64

Source: https://github.com/willnorris/imageproxy/wiki/URL-signing

Requires 'openssl' and 'base64' libraries, then computes the HMAC-SHA256 digest of the data with the key 'test' and outputs the URL-safe base64 encoded result. The output is stripped of newlines and printed.

```ruby
require 'openssl'
require 'base64'

key = "test"
data = "https://www.google.fr/images/srpr/logo11w.png"
puts Base64.urlsafe_encode64(OpenSSL::HMAC.digest(OpenSSL::Digest.new('sha256'), key, data)).strip()
```

```shell
% ruby sign.rb
RYifAJRfbhsitJeOrDNxWURCCkPsVR4ihCPXNv-ePbA=
```

--------------------------------

### ImageTransformer interface

Source: https://github.com/willnorris/imageproxy/blob/main/docs/plugin-design.md

A hypothetical interface for plugins that transform images. Implement TransformImage to apply transformations based on the provided options and return the resulting image.

```go
// An ImageTransformer transforms an image.
type ImageTransformer interface {
   // TransformImage based on the provided options and return the result.
   TransformImage(m image.Image, opt Options) image.Image
}
```

--------------------------------

### PHP: Generate signed request with hash_hmac

Source: https://github.com/willnorris/imageproxy/wiki/URL-signing

Computes the HMAC-SHA256 hash of the data with the key 'test' and then converts the base64 output to URL-safe by replacing '/' and '+' with '_' and '-'. Prints the resulting signature.

```php
<?php
$key = 'test';
$data = "https://www.google.fr/images/srpr/logo11w.png";
echo strtr(base64_encode(hash_hmac('sha256', $data, $key, 1)), '/+' , '_-');
```

```shell
$ php ex.php
RYifAJRfbhsitJeOrDNxWURCCkPsVR4ihCPXNv-ePbA=
```

--------------------------------

### Java: Generate signed request with EncodeUrl class

Source: https://github.com/willnorris/imageproxy/wiki/URL-signing

Defines an EncodeUrl class with an encode method that computes the HmacSHA256 signature and returns a base64url-safe string. The main method takes the key and data as command-line arguments and prints the result. Requires the Apache Commons Codec library.

```java
import org.apache.commons.codec.binary.Base64;
import javax.crypto.Mac;
import javax.crypto.spec.SecretKeySpec;

class EncodeUrl {

  public static String encode(String key, String data) throws Exception {
    Mac sha256_HMAC = Mac.getInstance("HmacSHA256");
    SecretKeySpec secret_key = new SecretKeySpec(key.getBytes(), "HmacSHA256");
    sha256_HMAC.init(secret_key);

    return Base64.encodeBase64URLSafeString(sha256_HMAC.doFinal(data.getBytes()));
  }

  public static void main(String [] args) throws Exception {
    System.out.println(encode(args[0], args[1]));
  }

}
```

```shell
$ java -cp commons-codec-1.10.jar:. EncodeUrl test https://www.google.fr/images/srpr/logo11w.png
RYifAJRfbhsitJeOrDNxWURCCkPsVR4ihCPXNv-ePbA
```

--------------------------------

### OpenSSL signature calculation

Source: https://github.com/willnorris/imageproxy/blob/main/docs/url-signing.md

OpenSSL command-line method to compute the HMAC-SHA256 signature. It pipes the URL to openssl dgst with the secret key, then converts the binary output to base64 and replaces '/' and '+' with '_' and '-' for URL-safe encoding. The output matches the expected signature.

```shell
$ echo -n "https://octodex.github.com/images/codercat.jpg" | openssl dgst -sha256 -hmac "secretkey" -binary|base64| tr '/+' '_-'
cw34eyalj8YvpLpETxSIxv2k8QkLel2UAR5Cku2FzGM=
```

--------------------------------

### Python: Generate signed request with hmac and hashlib

Source: https://github.com/willnorris/imageproxy/wiki/URL-signing

Uses the hmac module to create a signature using the SHA256 digest, then base64url-encodes the digest. The key is 'secret key' and the data is a sample URL. Note: this code uses the print statement as in Python 2.

```python
import hmac
import hashlib
import base64

key = 'secret key'
data = 'https://octodex.github.com/images/codercat.jpg'
print base64.urlsafe_b64encode(hmac.new(key, msg=data, digestmod=hashlib.sha256).digest())
```

--------------------------------

### JavaScript signature calculation with crypto

Source: https://github.com/willnorris/imageproxy/blob/main/docs/url-signing.md

Node.js script that uses the crypto module to create an HMAC-SHA256 signature and the urlsafe-base64 package to encode it. It reads the key and URL from command-line arguments. The shell command shows the expected output.

```javascript
const crypto = require("crypto");
const URLSafeBase64 = require("urlsafe-base64");

let key = process.argv[2];
let url = process.argv[3];
console.log(
  URLSafeBase64.encode(crypto.createHmac("sha256", key).update(url).digest()),
);
```

```shell
$ node sign.js "secretkey" "https://octodex.github.com/images/codercat.jpg"
cw34eyalj8YvpLpETxSIxv2k8QkLel2UAR5Cku2FzGM=
```

--------------------------------

### Java signature calculation with HmacSHA256

Source: https://github.com/willnorris/imageproxy/blob/main/docs/url-signing.md

Java class that signs a URL using HmacSHA256 and returns the base64url-encoded signature. The main method accepts the key and URL as command-line arguments. The shell command compiles and runs the class, producing the expected signature.

```java
import java.util.Base64;
import javax.crypto.Mac;
import javax.crypto.spec.SecretKeySpec;

class SignUrl {

  public static String sign(String key, String url) throws Exception {
    Mac sha256_HMAC = Mac.getInstance("HmacSHA256");
    SecretKeySpec secret_key = new SecretKeySpec(key.getBytes(), "HmacSHA256");
    sha256_HMAC.init(secret_key);

    return Base64.getUrlEncoder().encodeToString(sha256_HMAC.doFinal(url.getBytes()));
  }

  public static void main(String [] args) throws Exception {
    System.out.println(sign(args[0], args[1]));
  }

}
```

```shell
$ javac SignUrl.java && java SignUrl "secretkey" "https://octodex.github.com/images/codercat.jpg"
cw34eyalj8YvpLpETxSIxv2k8QkLel2UAR5Cku2FzGM=
```

--------------------------------

### Python signature calculation with hmac

Source: https://github.com/willnorris/imageproxy/blob/main/docs/url-signing.md

Python script that signs a URL using HMAC-SHA256 and prints the URL-safe base64 encoded digest. It takes the key and URL as command-line arguments. The shell command shows the expected output.

```python
import base64
import hashlib
import hmac
import sys

key = sys.argv[1]
url = sys.argv[2]
print base64.urlsafe_b64encode(hmac.new(key, msg=url, digestmod=hashlib.sha256).digest())
```

```shell
$ python sign.py "secretkey" "https://octodex.github.com/images/codercat.jpg"
cw34eyalj8YvpLpETxSIxv2k8QkLel2UAR5Cku2FzGM=
```

--------------------------------

### Ruby signature calculation with OpenSSL

Source: https://github.com/willnorris/imageproxy/blob/main/docs/url-signing.md

Ruby script that computes the HMAC-SHA256 signature using OpenSSL and outputs the URL-safe base64 encoded digest. It reads the key and URL from command-line arguments. The shell command shows the expected output.

```ruby
require 'openssl'
require 'base64'

key = ARGV[0]
url = ARGV[1]
puts Base64.urlsafe_encode64(OpenSSL::HMAC.digest(OpenSSL::Digest.new('sha256'), key, url)).strip()
```

```shell
% ruby sign.rb "secretkey" "https://octodex.github.com/images/codercat.jpg"
cw34eyalj8YvpLpETxSIxv2k8QkLel2UAR5Cku2FzGM=
```

--------------------------------

### nginx proxy_pass for imageproxy

Source: https://github.com/willnorris/imageproxy/blob/main/README.md

nginx configuration using the proxy_pass directive to send requests to an imageproxy instance at the path /api/imageproxy/.

```nginx
location /api/imageproxy/ {
  proxy_pass http://localhost:4593/;
}
```

--------------------------------

### Signature generation formula

Source: https://github.com/willnorris/imageproxy/blob/main/README.md

Formula for generating a request signature: HMAC-SHA256 of the remote URL using the configured key, then url-safe base64 encoding. This signature is used with the `signatureKey` flag to require signed requests.

```text
base64urlencode(hmac.New(sha256, <key>).digest(<remote_url>))
```

--------------------------------

### PHP signature calculation with hash_hmac

Source: https://github.com/willnorris/imageproxy/blob/main/docs/url-signing.md

PHP script that computes the HMAC-SHA256 signature using hash_hmac and converts the base64 output to URL-safe characters. It takes the key and URL from command-line arguments. The shell command shows the expected output.

```php
<?php

$key = $argv[1];
$url = $argv[2];
echo strtr(base64_encode(hash_hmac('sha256', $url, $key, 1)), '/+' , '_-');
```

```shell
$ php sign.php "secretkey" "https://octodex.github.com/images/codercat.jpg"
cw34eyalj8YvpLpETxSIxv2k8QkLel2UAR5Cku2FzGM=
```

--------------------------------

### nginx proxy_pass with precedence modifier

Source: https://github.com/willnorris/imageproxy/blob/main/README.md

nginx configuration with the ^~ modifier to alter precedence order for the /api/imageproxy/ location. Use this if other directives in the nginx config affect precedence.

```nginx
location ^~ /api/imageproxy/ {
  proxy_pass http://localhost:4593/;
}
```
Tokens:
Raw