pict-rs/pict-rs.toml

## Server configuration
[server]
## Optional: pict-rs binding address
# environment variable: PICTRS__SERVER__ADDRESS
# default: 0.0.0.0:8080
address = '0.0.0.0:8080'

## Optional: whether to reject any operations that would change the state of pict-rs.
# environment variable: PICTRS__SERVER__READ_ONLY
# default: false
#
# This can be useful if you need to run a copy of pict-rs while performing maintenance.
read_only = false

## Optional: whether to run pict-rs without dependencies.
# environment variable: PICTRS__SERVER__DANGER_DUMMY_MODE
# default: false
#
# This means pict-rs will not be able to inspect metadata of uploaded media, or perform processing
# on it. This mode is provided for use in test environments. It should not be used in production.
danger_dummy_mode = false

## Optional: shared secret for internal endpoints
# environment variable: PICTRS__SERVER__API_KEY
# default: empty
#
# Not specifying api_key disables internal endpoints
api_key = 'API_KEY'

## Optional: How many files are allowed to be uploaded per request
# environment variable: PICTRS__SERVER__MAX_FILE_COUNT
# default: 1
max_file_count = 1

## Optional: directory pict-rs will use to create temporary files
# environment variable: PICTRS__SERVER__TEMPORARY_DIRECTORY
# default: The system's advertised temporary directory ("/tmp" on most linuxes)
temporary_directory = "/tmp"

## Optional: whether to delete the contents of $temporary_directory/pict-rs on launch
# environment variable: PICTRS__SERVER__CLEANUP_TEMPORARY_DIRECTORY
# default: true
cleanup_temporary_directory = true

## Optional: path to server certificate to enable TLS
# environment variable: PICTRS__SERVER__CERTIFICATE
# default: empty
#
# Note that both certificate and private_key must be set to enable TLS
certificate = "/path/to/server.crt"

## Optional: path to server key to enable TLS
# environment variable: PICTRS__SERVER__PRIVATE_KEY
# default: empty
#
# Note that both private_key and certificate must be set to enable TLS
private_key = "/path/to/server.key"

## Client configuration
[client]
## Optional: time (in seconds) the client will wait for a response before giving up
# environment variable: PICTRS__CLIENT__TIMEOUT
# default: 30
#
# This is used for the `/image/download` endpoint when fetching media from another server. It is
# distinct from the object storage client timeout, which can be configured separately
timeout = 30

[upgrade]
## Optional: How many hashes will be migrated from the previous version of pict-rs at the same time
# environment variable: PICTRS__UPGRADE__CONCURRENCY
# default: 32
#
# Increasing this value will increase the number of concurrent connections to the Repo, and to the
# Store, so make sure your deployment can handle more throughput before tweaking this.
concurrency = 32


## Logging configuration
[tracing.logging]
## Optional: log format
# environment variable: PICTRS__TRACING__LOGGING__FORMAT
# default: normal
#
# available options: compact, json, normal, pretty
format = 'normal'

## Optional: log targets
# environment variable: PICTRS__TRACING__LOGGING__TARGETS
# default: info
#
# Dictates which traces should print to stdout
# Follows the same format as RUST_LOG
targets = 'info'

## Optional: whether pict-rs should log the new & close span events for tracing spans to stdout
# environment variable: PICTRS__TRACING__LOGGING__LOG_SPANS
# default: false
log_spans = false


## Console configuration
[tracing.console]
## Optional: console address
# environment variable: PICTRS__TRACING__CONSOLE__ADDRESS
# default: empty
#
# Dictates whether console should be enabled, and what address it should be exposed on.
#
# When set, tokio-console can connect to the pict-rs service
#
# Configure your container to expose the console port
# ```
# # docker-compose.yml
# version: '3.3'
#
# services:
#   pictrs:
#     image: asonix/pictrs:0.4.1
#     ports:
#       - "127.0.0.1:8080:8080"
#       - "127.0.0.1:6669:6669" # this is the line that exposes console
#     restart: always
#     volumes:
#       - ./volumes/pictrs:/mnt
# ```
#
# Connect from console
# ```
# $ tokio-console http://localhost:6669
# ```
address = '0.0.0.0:6669'

## Optional: console buffer capacity
# environment variable: PICTRS__TRACING__CONSOLE__BUFFER_CAPACITY
# default: 102400
#
# This is the number of _events_ to buffer, not the number of bytes. In reality, the amount of
# RAM used will be significatnly larger (in bytes) than the buffer capacity (in events)
buffer_capacity = 102400


## OpenTelemetry configuration
[tracing.opentelemetry]
## Optional: url for exporting otlp traces
# environment variable: PICTRS__TRACING__OPENTELEMETRY__URL
# default: empty
#
# Not specifying opentelemetry_url means no traces will be exported
# When set, pict-rs will export OpenTelemetry traces to the provided URL. If the URL is
# inaccessible, this can cause performance degredation in pict-rs, so it is best left unset unless
# you have an OpenTelemetry collector
url = 'http://localhost:4317/'

## Optional: name to relate OpenTelemetry traces
# environment variable: PICTRS__TRACING__OPENTELEMETRY__SERVICE_NAME
# default: pict-rs
service_name = 'pict-rs'

## Optional: trace level to export
# environment variable: PICTRS__TRACING__OPENTELEMETRY__TARGETS
# default: info
#
# Follows the same format as RUST_LOG
targets = 'info'

[metrics]
## Optional: enable a prometheus scrape endpoint for pict-rs
# environment variable: PICTRS__METRICS__PROMETHEUS_ADDRESS
# default: empty
#
# Setting this value enables pointing prometheus at pict-rs to receive metrics. It can also be
# queried with curl.
prometheus_address = "0.0.0.0:9000"


## Configuration for migrating from pict-rs 0.4
[old_repo]
## Optional: path to sled repository
# environment variable: PICTRS__OLD_REPO__PATH
# default: /mnt/sled-repo
path = '/mnt/sled-repo'


## Media Processing Configuration
[media]
## Optional: URL for external validation of media
# environment variable: PICTRS__MEDIA__EXTERNAL_VALIDATION
# default: empty
#
# The expected API for external validators is to accept a POST with the media as the request body,
# and a valid `Content-Type` header. The validator should return a 2XX response when the media
# passes validation. Any other status code is considered a validation failure.
external_validation = 'http://localhost:8076'

## Optional: max file size (in Megabytes)
# environment variable: PICTRS__MEDIA__MAX_FILE_SIZE
# default: 40
max_file_size = 40

## Optional: Timeout (in seconds) for all spawned media processing operations
# environment variable: PICTRS__MEDIA__PROCESS_TIMEOUT
# default: 30
process_timeout = 30

## Optional: preprocessing steps for uploaded images
# environment variable: PICTRS__MEDIA__PREPROCESS_STEPS
# default: empty
#
# This configuration is the same format as the process endpoint's query arguments
preprocess_steps = 'crop=16x9&resize=1200&blur=0.2'

## Optional: set allowed filters for image processing
# environment variable: PICTRS__MEDIA__FILTERS
# default: ['blur', 'crop', 'identity', 'resize', 'thumbnail']
filters = ['blur', 'crop', 'identity', 'resize', 'thumbnail']


[media.retention]
## Optional: retention period for image variants
# environment variable: PICTRS__MEDIA__RETENTION__VARIANTS
# default: 7d
#
# Variants are any image served from the process.{ext} endpoint. These images are generated based on
# an original upload, and can be regenerated when needed. The retention period is after last access
# rather than after generation, so a value of "7d" means "7 days after the last access of this
# variant"
#
# Available units are
# - m (minutes)
# - h (hours)
# - d (days)
# - y (years)
variants = "7d"

## Optional: retention period for proxied images
# environment variable: PICTRS__MEDIA__RETENTION__PROXY
# default: 7d
#
# Proxied images reside originally on other servers, and can be re-fetched if needed. The retention
# period is after last access rather than after fetch, so a value of "7d" means "7 days after the
# last access of this image"
#
# Available units are
# - m (minutes)
# - h (hours)
# - d (days)
# - y (years)
proxy = "7d"


[media.magick]
## Optional: maximum width, in pixels, of media that imagemagick will attempt to process
# environment variable: PICTRS__MEDIA__MAGICK__MAX_WIDTH
# default: 10_000
#
# This value should be at least as large as the greatest max_width set for images, animations, and
# videos. Any image that exceeds this limit will cause imagemagick to abort processing, which could
# lead to less clear errors, especially on image upload. In order for pict-rs to return helpful
# validation errors for images that don't meet other requirements, imagemagick must be allowed to
# process the image.
max_width = 10000

## Optional: maximum height, in pixels, of media that imagemagick will attempt to process
# environment variable: PICTRS__MEDIA__MAGICK__MAX_HEIGHT
# default: 10_000
#
# This value should be at least as large as the greatest max_height set for images, animations, and
# videos. Any image that exceeds this limit will cause imagemagick to abort processing, which could
# lead to less clear errors, especially on image upload. In order for pict-rs to return helpful
# validation errors for images that don't meet other requirements, imagemagick must be allowed to
# process the image.
max_height = 10000

## Optional: maximum area, in pixels, of media that imagemagick will keep in memory at a time
# environment variable: PICTRS__MEDIA__MAGICK__MAX_HEIGHT
# default: 20_000
#
# Images that exceed this area will have their pixels cached to disk
max_area = 20000

## Optional: maximum size, in MiB, that imagemagick is allowed to allocate in memory to store pixels
## while processing media.
# environment variable: PICTRS__MEDIA__MAGICK__MEMORY
# default: 256
#
# If this limit is exceeded, imagemagick will fall back to memory-mapped disk for storing pixels
memory = 256

## Optional: maximim size, in MiB, that imagemagick is allowed to allocate in memory-mapped disk to
## store pixels while processing media
# environment variable: PICTRS__MEDIA__MAGICK__MAP
# default: 512
#
# If this limit is exceeded, imagemagick will fall back to unmapped disk for storing pixels
map = 512

## Optional: maximum size, in MiB, that imagemagick is allowed to allocate on disk to store pixels
## while processing media
# environment variable: PICTRS__MEDIA__MAGICK__DISK
# default: 1024
#
# If this limit is exceeded, media processing will be aborted
disk = 1024


[media.image]
## Optional: max media width (in pixels)
# environment variable: PICTRS__MEDIA__IMAGE__MAX_WIDTH
# default: 10,000
max_width = 10000

## Optional: max media height (in pixels)
# environment variable: PICTRS__MEDIA__IMAGE__MAX_HEIGHT
# default: 10,000
max_height = 10000

## Optional: max media area (in pixels)
# environment variable: PICTRS__MEDIA__IMAGE__MAX_AREA
# default: 40,000,000
max_area = 40000000

## Optional: max file size (in Megabytes)
# environment variable: PICTRS__MEDIA__IMAGE__MAX_FILE_SIZE
# default: 40
max_file_size = 40

## Optional: set file type for all images
# environment variable: PICTRS__MEDIA__IMAGE__FORMAT
# default: empty
#
# available options: avif, png, jpeg, jxl, webp
# When set, all uploaded still images will be converted to this file type. For balancing quality vs
# file size vs browser support, 'avif', 'jxl', and 'webp' should be considered. By default, images
# are stored in their original file type.
format = "webp"


[media.image.quality]
## Optional: set quality for AVIF images
# environment variable : PICTRS__MEDIA__IMAGE__QUALITY__AVIF
# default: empty
#
# availabe range: 0-100
# 100 means best quality and 0 means worst quality. Playing with numbers between 40 and 100 makes
# the most sense.
avif = 100

## Optional: set compression for PNG images
# environment variable : PICTRS__MEDIA__IMAGE__QUALITY__PNG
# default: empty
#
# availabe range: 0-100
# 100 means best compression and 0 means worst compression. Since PNG is a lossless format, changing
# this value will not change how the images look.
png = 100

## Optional: set quality for JPEG images
# environment variable : PICTRS__MEDIA__IMAGE__QUALITY__JPEG
# default: empty
#
# availabe range: 0-100
# 100 means best quality and 0 means worst quality. Playing with numbers between 60 and 100 makes
# the most sense.
jpeg = 100

## Optional: set quality for JXL images
# environment variable : PICTRS__MEDIA__IMAGE__QUALITY__JXL
# default: empty
#
# availabe range: 0-100
# 100 means best quality and 0 means worst quality. Playing with numbers between 40 and 100 makes
# the most sense.
jxl = 100

## Optional: set quality for WEBP images
# environment variable : PICTRS__MEDIA__IMAGE__QUALITY__WEBP
# default: empty
#
# availabe range: 0-100
# 100 means best quality and 0 means worst quality. Playing with numbers between 50 and 100 makes
# the most sense.
webp = 100


[media.animation]
## Optional: max animation width (in pixels)
# environment variable: PICTRS__MEDIA__ANIMATION__MAX_WIDTH
# default: 1920
max_width = 1920

## Optional: max animation height (in pixels)
# environment variable: PICTRS__MEDIA__ANIMATION__MAX_HEIGHT
# default: 1920
max_height = 1920

## Optional: max animation area (in pixels)
# environment variable: PICTRS__MEDIA__ANIMATION__MAX_AREA
# default: 2,073,600
max_area = 2073600

## Optional: max animation size (in Megabytes)
# environment variable: PICTRS__MEDIA__ANIMATION__MAX_FILE_SIZE
# default: 40
max_file_size = 40

## Optional: max frame count
# environment variable: PICTRS__MEDIA__ANIMATION__MAX_FRAME_COUNT
# default: 100
max_frame_count = 900

## Optional: set file type for all animations
# environment variable: PICTRS__MEDIA__ANIMATION__FORMAT
# default: empty
#
# available options: apng, avif, gif, webp
# When set, all uploaded animated images will be converted to this file type. For balancing quality
# vs file size vs browser support, 'avif', 'jxl', and 'webp' should be considered. By default,
# images are stored in their original file type.
format = "webp"


[media.animation.quality]
## Optional: set compression for APNG animations
# environment variable : PICTRS__MEDIA__ANIMATION__QUALITY__APNG
# default: empty
#
# availabe range: 0-100
# 100 means best compression and 0 means worst compression. Since APNG is a lossless format,
# changing this value will not change how the animations look.
apng = 100

## Optional: set quality for AVIF animations
# environment variable : PICTRS__MEDIA__ANIMATION__QUALITY__AVIF
# default: empty
#
# availabe range: 0-100
# 100 means best quality and 0 means worst quality. Playing with numbers between 40 and 100 makes
# the most sense.
avif = 100

## Optional: set quality for WEBP animations
# environment variable : PICTRS__MEDIA__ANIMATION__QUALITY__WEBP
# default: empty
#
# availabe range: 0-100
# 100 means best quality and 0 means worst quality. Playing with numbers between 50 and 100 makes
# the most sense.
webp = 100


[media.video]
## Optional: enable MP4 and WEBM uploads (without sound)
# environment variable: PICTRS__MEDIA__VIDEO__ENABLE
# default: true
#
# Set this to false to serve static images only
enable = true

## Optional: enable Sound for MP4 and WEBM uploads
# environment variable: PICTRS__MEDIA__VIDEO__ALLOW_AUDIO
# default: false
#
# this setting does nothing if video is not enabled
allow_audio = false

## Optional: max video width (in pixels)
# environment variable: PICTRS__MEDIA__VIDEO__MAX_WIDTH
# default: 3,840
#
# this setting does nothing if video is not enabled
max_width = 3840

## Optional: max video height (in pixels)
# environment variable: PICTRS__MEDIA__VIDEO__MAX_HEIGHT
# default: 3,840
#
# this setting does nothing if video is not enabled
max_height = 3840

## Optional: max video area (in pixels)
# environment variable: PICTRS__MEDIA__VIDEO__MAX_AREA
# default: 8,294,400
#
# this setting does nothing if video is not enabled
max_area = 8294400

## Optional: max video size (in Megabytes)
# environment variable: PICTRS__MEDIA__VIDEO__MAX_FILE_SIZE
# default: 40
#
# this setting does nothing if video is not enabled
max_file_size = 40

## Optional: max frame count
# environment variable: PICTRS__MEDIA__VIDEO__MAX_FRAME_COUNT
# default: 900
#
# this setting does nothing if video is not enabled
max_frame_count = 900

## Optional: set the default video codec
# environment variable: PICTRS__MEDIA__VIDEO__VIDEO_CODEC
# default: empty
#
# available options: av1, h264, h265, vp8, vp9
# this setting does nothing if video is not enabled
video_codec = "vp9"

## Optional: set the default audio codec
# environment variable: PICTRS__MEDIA__VIDEO__AUDIO_CODEC
# default: empty
#
# available options: aac, opus, vorbis
# The audio codec is automatically selected based on video codec, but can be overriden to `vorbis`
# for webm uploads
# automatic mappings:
# - av1, vp8, and vp9 map to opus
# - h264 and h265 map to aac
# - vorbis is not default for any codec
# this setting does nothing if full video is not enabled
audio_codec = "opus"


[media.video.quality]
## Optional: set maximum quality for all videos
# environment variable: PICTRS__MEDIA__VIDEO__QUALITY__CRF_MAX
# default: 32
#
# This value means different things for different video codecs:
# - it ranges from 0 to 63 for AV1
# - it ranges from 4 to 63 for VP8
# - it ranges from 0 to 63 for VP9
# - it ranges from 0 to 51 for H265
# - it ranges from 0 to 51 for 8bit H264
# - it ranges from 0 to 63 for 10bit H264
#
# A lower value (closer to 0) is higher quality, while a higher value (closer to 63) is lower
# quality. Generally acceptable ranges are 15-38, where lower values are preferred for larger
# videos
#
# This value may be overridden for some videos depending on whether other crf configurations are set
# For example, if crf_max is set to 32 and crf_720 is set to 34, then all videos smaller than or
# equal to 720p video will be encoded with a `crf` of 34, while all videos larger than 720p will be
# encoded with a `crf` of 32
#
# The example values here are taken from a google document about reasonable CRF values for VP9
# video. More information about `crf` can be found on ffmpeg's wiki
# 
# - AV1: https://trac.ffmpeg.org/wiki/Encode/AV1#ConstantQuality
# - H264: https://trac.ffmpeg.org/wiki/Encode/H.264#crf
# - H265: https://trac.ffmpeg.org/wiki/Encode/H.265#ConstantRateFactorCRF
# - VP8: https://trac.ffmpeg.org/wiki/Encode/H.265#ConstantRateFactorCRF
# - VP9: https://trac.ffmpeg.org/wiki/Encode/VP9#constantq
crf_max = 12

## Optional: set quality for videos up to 240p
# environment variable: PICTRS__MEDIA__VIDEO__QUALITY__CRF_240
# default: empty
#
# This value overrides `crf_max` for videos with a smaller dimension of at most 240px (240p)
crf_240 = 37

## Optional: set quality for videos up to 360p
# environment variable: PICTRS__MEDIA__VIDEO__QUALITY__CRF_360
# default: empty
#
# This value overrides `crf_max` for videos with a smaller dimension of at most 360px (260p)
crf_360 = 36

## Optional: set quality for videos up to 480p
# environment variable: PICTRS__MEDIA__VIDEO__QUALITY__CRF_480
# default: empty
#
# This value overrides `crf_max` for videos with a smaller dimension of at most 480px (480p)
crf_480 = 33

## Optional: set quality for videos up to 720p
# environment variable: PICTRS__MEDIA__VIDEO__QUALITY__CRF_720
# default: empty
#
# This value overrides `crf_max` for videos with a smaller dimension of at most 720px (720p)
crf_720 = 32

## Optional: set quality for videos up to 1080p
# environment variable: PICTRS__MEDIA__VIDEO__QUALITY__CRF_1080
# default: empty
#
# This value overrides `crf_max` for videos with a smaller dimension of at most 1080px (1080p)
crf_1080 = 31

## Optional: set quality for videos up to 1440p
# environment variable: PICTRS__MEDIA__VIDEO__QUALITY__CRF_1440
# default: empty
#
# This value overrides `crf_max` for videos with a smaller dimension of at most 1440px (1440p)
crf_1440 = 24

## Optional: set quality for videos up to 4K
# environment variable: PICTRS__MEDIA__VIDEO__QUALITY__CRF_2160
# default: empty
#
# This value overrides `crf_max` for videos with a smaller dimension of at most 2160px (4K)
crf_2160 = 15


### Database configuration

## Sled repo configuration example
[repo]
## Optional: database backend to use
# environment variable: PICTRS__REPO__TYPE
# default: sled
#
# available options: sled, postgres
type = 'sled'

## Optional: path to sled repository
# environment variable: PICTRS__REPO__PATH
# default: /mnt/sled-repo
path = '/mnt/sled-repo'

## Optional: in-memory cache capacity for sled data (in bytes)
# environment variable: PICTRS__REPO__CACHE_CAPACITY
# default: 67,108,864 (1024 * 1024 * 64, or 64MB)
cache_capacity = 67108864

## Optional: path for storing database exports
# environment variable: PICTRS__REPO__EXPORT_PATH
# default: /mnt/exports
#
# Used in combination with the /internal/export endpoint to dump the current sled database into a
# new file. This can be helpful for backing up a running pict-rs server.
export_path = "/mnt/exports"


## Postgres repo configuration example
[repo]
## Optional: database backend to use
# environment variable: PICTRS__REPO__TYPE
# default: sled
#
# available options: sled, postgres
type = 'postgres'

## Required: URL to postgres database
# environment variable: PICTRS__REPO__URL
# default: empty
url = 'postgres://user:password@host:5432/db'

## Optional: Whether to use TLS when connecting to postgres
# environment variable: PICTRS__REPO__USE_TLS
# default: false
use_tls = false

## Optional: The CA Certificate used to verify the postgres TLS certificate
# environment variable: PICTRS__REPO__CERTIFICATE_FILE
# default: empty
certificate_file = '/etc/ca-certificate.crt'


### Media storage configuration

## Filesystem media storage example
[store]
## Optional: type of media storage to use
# environment variable: PICTRS__STORE__TYPE
# default: filesystem
#
# available options: filesystem, object_storage
type = 'filesystem'

## Optional: path to uploaded media
# environment variable: PICTRS__STORE__PATH
# default: /mnt/files
path = '/mnt/files'


## Object media storage example
[store]
## Optional: type of media storage to use
# environment variable: PICTRS__STORE__TYPE
# default: filesystem
#
# available options: filesystem, object_storage
type = 'object_storage'

## Required: endpoint at which the object storage exists
# environment variable: PICTRS__STORE__ENDPOINT
# default: empty
#
# examples:
# - `http://localhost:9000` # minio
# - `https://s3.dualstack.eu-west-1.amazonaws.com` # s3
endpoint = 'http://minio:9000'

## Optional: How to format object storage requests
# environment variable: PICTRS__STORE__USE_PATH_STYLE
# default: false
#
# When this is true, objects will be fetched from http{s}://{endpoint}:{port}/{bucket_name}/{object}
# When false, objects will be fetched from http{s}://{bucket_name}.{endpoint}:{port}/{object}
#
# Set to true when using minio
use_path_style = false

## Required: object storage bucket name
# environment variable: PICTRS__STORE__BUCKET_NAME
# default: empty
bucket_name = 'pict-rs'

## Required: object storage region
# environment variable: PICTRS__STORE__REGION
# default: empty
#
# When using minio, this can be set to `minio`
region = 'minio'

## Required: object storage access key
# environment variable: PICTRS__STORE__ACCESS_KEY
# default: empty
access_key = 'ACCESS_KEY'

## Required: object storage secret key
# environment variable: PICTRS__STORE__SECRET_KEY
# default: empty
secret_key = 'SECRET_KEY'

## Optional: object storage session token
# environment variable: PICTRS__STORE__SESSION_TOKEN
# default: empty
session_token = 'SESSION_TOKEN'

## Optional: set how long object storage signatures are valid for (in seconds)
# environment variable: PICTRS__STORE__SIGNATURE_EXPIRATION
# default: 15
#
# This can be useful if your object storage might take a while to process requests. It should not be
# increased more than needed to prevent replay attacks.
signature_expiration = 15

## Optional: set how long pict-rs will wait (in seconds) for a response from object storage
# environment variable: PICTRS__STORE__CLIENT_TIMEOUT
# default: 30
#
# This value is the total wait time, and not additional wait time on top of the
# signature_expiration.
client_timeout = 30

## Optional: URL to a CDN at which pict-rs files are available for web consumption
# environment variable: PICTRS__STORE__PUBLIC_ENDPOINT
# default: empty
#
# When enabled, instaed of serving files itself, pict-rs will serve redirects to this URL with the
# path of the requested file. This can greatly reduce egress costs, and shorten the number of hops
# between the media and the client.
#
# Note that in order for clients to fetch media from this URL directly, any server between the
# client and pict-rs must not be configured to follow redirects, or else that server will fetch from
# this public URL and serve the file itself.
public_endpoint = "https://pict-rs.some.cdn.example.com/subpath/"