CattoPic - Self-Hosted Image Hosting on Cloudflare

What is CattoPic#

CattoPic is a self-hosted image hosting service providing complete functionality for uploading, managing, and serving images. Its distinctive feature is that the entire backend runs on Cloudflare’s free tier services, while the frontend can be deployed on Vercel. For users who already have a Cloudflare account, this translates to near-zero operating costs.

Core features include:

• Multi-format image upload supporting JPEG, PNG, GIF, WebP, and AVIF
• Automatic conversion to WebP and AVIF formats after upload, saving storage and bandwidth
• Tag system for organizing images
• Image expiration time settings for temporary images
• Public random image API, useful for blog backgrounds or other scenarios
• Automatic landscape/portrait detection with API filtering by orientation

Technical Architecture#

CattoPic employs a modern technology stack:

Frontend

• Next.js 16 with React 19
• Tailwind CSS for styling
• Static export deployment, no server-side rendering required

Backend

• Cloudflare Workers as the compute layer, using the Hono framework for API construction
• Cloudflare D1 as the database, storing image metadata and configuration
• Cloudflare R2 as object storage for image files
• Cloudflare KV for caching
• Cloudflare Queues for asynchronous tasks
• Cron Triggers for scheduled cleanup of expired images

The entire backend runs on Cloudflare’s edge network, ensuring good response times and reliability.

Deployment Guide#

Deploying CattoPic involves two steps: configuring the Cloudflare backend services and deploying the frontend application.

1
wrangler login

1
# Create R2 bucket
2
wrangler r2 bucket create cattopic-r2
3

4
# Create D1 database
5
wrangler d1 create CattoPic-D1
6

7
# Create KV namespace
8
wrangler kv namespace create CACHE_KV
9

10
# Create message queue
11
wrangler queues create cattopic-delete-queue

1
[[d1_databases]]
2
binding = "DB"
3
database_name = "CattoPic-D1"
4
database_id = "your-database-id"
5

6
[[r2_buckets]]
7
binding = "R2"
8
bucket_name = "cattopic-r2"
9

10
[[kv_namespaces]]
11
binding = "CACHE_KV"
12
id = "your-kv-namespace-id"
13

14
[[queues.producers]]
15
queue = "cattopic-delete-queue"
16
binding = "DELETE_QUEUE"
17

18
[[queues.consumers]]
19
queue = "cattopic-delete-queue"
20

21
[vars]
22
R2_PUBLIC_URL = "your-r2-public-url"
23
ENVIRONMENT = "production"

1
cd worker
2
wrangler d1 execute CattoPic-D1 --remote --file=schema.sql

1
wrangler deploy

1
INSERT INTO api_keys (key, name, created_at)
2
VALUES ('your-secret-key', 'Admin Dashboard', datetime('now'));

1
NEXT_PUBLIC_API_URL=your-worker-url
2
NEXT_PUBLIC_REMOTE_PATTERNS=your-r2-public-url,your-worker-url

Key Advantages#

Cost Efficiency

Cloudflare’s free tier is quite generous:

• Workers: 100,000 requests per day
• D1: 5GB storage, 5 million row reads
• R2: 10GB storage, 1 million Class A operations, 10 million Class B operations
• KV: 100,000 reads per day

For personal blogs or small to medium sites, these quotas are sufficient for daily use.

Performance

Leveraging Cloudflare’s global edge network, image access latency is low. The automatic format conversion feature generates WebP and AVIF versions, allowing modern browsers to receive smaller file sizes and faster loading times.

Data Sovereignty

Images are stored in your own R2 bucket, with data entirely under your control. No need to worry about third-party content moderation or service termination.

Feature Completeness

The management dashboard supports drag-and-drop upload, paste upload, and batch operations. The tag system and expiration time features provide flexible image management. The random image API is a practical bonus feature.

Current Limitations#

CattoPic has some usage limitations to be aware of before deployment:

File Size Limit

The frontend upload component limits individual files to 20MB. This limit is hardcoded in app/components/UploadSection.tsx. While the backend theoretically supports 100MB (Cloudflare Workers’ request body limit), the frontend intercepts first. To upload larger images, you need to modify the MAX_FILE_SIZE constant in the frontend code.

GIF Handling

GIF files are stored in their original format without conversion to WebP or AVIF. This is a deliberate choice considering the complexity of animated image conversion. I will also pay attention to the update of worker, and may consider other solutions to improve it.

Conclusion#

CattoPic provides an image hosting solution built on the Cloudflare ecosystem. It leverages Cloudflare’s free service tier to construct a fully-featured image hosting system, suitable for users who require data sovereignty and want to control costs. The deployment process requires some technical background, but the documentation is reasonably complete. The 20MB upload limit is typically sufficient for web images, and can be adjusted by modifying the code if needed.

If you are looking for a controllable, low-cost image hosting solution with decent performance, CattoPic is worth considering.