DOCSEARCHbyAlgolia
Submit Docs

Pingvin Share X

repository·main·Indexed 42 days ago

https://github.com/smp46/pingvin-share-x

A self-hosted file sharing platform alternative to services like WeTransfer, allowing users to share files via links with customizable security and storage configurations. Version 2.0.0-beta.2 supports deployment via Docker Compose, configuration through a config.yaml file or administrative API, and features an integrated EmailService for automated notifications and SMTP delivery.

Tokens
14.4K
Snippets
44
Records
77
Agent score
58%

What's inside Pingvin Share X

  1. Overview of Pingvin Share X features

    main

    Pingvin Share X is a self-hosted file sharing platform designed as an alternative to services like WeTransfer. It allows users to share files via links with several security and management features:

    • Unlimited file size: Sharing is restricted only by your available disk space.
    • Expiration dates: Set specific dates for when a share should expire.
    • Security controls: Protect shares using passwords and visitor limits.
    • Email integration: Send shares directly to email recipients.
    • Security scanning: Integrates with ClamAV to perform security scans on files.

  2. S3 performance considerations for ClamAV and ZIP

    main

    When using S3 as your storage provider, be aware of the following behaviors:

    ClamAV Scanning

    If ClamAV is enabled, files are first uploaded to the S3 bucket, then streamed back to the backend server to be scanned. This extra step can significantly increase scanning times, especially for large files. If scanning is too slow, consider disabling either S3 or ClamAV.

    ZIP Archive Creation

    ZIP archive creation is supported with S3. The backend will fetch the files from the S3 bucket, compress them into a ZIP file, and then serve the resulting archive to the user.

  4. Configure CORS for S3 uploads and downloads

    main

    Because Pingvin Share performs uploads and downloads directly between the client's browser and the S3 bucket using pre-signed URLs, you must configure a Cross-Origin Resource Sharing (CORS) policy on your S3 bucket. Failure to do so will cause file transfers to fail due to browser security restrictions.

    Required Configuration Rules

    • AllowedOrigins: Must match the exact URL (including scheme, domain, and port) used to access your Pingvin Share instance (e.g., https://share.example.com or http://100.116.239.35:3001).
    • AllowedMethods: Must include PUT (for chunked uploads), GET (for downloads/previews), and HEAD (for existence/size checks).
    • ExposeHeaders: Must explicitly include ETag. The frontend requires this header to complete uploads.
    • AllowedHeaders: Should include Content-Type.
    [
  {
    "AllowedHeaders": ["Content-Type"],
    "AllowedMethods": ["GET", "PUT", "HEAD"],
    "AllowedOrigins": ["https://your-pingvin-share-domain.com"],
    "ExposeHeaders": ["ETag"],
    "MaxAgeSeconds": 3000
  }
]

  6. Install Pingvin Share X with Docker

    main

    The recommended way to deploy Pingvin Share X is using Docker Compose.

    1. Download the docker-compose.yml file.
    2. Run the following command to start the services in detached mode:
    docker compose up -d

    Once running, the application is accessible at http://localhost:3000.

  7. Stand-alone Installation of Pingvin Share X

    main

    For manual installation without Docker, ensure you have the following tools installed:

    Follow these steps to clone, checkout the latest version, and start both the backend and frontend services using pm2.

    git clone https://github.com/smp46/pingvin-share-x
cd pingvin-share

# Checkout the latest version
git fetch --tags && git checkout $(git describe --tags `git rev-list --tags --max-count=1`)

# Start the backend
cd backend
npm install
npm run build
pm2 start --name="pingvin-share-x-backend" npm -- run prod

# Start the frontend
cd ../frontend
npm install
npm run build
API_URL=http://localhost:8080 # Set the URL of the backend, default: http://localhost:8080
pm2 start npm --name "pingvin-share-x-frontend" -- run start

  8. Upgrade Pingvin Share X Stand-alone installation

    main

    For stand-alone installations managed via PM2, you must stop the services, fetch the latest tagged version via Git, rebuild the assets, and restart the processes.

    Note on Environment Variables: If you are changing configuration via environment variables, a standard pm2 restart will not pick up the changes. You must use pm2 --update-env restart instead.

    # 1. Stop the running app
pm2 stop pingvin-share-x-backend pingvin-share-x-frontend

# 2. Update the source code
cd pingvin-share
git fetch --tags && git checkout $(git describe --tags `git rev-list --tags --max-count=1`)

# 3. Rebuild and restart the backend
cd backend
npm install
npm run build
pm2 restart pingvin-share-x-backend

# 4. Rebuild and restart the frontend
cd ../frontend
npm install
npm run build
pm2 restart pingvin-share-x-frontend

# Note: Use 'pm2 --update-env restart' if you changed environment variables

  9. Integrate ClamAV with Docker Compose

    main

    To enable automatic scanning of shares for malicious files using ClamAV within a Docker Compose setup, add a clamav service to your stack. Use the depends_on property with a service_healthy condition to ensure Pingvin Share X only starts once ClamAV is ready.

    Note that ClamAV requires significant system resources (RAM). After starting, check the Pingvin Share logs for the message ClamAV is active to confirm successful integration.

    services:
  pingvin-share-x:
    image: smp46/pingvin-share-x
    ...
+   depends_on:
+     clamav:
+       condition: service_healthy

+  clamav:
+    restart: unless-stopped
+    image: clamav/clamav

  10. Configure built-in OAuth 2 providers

    main

    Pingvin Share X supports several built-in OAuth 2 providers. To use them, you must register your application with the respective provider and set the correct Redirect URL in your application settings.

    ProviderRedirect URL
    GitHubhttps://<your-domain>/api/oauth/callback/github
    Googlehttps://<your-domain>/api/oauth/callback/google
    Microsofthttps://<your-domain>/api/oauth/callback/microsoft
    Discordhttps://<your-domain>/api/oauth/callback/discord
    OpenID Connecthttps://<your-domain>/api/oauth/callback/oidc

    Note for Microsoft: The Microsoft Tenant configured in the admin panel must match the supported account types set in the Microsoft Entra admin center for authentication to succeed.