Pingvin Share Setup: Host a Lightweight File Sharing Platform in Docker

Deploying a self-hosted file-sharing solution provides complete control over your data, eliminates third-party storage limits, and enhances security. Pingvin Share is a lightweight, modern, and privacy-focused alternative to platforms like WeTransfer. This guide covers a production-ready deployment of Pingvin Share using Docker Compose, secured behind an Nginx reverse proxy with SSL, along with performance tuning for handling large file uploads.

Prerequisites

Before beginning, ensure you have: * A VPS running a clean installation of Ubuntu 22.04 LTS or 24.04 LTS. * A registered domain name (e.g., share.example.com) pointed to your VPS IP address (A record). * Docker and the Docker Compose plugin installed.

To verify Docker and Compose are installed:

docker --version
docker compose version

Directory Structure and Preparation

Organize your deployment configuration by creating a dedicated directory for Pingvin Share. This isolates your application state, configuration files, and volume mappings.

mkdir -p /opt/pingvin-share/data
cd /opt/pingvin-share

Docker Compose Configuration

Create a docker-compose.yml file to manage the Pingvin Share service. Pingvin Share operates as a unified container containing both the frontend and backend components.

Create and open /opt/pingvin-share/docker-compose.yml:

version: '3.8'

services:
  pingvin-share:
    image: stonith404/pingvin-share:latest
    container_name: pingvin-share
    restart: unless-stopped
    ports:
      - "3000:3000"
    volumes:
      - ./data:/opt/app/backend/data
    environment:
      - PORT=3000
      # Trust proxy headers passed by Nginx
      - TRUST_PROXY=true
    logging:
      driver: "json-file"
      options:
        max-size: "10m"
        max-file: "3"

Configuration Breakdown:

• Ports: Maps container port 3000 to the host port 3000. If port 3000 is occupied on your host, change the host mapping (e.g., "8080:3000").
• Volumes: Binds ./data on the host to /opt/app/backend/data inside the container. This directory stores database files (SQLite), configuration, and uploaded shares.
• TRUST_PROXY: Set to true to ensure Pingvin Share correctly detects user IP addresses and protocol schemes (HTTP/HTTPS) forwarded by the reverse proxy.

Reverse Proxy Setup (Nginx)

To enable HTTPS and handle large file uploads without timeouts, set up Nginx on the host VPS.

1. Install Nginx and Certbot

sudo apt update
sudo apt install -y nginx certbot python3-certbot-nginx

2. Configure Nginx Server Block

Create a new configuration block for Pingvin Share:

sudo nano /etc/nginx/sites-available/pingvin-share

Paste the following configuration. Replace share.example.com with your actual subdomain:

server {
    listen 80;
    server_name share.example.com;

    # Adjust client_max_body_size to define the maximum upload limit
    client_max_body_size 10G;

    # Enable chunked transfer encoding for large uploads
    chunked_transfer_encoding on;

    location / {
        proxy_pass http://127.0.0.1:3000;
        proxy_http_version 1.1;

        # Websockets and Upgrade headers
        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Connection "upgrade";

        # Real IP Forwarding
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;
        proxy_set_header X-Forwarded-Host $host;
        proxy_set_header X-Forwarded-Port $server_port;

        # Disable buffering to allow immediate streaming of large files
        proxy_buffering off;
        proxy_request_buffering off;

        # Timeouts for large uploads/downloads
        proxy_read_timeout 600s;
        proxy_send_timeout 600s;
        send_timeout 600s;
    }
}

3. Enable Nginx Configuration

Enable the configuration and reload Nginx:

sudo ln -s /etc/nginx/sites-available/pingvin-share /etc/nginx/sites-enabled/
sudo nginx -t
sudo systemctl reload nginx

4. Obtain Let's Encrypt SSL Certificate

Run Certbot to automate SSL certificate acquisition and Nginx configuration updating:

sudo certbot --nginx -d share.example.com

Follow the interactive prompts to enable automatic redirection from HTTP to HTTPS.

Deploying the Stack

Start the Pingvin Share container in detached mode:

cd /opt/pingvin-share
docker compose up -d

Verify that the container is running and healthy:

docker compose ps
docker compose logs -f

Access your platform by navigating to https://share.example.com. Complete the initial setup wizard to register the admin account.

Post-Deployment & Production Configurations

Once the application is running, complete key configurations in the Admin Panel (https://share.example.com/admin/settings).

1. File Upload Limits

1. Navigate to Settings > General.
2. Update the App URL to https://share.example.com.
3. Set the Max upload size (GB). Ensure this value is equal to or less than the Nginx client_max_body_size directive (10G in our configuration block).

2. SMTP Mail Integration

SMTP is required to invite users, send password reset links, and share links directly via email. 1. Navigate to Settings > Email. 2. Configure your SMTP provider settings: * SMTP Host: smtp.sendgrid.net, smtp.mailgun.org, or your custom server. * SMTP Port: 465 (SSL) or 587 (TLS). * SMTP User: dU9f4oKINFDDnkJ10Sy5obyV SMTP authentication username. * SMTP Password: dU9f4oKINFDDnkJ10Sy5obyV SMTP authentication password/API key. * From Email: noreply@share.example.com * Enable TLS/SSL: Check according to your port configuration. 3. Click Save and test the connection.

3. Security Hardening

• Disable Public Registration: If you want to restrict the platform to personal use, navigate to Settings > General and disable Allow registration.
• Limit Download attempts: Enforce download limit constraints per share link in the share configuration window.
• Add password protection: Require password authorization on sensitive shares.

Backup and Restore

To backup your deployment, you only need to copy the data directory and the docker-compose.yml file.

Backup Command

Create a tar archive of the installation:

tar -czvf pingvin-share-backup.tar.gz -C /opt/pingvin-share .

Restore Command

To restore to a new server: 1. Extract the backup archive to /opt/pingvin-share. 2. Run docker compose up -d.