CloudPaste 📋

📑 Table of Contents

• Action Automated Deployment

• Manual Deployment

• ClawCloud CloudPaste Deployment Tutorial

Action Automated Deployment

Using GitHub Actions enables automatic deployment of your application after code is pushed. CloudPaste offers two deployment architectures for you to choose from.

Deployment Architecture Selection

🔄 Unified Deployment (Recommended)

Frontend and backend deployed on the same Cloudflare Worker

✨ Advantages:

• Same Origin - No CORS issues, simpler configuration
• Lower Cost - Navigation requests are free, saving 60%+ costs compared to separated deployment
• Simpler Deployment - Deploy frontend and backend in one go, no need to manage multiple services
• Better Performance - Frontend and backend on the same Worker, faster response time

🔀 Separated Deployment

Backend deployed to Cloudflare Workers, frontend deployed to Cloudflare Pages

✨ Advantages:

• Flexible Management - Independent deployment, no mutual interference
• Team Collaboration - Frontend and backend can be maintained by different teams
• Scalability - Frontend can easily switch to other platforms (e.g., Vercel)

Configure GitHub Repository

1️⃣ Fork or Clone Repository

Visit and Fork the repository: https://github.com/ling-drag0n/CloudPaste

2️⃣ Configure GitHub Secrets

Go to your GitHub repository settings: Settings → Secrets and variables → Actions → New repository secret

Add the following Secrets:

| Secret Name | Required | Purpose | | ----------------------- | -------- | ------------------------------------------------------------------------------------- | | CLOUDFLAREAPITOKEN | ✅ | Cloudflare API token (requires Workers, D1, and Pages permissions) | | CLOUDFLAREACCOUNTID | ✅ | Cloudflare account ID | | ENCRYPTION_SECRET | ❌ | Key for encrypting sensitive data (will be auto-generated if not provided) | | ACTIONSVARTOKEN | ✅ | GitHub Token for deployment control panel (required only when using the control panel, otherwise skip) |

3️⃣ Obtain Cloudflare API Token

Get API Token:

• Visit Cloudflare API Tokens
• Click Create Token
• Select Edit Cloudflare Workers template
• Add additional permissions:

• Click Continue to summary → Create Token
• Copy the Token and save it to GitHub Secrets

Get Account ID:

• Visit Cloudflare Dashboard
• Find Account ID in the right sidebar
• Click to copy and save to GitHub Secrets

4️⃣ (Optional) Configure Deployment Control Panel

If you want to use the visual control panel to manage auto-deployment switches, you need additional configuration:

Create GitHub Personal Access Token:

• Visit GitHub Token Settings
• Click Generate new token → Generate new token (classic)
• Set Token name (e.g., CloudPaste Deployment Control)
• Select permissions:

• Click Generate token
• Copy the Token and save as Secret ACTIONSVARTOKEN

• Go to repository Actions tab
• In the left workflow list, click 🎛️ Deployment Control Panel
• Click Run workflow → Run workflow on the right
• In the popup, select the deployment method to enable/disable
• Click Run workflow to apply configuration
• After updating the switch state, the control panel will automatically trigger the corresponding deployment workflow once (whether it actually deploys is decided by the current switch state)

🔄 Unified Deployment Tutorial (Recommended)

Deployment Steps

1️⃣ Configure GitHub Secrets (refer to the configuration section above)

2️⃣ Trigger Deployment Workflow

Method 1: Manual Trigger (recommended for first deployment)

• Go to repository Actions tab
• Click Deploy SPA CF Workers[一体化部署] on the left
• Click Run workflow on the right → select main branch → Run workflow

• Use the deployment control panel to enable SPA Unified Auto Deploy
• After that, deployment will be triggered automatically when pushing code to frontend/ or backend/ directory to main branch

Note: When you manually run Deploy SPA CF Workers[一体化部署] from the Actions page, it will always deploy once regardless of the auto-deploy switch. Automatic behavior (push or control panel triggered) is still controlled by the SPA_DEPLOY switch.

3️⃣ Wait for Deployment to Complete

The deployment process takes about 3-5 minutes. The workflow will automatically complete the following steps:

• ✅ Build frontend static assets
• ✅ Install backend dependencies
• ✅ Create/verify D1 database
• ✅ Initialize database schema
• ✅ Set encryption secret
• ✅ Deploy to Cloudflare Workers

After successful deployment, you will see output similar to this in the Actions log:

Published cloudpaste-spa (X.XX sec)
  https://cloudpaste-spa.your-account.workers.dev

Your CloudPaste has been successfully deployed! Visit the URL above to use it.

Deployment Complete

Visit your application: https://cloudpaste-spa.your-account.workers.dev

Post-deployment Configuration:

• The database will be automatically initialized on first visit
• Log in with the default admin account:

• ⚠️ Important: Change the default admin password immediately!
• Configure your S3-compatible storage service in the admin panel
• (Optional) Bind a custom domain in Cloudflare Dashboard

• ✅ Same origin for frontend and backend, no CORS issues
• ✅ Navigation requests are free, reducing costs by 60%+
• ✅ Deploy in one go, simple management

🔀 Separated Deployment Tutorial

If you choose separated deployment, follow these steps:

Backend Deployment

1️⃣ Configure GitHub Secrets (refer to the configuration section above)

2️⃣ Trigger Backend Deployment

Method 1: Manual Trigger

• Go to repository Actions tab
• Click Deploy Backend CF Workers[Worker后端分离部署] on the left
• Click Run workflow → Run workflow

• Use the deployment control panel to enable Backend Separated Auto Deploy
• Deployment will be triggered automatically when pushing backend/ directory code

The workflow will automatically complete:

• ✅ Create/verify D1 database
• ✅ Initialize database schema
• ✅ Set encryption secret
• ✅ Deploy Worker to Cloudflare

After successful deployment, note down your backend Worker URL: https://cloudpaste-backend.your-account.workers.dev

⚠️ Important: Remember your backend domain, you'll need it for frontend deployment!

Frontend Deployment

Cloudflare Pages

1️⃣ Trigger Frontend Deployment

Method 1: Manual Trigger

• Go to repository Actions tab
• Click Deploy Frontend CF Pages[Pages前端分离部署] on the left
• Click Run workflow → Run workflow

• Use the deployment control panel to enable Frontend Separated Auto Deploy
• Deployment will be triggered automatically when pushing frontend/ directory code

Note: When you manually run the Backend or Frontend deployment workflows from the Actions page, they will always deploy once regardless of the auto-deploy switch. Automatic behavior is controlled by the BACKENDDEPLOY / FRONTENDDEPLOY switches.

2️⃣ Configure Environment Variables

Required step: After frontend deployment, you must manually configure the backend address!

• Log in to Cloudflare Dashboard
• Navigate to Pages → cloudpaste-frontend
• Click Settings → Environment variables
• Add environment variable:

⚠️ Must fill in the complete backend domain, format: https://xxxx.com

3️⃣ Redeploy Frontend

Important: After configuring environment variables, you must run the frontend workflow again!

• Return to GitHub Actions
• Manually trigger Deploy Frontend CF Pages workflow again
• This is necessary to load the backend domain configuration

4️⃣ Access Application

Frontend deployment URL: https://cloudpaste-frontend.pages.dev

⚠️ Please strictly follow the steps, otherwise backend domain loading will fail!

Vercel (Alternative)

Vercel deployment steps:

• Import GitHub project in Vercel after forking
• Configure deployment parameters:

Framework Preset: Vite
Build Command: npm run build
Output Directory: dist
Install Command: npm install

• Configure environment variables:

• Click Deploy button to deploy

⚠️ Security Notice: Please change the default admin password immediately after system initialization (username: admin, password: admin123).

Manual Deployment

CloudPaste supports two manual deployment methods: unified deployment (recommended) and separated deployment.

🔄 Unified Manual Deployment (Recommended)

Unified deployment deploys both frontend and backend to the same Cloudflare Worker, offering simpler configuration and lower costs.

Step 1: Clone Repository

git clone https://github.com/ling-drag0n/CloudPaste.git
cd CloudPaste

Step 2: Build Frontend

cd frontend
npm install
npm run build
cd ..

Verify build output: Ensure frontend/dist directory exists and contains index.html

Step 3: Configure Backend

cd backend
npm install
npx wrangler login

Step 4: Create D1 Database

npx wrangler d1 create cloudpaste-db

Note the database_id from the output (e.g., xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx)

Step 5: Initialize Database

npx wrangler d1 execute cloudpaste-db --file=./schema.sql

Step 6: Configure wrangler.spa.toml

Edit backend/wrangler.spa.toml file and modify the database ID:

[[d1_databases]]
binding = "DB"
database_name = "cloudpaste-db"
databaseid = "YOURDATABASE_ID"  # Replace with ID from Step 4

Step 7: Deploy to Cloudflare Workers

npx wrangler deploy --config wrangler.spa.toml

After successful deployment, you'll see your application URL:

Published cloudpaste-spa (X.XX sec)
  https://cloudpaste-spa.your-account.workers.dev

Deployment Complete!

Visit your application: Open the URL above to use CloudPaste

Post-deployment Configuration:

• The database will be automatically initialized on first visit
• Log in with the default admin account (username: admin, password: admin123)
• ⚠️ Change the default admin password immediately!
• Configure S3-compatible storage service in the admin panel
• (Optional) Bind a custom domain in Cloudflare Dashboard

🔀 Separated Manual Deployment

If you need to deploy and manage frontend and backend independently, you can choose the separated deployment method.

Backend Manual Deployment

• Clone the repository

git clone https://github.com/ling-drag0n/CloudPaste.git
cd CloudPaste/backend

• Install dependencies

npm install

• Log in to Cloudflare

npx wrangler login

• Create D1 database

npx wrangler d1 create cloudpaste-db

Note the database ID from the output.

• Modify wrangler.toml configuration

[[d1_databases]]
   binding = "DB"
   database_name = "cloudpaste-db"
   databaseid = "YOURDATABASE_ID"

• Deploy Worker

npx wrangler deploy

Note the URL from the output; this is your backend API address.

• Initialize database (automatic)

https://cloudpaste-backend.your-username.workers.dev

⚠️ Important: Remember your backend domain, you'll need it for frontend deployment!

Frontend Manual Deployment

Cloudflare Pages

• Prepare frontend code

cd CloudPaste/frontend
   npm install

• Configure environment variables

VITEBACKENDURL=https://cloudpaste-backend.your-username.workers.dev
   VITEAPPENV=production
   VITEENABLEDEVTOOLS=false

• Build frontend project

npm run build

Be careful when building! !

• Deploy to Cloudflare Pages

npx wrangler pages deploy dist --project-name=cloudpaste-frontend

Method 2: Via Cloudflare Dashboard

1. Log in to Cloudflare Dashboard 2. Select "Pages" 3. Click "Create a project" → "Direct Upload" 4. Upload files from the dist directory 5. Set project name (e.g., "cloudpaste-frontend") 6. Click "Save and Deploy"

Vercel

• Prepare frontend code

cd CloudPaste/frontend
   npm install

• Install and log in to Vercel CLI

npm install -g vercel
   vercel login

• Configure environment variables, same as for Cloudflare Pages
• Build and deploy

vercel --prod

Follow the prompts to configure the project.

ClawCloud CloudPaste Deployment Tutorial

10GB free traffic per month, suitable for light usage only

Step 1:

Registration link: Claw Cloud (no #AFF) No credit card required, as long as your GitHub registration date is more than 180 days, you get $5 credit every month.

Step 2:

After registration, click APP Launchpad on the homepage, then click create app in the upper right corner

Step 3:

First deploy the backend, as shown in the figure (for reference only):

Backend data storage is here:

Step 4:

Then the frontend, as shown in the figure (for reference only):

Deployment is complete and ready to use, custom domain names can be configured as needed

📑 Table of Contents

• Docker Command Line Deployment

• Docker Compose One-Click Deployment

Docker Command Line Deployment

Backend Docker Deployment

CloudPaste backend can be quickly deployed using the official Docker image.

• Create data storage directory

mkdir -p sql_data

• Run the backend container

docker run -d --name cloudpaste-backend \
     -p 8787:8787 \
     -v $(pwd)/sql_data:/data \
     -e ENCRYPTION_SECRET=your-encryption-key \
     -e NODE_ENV=production \
     dragon730/cloudpaste-backend:latest

Note the deployment URL (e.g., http://your-server-ip:8787), which will be needed for the frontend deployment.

⚠️ Security tip: Be sure to customize ENCRYPTION_SECRET and keep it safe, as this key is used to encrypt sensitive data.

Frontend Docker Deployment

The frontend uses Nginx to serve and configures the backend API address at startup.

docker run -d --name cloudpaste-frontend \
  -p 80:80 \
  -e BACKEND_URL=http://your-server-ip:8787 \
  dragon730/cloudpaste-frontend:latest

⚠️ Note: BACKEND_URL must include the complete URL (including protocol http:// or https://) ⚠️ Security reminder: Please change the default administrator password immediately after system initialization (Username: admin, Password: admin123).

Docker Image Update

When a new version of the project is released, you can update your Docker deployment following these steps:

• Pull the latest images

docker pull dragon730/cloudpaste-backend:latest
   docker pull dragon730/cloudpaste-frontend:latest

• Stop and remove old containers

docker stop cloudpaste-backend cloudpaste-frontend
   docker rm cloudpaste-backend cloudpaste-frontend

• Start new containers using the same run commands as above (preserving data directory and configuration)

Docker Compose One-Click Deployment

Using Docker Compose allows you to deploy both frontend and backend services with one click, which is the simplest recommended method.

• Create a docker-compose.yml file

version: "3.8"
services:   frontend:     image: dragon730/cloudpaste-frontend:latest     environment:       - BACKEND_URL=https://xxx.com # Fill in the backend service address     ports:       - "8080:80" #"127.0.0.1:8080:80"     depends_on:       - backend # Depends on backend service     networks:       - cloudpaste-network     restart: unless-stopped
backend:     image: dragon730/cloudpaste-backend:latest     environment:       - NODE_ENV=production       - PORT=8787       - ENCRYPTION_SECRET=custom-key # Please modify this to your own security key       - TASKWORKERPOOL_SIZE=2     volumes:       - ./sql_data:/data # Data persistence     ports:       - "8787:8787" #"127.0.0.1:8787:8787"     networks:       - cloudpaste-network     restart: unless-stopped
networks:   cloudpaste-network:     driver: bridge

• Start the services

docker-compose up -d

⚠️ Security reminder: Please change the default administrator password immediately after system initialization (Username: admin, Password: admin123).

• Access the services

Docker Compose Update

When you need to update to a new version:

• Pull the latest images

docker-compose pull

• Recreate containers using new images (preserving data volumes)

docker-compose up -d --force-recreate

💡 Tip: If there are configuration changes, you may need to backup data and modify the docker-compose.yml file

Nginx Reverse Proxy Example

server {
    listen 443 ssl;
    server_name paste.yourdomain.com;  # Replace with your domain name
# SSL certificate configuration     ssl_certificate     /path/to/cert.pem;  # Replace with certificate path     sslcertificatekey /path/to/key.pem;   # Replace with key path
# Frontend proxy configuration     location / {         proxy_pass http://localhost:80;  # Docker frontend service address         proxysetheader Host $host;         proxysetheader X-Real-IP $remote_addr;     }
# Backend API proxy configuration     location /api {         proxy_pass http://localhost:8787;  # Docker backend service address         proxysetheader Host $host;         proxysetheader X-Real-IP $remote_addr;         clientmaxbody_size 0;
# WebSocket support (if needed)         proxyhttpversion 1.1;         proxysetheader Upgrade $http_upgrade;         proxysetheader Connection "upgrade";     }
# WebDAV Configuration     location /dav {         proxy_pass http://localhost:8787/dav;  # Points to your backend service
# WebDAV necessary headers         proxysetheader Host $host;         proxysetheader X-Real-IP $remote_addr;         proxysetheader X-Forwarded-For $proxyaddxforwardedfor;
# WebDAV method support         proxypassrequest_headers on;
# Support all WebDAV methods         proxymethod $requestmethod;
# Necessary header processing         proxysetheader Destination $http_destination;         proxysetheader Overwrite $http_overwrite;
# Handle large files         clientmaxbody_size 0;
# Timeout settings         proxyconnecttimeout 3600s;         proxysendtimeout 3600s;         proxyreadtimeout 3600s;     } }

⚠️ Security tip: It is recommended to configure HTTPS and a reverse proxy (such as Nginx) to enhance security.

R2 API Retrieval and Cross-Origin Configuration

• Log in to Cloudflare Dashboard
• Click R2 Storage and create a bucket.
• Create API token

• Save all data after creation; you'll need it later
• Configure cross-origin rules: click the corresponding bucket, click Settings, edit CORS policy as shown below:

[
  {
    "AllowedOrigins": ["http://localhost:3000", "https://replace-with-your-frontend-domain"],
    "AllowedMethods": ["GET", "PUT", "POST", "DELETE", "HEAD"],
    "AllowedHeaders": ["*"],
    "ExposeHeaders": ["ETag"],
    "MaxAgeSeconds": 3600
  }
]

B2 API Retrieval and Cross-Origin Configuration

• If you don't have a B2 account, register one first, then create a bucket.

• Click Application Key in the sidebar, click Create Key, and follow the illustration.

• Configure B2 cross-origin; B2 cross-origin configuration is more complex, take note

• You can try options 1 or 2 first, go to the upload page and see if you can upload. If F12 console shows cross-origin errors, use option 3. For a permanent solution, use option 3 directly.

Regarding option 3 configuration, since the panel cannot configure it, you need to configure manually by downloading B2 CLI tool. For more details, refer to: "https://docs.cloudreve.org/zh/usage/storage/b2".

After downloading, in the corresponding download directory CMD, enter the following commands:

b2-windows.exe account authorize   //Log in to your account, following prompts to enter your keyID and applicationKey
b2-windows.exe bucket get <bucketName> //You can execute to get bucket information, replace <bucketName> with your bucket name

Windows configuration, Use ".\b2-windows.exe xxx", Python CLI would be similar:

b2-windows.exe bucket update <bucketName> allPrivate --cors-rules "[{\"corsRuleName\":\"CloudPaste\",\"allowedOrigins\":[\"\"],\"allowedHeaders\":[\"\"],\"allowedOperations\":[\"b2uploadfile\",\"b2downloadfilebyname\",\"b2downloadfilebyid\",\"s3head\",\"s3get\",\"s3put\",\"s3post\",\"s3_delete\"],\"exposeHeaders\":[\"Etag\",\"content-length\",\"content-type\",\"x-bz-content-sha1\"],\"maxAgeSeconds\":3600}]"

Replace with your bucket name. For allowedOrigins in the cross-origin allowance, you can configure based on your needs; here it allows all.

• Cross-origin configuration complete

MinIO API Access and Cross-Origin Configuration

• Deploy MinIO Server

version: "3"
services:      minio:        image: minio/minio:RELEASE.2025-02-18T16-25-55Z        container_name: minio-server        command: server /data --console-address :9001 --address :9000        environment:          - MINIOROOTUSER=minioadmin # Admin username          - MINIOROOTPASSWORD=minioadmin # Admin password          - MINIO_BROWSER=on          - MINIOSERVERURL=https://minio.example.com # S3 API access URL          - MINIOBROWSERREDIRECT_URL=https://console.example.com # Console access URL        ports:          - "9000:9000" # S3 API port          - "9001:9001" # Console port        volumes:          - ./data:/data          - ./certs:/root/.minio/certs # SSL certificates (if needed)        restart: always

Run docker-compose up -d to start the service.

• Configure Reverse Proxy (Reference)

MinIO S3 API Reverse Proxy (minio.example.com):

location / {
       proxy_pass http://127.0.0.1:9000;
       proxysetheader Host $host;
       proxysetheader X-Real-IP $remote_addr;
       proxysetheader X-Forwarded-For $proxyaddxforwardedfor;
       proxysetheader X-Forwarded-Proto $scheme;
# HTTP optimization        proxyhttpversion 1.1;        proxysetheader Connection "";  # Enable HTTP/1.1 keepalive
# Critical: Resolve 403 errors & preview issues        proxy_cache off;        proxy_buffering off;        proxyrequestbuffering off;
# No file size limit        clientmaxbody_size 0;    }

MinIO Console Reverse Proxy (console.example.com):

location / {
       proxy_pass http://127.0.0.1:9001;
       proxysetheader Host $host;
       proxysetheader X-Real-IP $remote_addr;
       proxysetheader X-Forwarded-For $proxyaddxforwardedfor;
       proxysetheader X-Forwarded-Proto $scheme;
# WebSocket support        proxyhttpversion 1.1;        proxysetheader Upgrade $http_upgrade;        proxysetheader Connection "upgrade";
# Critical settings        proxy_cache off;        proxy_buffering off;
# No file size limit        clientmaxbody_size 0;    }

• Access Console to Create Buckets & Access Keys

• Additional Configuration (Optional)

• Configure MinIO in CloudPaste

• Troubleshooting

More S3-related configurations to come......

WebDAV Configuration and Usage Guide

CloudPaste provides simple WebDAV protocol support, allowing you to mount storage spaces as network drives for convenient access and management of files directly through file managers.

WebDAV Service Basic Information

• WebDAV Base URL: https://your-backend-domain/dav
• Supported Authentication Methods:

• Supported Permission Types:

Permission Configuration

1. Administrator Account Access

Use administrator account and password to directly access the WebDAV service:

• Username: Administrator username
• Password: Administrator password

2. API Key Access (Recommended)

For a more secure access method, it is recommended to create a dedicated API key:

• Log in to the management interface
• Navigate to "API Key Management"
• Create a new API key, ensure "Mount Permission" is enabled
• Usage method:

NGINX Reverse Proxy Configuration

If using NGINX as a reverse proxy, specific WebDAV configuration needs to be added to ensure all WebDAV methods work properly:

# WebDAV Configuration
location /dav {
    proxy_pass http://localhost:8787;  # Points to your backend service
# WebDAV necessary headers     proxysetheader Host $host;     proxysetheader X-Real-IP $remote_addr;     proxysetheader X-Forwarded-For $proxyaddxforwardedfor;
# WebDAV method support     proxypassrequest_headers on;
# Support all WebDAV methods     proxymethod $requestmethod;
# Necessary header processing     proxysetheader Destination $http_destination;     proxysetheader Overwrite $http_overwrite;
# Handle large files     clientmaxbody_size 0;
# Timeout settings     proxyconnecttimeout 3600s;     proxysendtimeout 3600s;     proxyreadtimeout 3600s; }

Common Issues and Solutions

• Connection Problems:

• Permission Errors:

• ⚠️⚠️ WebDAV Upload Issues: