📌 Project Resources#

• 🌐 GitHub: https://github.com/besscroft/PicImpact

• 📖 Documentation:

  https://pic-docs.ziyume.com

• 🪪 License: MIT

🪄 Why Choose PicImpact?#

I was searching for a sleek image hosting template for my photography site, Moments. PicImpact stood out for its clean UI and Docker support—a perfect “one-and-done” solution.

🚫 Why not local deployment?
Don’t ask. I just didn’t want to deal with the overhead of a local Node.js environment… 💀

🐳 Docker Deployment Experience#

The deployment is incredibly smooth. As long as your PostgreSQL instance is ready (either local or a managed cloud DB), you just run the following command, and you’re airborne:

1
docker run -d --name picimpact \
2
  -p 3000:3000 \
3
  -e DATABASE_URL="postgresql://[USER]:[PASSWORD]@[HOST]:[PORT]/[DB_NAME]" \
4
  -e BETTER_AUTH_SECRET="npx auth secret or a random string" \
5
  besscroft/picimpact:latest

🧨 The Obstacle…#

Initially, I used Alist as the storage backend, but I was bottlenecked by my home broadband’s limited upload speed 🥲. So, I pivoted to Cloudflare’s R2—the generous “Saint” of free object storage.

However, after configuration, the upload process went haywire:

• The UI popup showed a “Success” checkmark ☑️, but the image status below displayed Upload.failed

• The Browser Console was a gallery of errors:

  1. ERR_NAME_NOT_RESOLVED
  2. ERR_SSL_VERSION_OR_CIPHER_MISMATCH
  3. ERR_FAILED
  4. has been blocked by CORS policy: … No ‘Access-Control-Allow-Origin’ header

Is it successful? The R2 dashboard was empty. Is it a failure? The frontend insisted it was “Success.” I felt like I had triggered every possible error in the PicImpact library 🤦‍♂️. Eventually, I narrowed it down to a CORS configuration issue.

🛠️ Setting Up Cloudflare R2#

Cloudflare R2 offers 10GB of free monthly storage with no egress fees. Note that CF nodes are primarily overseas, so latency may vary. For higher performance in China, consider Tencent COS or Alibaba OSS.

1. Access R2 Storage

2. Create a Bucket.

3. Bucket Parameters

You can choose any location, as latency is similar. However, ensure you select the Standard storage class to stay within the free tier.😯

4. Custom Domain

You must use a domain whose Nameservers (NS) point to Cloudflare.

5. CRITICAL: Configure CORS Policy

This is the dealbreaker. If you miss this, you’ll end up wasting hours like I did.～

CORS Policy Sample: Note that AllowedHeaders is mandatory; R2’s default generator often omits it.

1
[
2
  {
3
    "AllowedOrigins": [
4
      "http://localhost:3000"
5
    ],
6
    "AllowedMethods": [
7
      "GET",
8
      "HEAD",
9
      "PUT",
10
      "POST",
11
      "DELETE"
12
    ],
13
    "AllowedHeaders": [
14
      "*"
15
    ]
16
  }
17
]

5. Create API Tokens

As a security professional, I strongly advocate for the Principle of Least Privilege.

Avoid creating “Account API Tokens” if possible; a specific User API Token scoped only to the required bucket is much safer.

6. Save API Credentials

These credentials (Access Key ID, Secret Access Key, and Account ID) appear only once. You will need the S3 API info for PicImpact.

🔗 Integrating PicImpact with CF-R2#

1. Navigate to the PicImpact dashboard: Storage Config -> Cloudflare R2 -> Edit.

2. Fill in the Details:

• r2_accesskey_id: Your Access Key ID.
• r2_accesskey_secret: Your Secret Access Key.
• r2_account_id: The prefix of your S3 endpoint (e.g., if the endpoint is https://123456.r2.cloudflarestorage.com, use 123456).
• r2_bucket: Your bucket name.
• r2_storage_folder: Path prefix. If using the root, leave blank. Do not start with a slash (/).
• r2_public_domain: Your custom domain from step 4. Must include the protocol (e.g., https://abc.com).
• r2_direct_download: Usually set to false.

3. Success: You’re now ready to showcase your work!

✅ Final Thoughts#

PicImpact is a fantastic project with an elegant UI. While the documentation doesn’t provide a “step-by-step” for every storage provider, that’s the beauty of open-source—the joy of tinkering.

The “False Success” caused by CORS is particularly misleading. If you’re struggling with PicImpact + CF-R2, remember:

• Check the Console errors first.
• Verify your CORS headers (especially AllowedHeaders).
• Confirm that files are actually landing in the bucket dashboard.

Hopefully, this guide saves you some hair-pulling! 🤯