windoze/clipper-server repository overview

⁠Clipper Server

A clipboard management server with REST API, WebSocket support, and built-in Web UI.

⁠Features

• REST API for CRUD operations on clipboard entries
• Full-text search with filters and pagination
• WebSocket for real-time updates
• File attachment support (text, images, binary files)
• Built-in Web UI with drag-and-drop upload
• TLS/HTTPS with manual, automatic (Let's Encrypt), or self-signed certificates
• Self-signed certificate support with SSH-like fingerprint verification
• Clip sharing via short URLs with optional expiration
• Auto-cleanup for old clips
• Multi-architecture support (amd64, arm64)

⁠Quick Start

docker run -d \
  --name clipper \
  -p 3000:3000 \
  -v clipper-data:/data \
  windoze/clipper-server

Access the Web UI at http://localhost:3000

⁠Configuration

⁠Environment Variables

⁠Auto-Cleanup

⁠TLS (Manual Certificates)

⁠TLS (Let's Encrypt)

⁠Authentication

When CLIPPER_BEARER_TOKEN is set, all API requests require authentication:

• REST API: Include Authorization: Bearer <token> header or ?token=<token> query parameter
• WebSocket: Send {"type": "auth", "token": "<token>"} message after connecting
• Web UI: Login screen appears automatically when authentication is required
• File downloads: Use ?token=<token> query parameter for direct file links

⁠Clip Sharing (Short URLs)

When CLIPPER_SHORT_URL_BASE is set (e.g., https://clips.example.com), clips can be shared publicly via short URLs. The share button appears in the Web UI and desktop app.

⁠Upload Limits

Files exceeding the limit will be rejected with a 413 Payload Too Large error.

⁠Usage Examples

⁠Basic HTTP

docker run -d \
  --name clipper \
  -p 3000:3000 \
  -v clipper-data:/data \
  windoze/clipper-server

⁠HTTPS with Manual Certificates

docker run -d \
  --name clipper \
  -p 3000:3000 \
  -p 443:443 \
  -v clipper-data:/data \
  -v /path/to/certs:/certs:ro \
  -e CLIPPER_TLS_ENABLED=true \
  windoze/clipper-server

⁠HTTPS with Let's Encrypt

docker run -d \
  --name clipper \
  -p 80:3000 \
  -p 443:443 \
  -v clipper-data:/data \
  -e CLIPPER_ACME_ENABLED=true \
  -e CLIPPER_ACME_DOMAIN=clips.example.com \
  -e [email protected] \
  windoze/clipper-server

⁠With Auto-Cleanup

docker run -d \
  --name clipper \
  -p 3000:3000 \
  -v clipper-data:/data \
  -e CLIPPER_CLEANUP_ENABLED=true \
  -e CLIPPER_CLEANUP_RETENTION_DAYS=7 \
  windoze/clipper-server

⁠With Authentication

docker run -d \
  --name clipper \
  -p 3000:3000 \
  -v clipper-data:/data \
  -e CLIPPER_BEARER_TOKEN=your-secret-token \
  windoze/clipper-server

Example API call with authentication:

# Using Authorization header
curl -H "Authorization: Bearer your-secret-token" http://localhost:3000/clips

# Using query parameter
curl "http://localhost:3000/clips?token=your-secret-token"

⁠With Custom Upload Limit

docker run -d \
  --name clipper \
  -p 3000:3000 \
  -v clipper-data:/data \
  -e CLIPPER_MAX_UPLOAD_SIZE_MB=100 \
  windoze/clipper-server

⁠Docker Compose

services:
  clipper:
    image: windoze/clipper-server
    ports:
      - "3000:3000"
      - "443:443"
    volumes:
      - clipper-data:/data
      - ./certs:/certs:ro  # Optional: for manual TLS
    environment:
      - RUST_LOG=clipper_server=info
      # Enable authentication:
      # - CLIPPER_BEARER_TOKEN=your-secret-token
      # Enable HTTPS with Let's Encrypt:
      # - CLIPPER_ACME_ENABLED=true
      # - CLIPPER_ACME_DOMAIN=clips.example.com
      # - [email protected]
    restart: unless-stopped

volumes:
  clipper-data:

⁠Volumes

⁠Ports

⁠REST API

• GET /health - Health check
• GET /version - Server version and status information
• POST /clips - Create a clip
• POST /clips/upload - Upload a file
• GET /clips - List clips (with pagination)
• GET /clips/search?q=query - Search clips
• GET /clips/:id - Get a clip
• PUT /clips/:id - Update a clip
• DELETE /clips/:id - Delete a clip
• GET /clips/:id/file - Download file attachment
• POST /clips/:id/short-url - Create short URL for sharing
• GET /s/:code - Resolve short URL (public, no auth required)

⁠WebSocket

Connect to ws://localhost:3000/ws for real-time updates.

⁠Authentication

When authentication is enabled, send an auth message immediately after connecting:

{ "type": "auth", "token": "your-secret-token" }

The server will respond with:

{ "type": "auth_result", "success": true }

⁠Notification Messages

{ "type": "new_clip", "id": "abc123", "content": "...", "tags": [] }
{ "type": "updated_clip", "id": "abc123" }
{ "type": "deleted_clip", "id": "abc123" }
{ "type": "clips_cleaned_up", "ids": ["..."], "count": 5 }

⁠Security

• Runs as non-root user (UID 65532)
• Uses distroless base image for minimal attack surface
• Proper signal handling with tini

⁠Links

• Homepage⁠
• GitHub Repository⁠
• Full Documentation⁠
• Desktop App Downloads⁠