Configuration

Configuration

Create a storage config file (see Installation for the jar path, the storage config directory sits next to it, e.g. ./plugins/BlueMap/storages/s3.conf for Spigot/Paper):

##                          ##
##         BlueMap          ##
##      Storage-Config      ##
##                          ##

# Don't change this value! (If you want a different storage-type, check out the other
# example-configs under de.bluecolored.bluemap.core.storage.file)
storage-type: "themeinerlp:s3"

# gzip, zstd, deflate, or none
compression: gzip

bucket-name: "bluemap-storage"

# AWS region, "Minio" for MinIO, or "auto" for Cloudflare R2
region: "Minio"

access-key-id: "your-access-key"
secret-access-key: "your-secret-key"

# Optional: custom endpoint URL for S3-compatible services. Leave empty for AWS S3.
endpoint-url: "http://localhost:9000"

# Optional: root path inside the bucket. Default is "." (bucket root)
root-path: "."

# Optional: force path-style access (needed for MinIO, and for R2 unless using account-id)
force-path-style: true

Then reference the storage from your main BlueMap config (core.conf) or map definitions, same as any other BlueMap storage.

Options

Option	Description	Default
storage-type	The storage type identifier (don't change this value)	themeinerlp:s3
compression	Compression for stored data: gzip, zstd, deflate, none	gzip
bucket-name	The S3 bucket name	bluemap-storage
region	The AWS region, or the region string your provider expects (Minio for MinIO, auto for R2)	Minio
access-key-id	Access key ID for authentication	bluemap
secret-access-key	Secret access key for authentication	bluemap-secret
endpoint-url	Custom endpoint URL for S3-compatible services. Leave empty for AWS S3.	http://localhost:9000
root-path	Root path inside the bucket	.
force-path-style	Force path-style access (needed for MinIO; not needed for R2 if using account-id, see below)	false
checksum-validation	when_required or when_supported. Since AWS SDK 2.30, when_supported attaches a checksum to every request, which many S3-compatible stores (Ceph RGW included) reject with a bare 400 Bad Request, silently failing tile saves. Only switch to when_supported on real AWS S3 or a provider you've confirmed handles it.	when_required
provider	Explicitly picks the provider profile (r2 or generic) instead of auto-detecting from which fields are set. Only needed if you want to be explicit; see Cloudflare R2.	(auto-detect)
account-id	Cloudflare account ID. If set (and endpoint-url is empty), the endpoint and path-style access are derived automatically. See Cloudflare R2.	(empty)
list-cache-ttl-seconds	How long to cache the list of available maps (mapIds()). Directory listings are a billed operation on some providers (e.g. R2); this list rarely changes at runtime. 0 disables caching.	0

For ready-to-use examples per provider, see Provider Examples and Cloudflare R2.