Hetzner Object Storage logo

Hetzner Object Storage

By Hermann del Campo - The AI QUEEN

A Strapi Upload Provider for Hetzner Object Storage (S3-compatible).

Latest version

v1.0.0

released October 29, 2025

npm install strapi-provider-upload-hetzner-s3

strapi-provider-upload-hetzner-s3

A Strapi Upload Provider for Hetzner Object Storage (S3-compatible).

🚀 Features

  • ✅ Full integration with Hetzner Object Storage
  • ✅ Support for all three Hetzner regions (FSN1, NBG1, HEL1)
  • ✅ TypeScript Support
  • ✅ Bucket prefixes for organized file structure
  • ✅ Custom Base URL Support (e.g., for CDN)
  • ✅ ACL configuration
  • ✅ Unit Tests
  • ✅ Buffer and Stream Upload Support

📋 Prerequisites

  • Node.js >= 14.19.1
  • Strapi >= 4.0.0
  • A Hetzner Object Storage Bucket

📦 Installation

npm install strapi-provider-upload-hetzner-s3
# or
yarn add strapi-provider-upload-hetzner-s3

🔧 Hetzner Object Storage Setup

1. Create Bucket

  1. Go to Hetzner Cloud Console
  2. Navigate to "Object Storage"
  3. Create a new bucket
  4. Choose a region:
    • FSN1: Falkenstein, Germany
    • NBG1: Nuremberg, Germany
    • HEL1: Helsinki, Finland

2. Generate Access Keys

  1. Click on your bucket
  2. Go to "S3 Keys"
  3. Create a new S3 Key
  4. Save the Access Key and Secret Key securely

3. Bucket Settings

  • Public Access: Enable this if your files should be publicly accessible
  • CORS: Configure CORS settings if needed

⚙️ Configuration

Basic Configuration

Create or edit ./config/plugins.js (or .ts):

module.exports = ({ env }) => ({
  upload: {
    config: {
      provider: "strapi-provider-upload-hetzner-s3",
      providerOptions: {
        accessKeyId: env("HETZNER_ACCESS_KEY_ID"),
        secretAccessKey: env("HETZNER_SECRET_ACCESS_KEY"),
        region: env("HETZNER_REGION"), // fsn1, nbg1, or hel1
        params: {
          Bucket: env("HETZNER_BUCKET_NAME"),
        },
      },
    },
  },
});

Advanced Configuration

module.exports = ({ env }) => ({
  upload: {
    config: {
      provider: "strapi-provider-upload-hetzner-s3",
      providerOptions: {
        accessKeyId: env("HETZNER_ACCESS_KEY_ID"),
        secretAccessKey: env("HETZNER_SECRET_ACCESS_KEY"),
        region: env("HETZNER_REGION"), // fsn1, nbg1, or hel1
        params: {
          Bucket: env("HETZNER_BUCKET_NAME"),
          ACL: "public-read", // Optional: makes files publicly readable
        },
        // Optional: Prefix for all uploads
        prefix: env("HETZNER_BUCKET_PREFIX", "uploads"), // e.g., "strapi-assets"
        // Optional: Custom Base URL (e.g., for CDN)
        baseUrl: env("CDN_BASE_URL"), // e.g., "https://cdn.example.com"
      },
    },
  },
});

Environment Variables

Create a .env file in the root of your project:

# Hetzner Object Storage Credentials
HETZNER_ACCESS_KEY_ID=your_access_key
HETZNER_SECRET_ACCESS_KEY=your_secret_key

# Region (fsn1, nbg1, or hel1)
HETZNER_REGION=fsn1

# Bucket Name
HETZNER_BUCKET_NAME=my-strapi-bucket

# Optional: Bucket Prefix
HETZNER_BUCKET_PREFIX=uploads

# Optional: CDN Base URL
CDN_BASE_URL=https://cdn.example.com

🌍 Available Regions

Region CodeLocationEndpoint
fsn1Falkenstein, Germanyfsn1.your-objectstorage.com
nbg1Nuremberg, Germanynbg1.your-objectstorage.com
hel1Helsinki, Finlandhel1.your-objectstorage.com

🖼️ Image Previews in Strapi Admin

To display thumbnails correctly in the Strapi Admin Panel, configure the Content Security Policy:

Edit ./config/middlewares.js:

module.exports = ({ env }) => [
  // ... other middlewares
  {
    name: "strapi::security",
    config: {
      contentSecurityPolicy: {
        useDefaults: true,
        directives: {
          "connect-src": ["'self'", "https:"],
          "img-src": [
            "'self'",
            "data:",
            "blob:",
            `${env("HETZNER_BUCKET_NAME")}.${env("HETZNER_REGION")}.your-objectstorage.com`,
          ],
          "media-src": [
            "'self'",
            "data:",
            "blob:",
            `${env("HETZNER_BUCKET_NAME")}.${env("HETZNER_REGION")}.your-objectstorage.com`,
          ],
          upgradeInsecureRequests: null,
        },
      },
    },
  },
  // ... other middlewares
];

If using a CDN Base URL:

"img-src": [
  "'self'",
  "data:",
  "blob:",
  env("CDN_BASE_URL"),
],
"media-src": [
  "'self'",
  "data:",
  "blob:",
  env("CDN_BASE_URL"),
],

🔐 Security & Best Practices

ACL Settings

Hetzner Object Storage supports the following ACL values:

  • private (Default): Only the bucket owner has access
  • public-read: Everyone can read objects
  • public-read-write: Everyone can read and write (⚠️ not recommended)
  • authenticated-read: Only authenticated users can read

Recommendation: Use public-read for public websites or omit ACL and configure bucket settings via Hetzner Console.

Bucket Organization with Prefixes

Use prefixes to organize your files:

prefix: "production/uploads"  // All files under production/uploads/
prefix: "strapi/media"         // All files under strapi/media/

CORS Configuration

If your frontend directly accesses the files, configure CORS in the Hetzner Console:

{
  "CORSRules": [
    {
      "AllowedOrigins": ["https://your-website.com"],
      "AllowedMethods": ["GET", "HEAD"],
      "AllowedHeaders": ["*"],
      "MaxAgeSeconds": 3000
    }
  ]
}

🚨 Troubleshooting

Error: "Access Denied"

Solution:

  • Check your Access Key and Secret Key
  • Ensure the key has the correct permissions
  • If using ACL, ensure the key has s3:PutObjectACL permission

Error: "Bucket not found"

Solution:

  • Check the bucket name (case-sensitive!)
  • Ensure the bucket exists in the correct region
  • Verify the region configuration (fsn1, nbg1, or hel1)

Images not displaying

Solution:

  • Check the Content Security Policy in middlewares.js
  • Ensure the bucket is publicly readable or ACL is set correctly
  • Check browser console for CORS errors

Uploads failing

Solution:

  • Check bucket size and limits
  • Ensure the upload isn't too large
  • Check network connection
  • Enable debug logging in Strapi

🧪 Testing

# Run tests
npm test

# Tests with coverage
npm test -- --coverage

# Build
npm run build

📊 Comparison to Other Providers

FeatureHetzner S3AWS S3DigitalOcean Spaces
Price (Storage)~€0.005/GB~€0.023/GB~€0.020/GB
Price (Transfer)Free~€0.09/GB~€0.01/GB
EU Regions✅ 3✅ 8+❌
S3-Compatible✅✅✅
GDPR-Compliant✅⚠️⚠️

🤝 Contributing

Contributions are welcome! Please create a pull request or open an issue.

Development Setup

# Clone repository
git clone https://github.com/raiva-technologies/strapi-provider-upload-hetzner-s3.git

# Install dependencies
npm install

# Run tests
npm test

# Build
npm run build

📝 License

MIT License - see LICENSE file

🔗 Links

💬 Support

If you have any questions or issues:

📈 Changelog

v1.0.0

  • Initial Release
  • Support for all three Hetzner regions
  • TypeScript Support
  • Full test coverage
  • Prefix and Base URL Support

Made with ❤️ for the Strapi Community

Submit your content

Share your work with the community and get it listed in the Strapi ecosystem for everyone to discover and use.

Submit
Submit your content