How to Self-Host Pingvin Share on a VPS with Docker, HTTPS, and Large-Upload Support

The linked file is the project's Compose example. Because the original repository is archived, treat a raw download from its default branch as an operational example rather than an immutable production pin. Review the image owner, tag, release notes, and security advisories before deploying; use a reviewed release or maintained fork when appropriate.

Understand the required mounts and settings

A representative Compose service has the following shape:

Rank #2

Sale

UGREEN NAS DH2300 2-Bay for Beginners & Personal Users, Phone Backup | AI Album, Private Cloud/Remote Access, File Sharing, Multi-Device Backup, Home Entertainment, 4GB RAM on Board (Diskless)

• Entry-level NAS Personal Storage：UGREEN NAS DH2300 is your first and best NAS made easy. It is designed for beginners who want a simple, private way to store videos, photos and personal files, which is intuitive for users moving from cloud storage or external drives and move away from scattered date across devices. This entry-level NAS 2-bay perfect for personal entertainment, photo storage, and easy data backup (doesn't support Docker or virtual machines).
• Set Your Devices Free, Expand Your Digital World: This unified storage hub supports massive capacity up to 64TB.*Storage drives not included. Stop Deleting, Start Storing. You can store 22 million 3MB images, or 2 million 30MB songs, or 43K 1.5GB movies or 67 million 1MB documents! UGREEN NAS is a better way to free up storage across all your devices such as phones, computers, tablets and also does automatic backups across devices regardless of the operating system—Window, iOS, Android or macOS.
• The Smarter Long-term Way to Store: Unlike cloud storage with recurring monthly fees, a UGREEN NAS enclosure requires only a one-time purchase for long-term use. For example, you only need to pay $459.98 for a NAS, while for cloud storage, you need to pay $719.88 per year, $2,159.64 for 3 years, $3,599.40 for 5 years. You will save $6,738.82 over 10 years with UGREEN NAS! *NAS cost based on DH2300 + 12TB HDD; cloud cost based on 12TB plan (e.g. $59.99/month).
• Blazing Speed, Minimal Power: Equipped with a high-performance processor, 1GbE port, and 4GB RAM on Board, this NAS handles multiple tasks with ease. File transfers reach up to 125MB/s—a 1GB file takes only 8 seconds. Don't let slow clouds hold you back; they often need over 100 seconds for the same task. The difference is clear.
• Let AI Better Organize Your Memories: UGREEN NAS uses AI to tag faces, locations, texts, and objects—so you can effortlessly find any photo by searching for who or what's in it in seconds. It also automatically finds and deletes similar or duplicate photo, backs up live photos and allows you to share them with your friends or family with just one tap. Everything stays effortlessly organized, powered by intelligent tagging and recognition.

$239.99

Buy on Amazon

services:
  pingvin-share:
    image: stonith404/pingvin-share
    restart: unless-stopped
    ports:
      - '3000:3000'
    environment:
      TRUST_PROXY: 'false'
    volumes:
      - ./data:/opt/app/backend/data
      - ./data/images:/opt/app/frontend/public/img

The image can also be pulled from the project's GitHub Container Registry equivalent when that is the image source you have reviewed. Keep the two volume mappings even when you change the image reference. The first preserves the database and application state; the second preserves uploaded or generated image assets. A container recreation without those mounts can leave the service apparently empty or missing images.

The sample sets TRUST_PROXY=false because it assumes direct access during initial installation. Change it to true after placing a correctly configured reverse proxy in front of the application.

Start and inspect the container

1. From ~/pingvin-share, create the host directories explicitly: mkdir -p data/images.
2. Start the service in the background: docker compose up -d.
3. Check container state: docker compose ps. The service should show as running.
4. Read startup output if it is not healthy: docker compose logs --tail=200 pingvin-share.
5. From the VPS itself, test the documented listener with curl -I http://127.0.0.1:3000.

The installation guide documents the result as a site listening on http://localhost:3000. That address is useful for local verification; it is not the final public URL.

Put a domain and HTTPS in front

Use an external reverse proxy

Terminate TLS at Caddy, Nginx, Traefik, or another reverse proxy and forward the complete application path to port 3000. A minimal Caddy configuration for a host where Caddy runs on the VPS is:

share.example.com {
    reverse_proxy 127.0.0.1:3000
}

Replace the example hostname with the DNS name you configured. Caddy can obtain and renew a certificate when ports 80 and 443 are reachable. Other proxies require their own certificate and renewal configuration.

Set the Compose environment value to trust the proxy:

environment:
  TRUST_PROXY: 'true'

Recreate the service after changing the environment:

docker compose up -d

If you disable Pingvin Share's built-in Caddy layer with CADDY_DISABLED=true, the configuration reference requires the external proxy to map all application paths correctly. A proxy that forwards only the home page can make login, uploads, or static assets fail even though the root URL loads.

Rank #3

Synology DS225+ Private Cloud Media Server - Stream, Back Up Photos & Share Files, Intel CPU for Hardware Transcoding (2-Bay Diskless NAS)

• Your Personal Streaming Server - Build your own Netflix-style media library and stream 4K movies, shows and photos to any device without monthly fees
• Create Your Own Cloud - Store your entire photo, video and music collection; access from anywhere with fast 282 MB/s transfer speeds
• Creator-Grade Backup Solution - Protect your irreplaceable content with automated backups to cloud services, external drives and remote NAS
• Multi-Layered Data Protection - Combine RAID redundancy, automated backups and snapshot technology to prevent data loss from any cause
• Smart Home Surveillance - Support up to 30 IP cameras with AI detection, instant alerts and secure remote monitoring

$364.99

Buy on Amazon

Keep the direct port private

Do not expose an unauthenticated administrative interface directly on a public port. Bind the application to the VPS and let the reverse proxy be the Internet-facing service, or restrict port 3000 at the firewall to localhost and the proxy network. Use a strong administrator password and protect SSH with keys, limited source addresses, and current host updates.

Account for proxy limits

Every proxy in the chain can impose a request-body limit, timeout, buffering policy, or maximum header size. Set those deliberately for the largest files you expect to transfer. A successful small-file test does not prove that a multi-gigabyte upload will work; test through the real HTTPS hostname after changing proxy settings.

Persist data and build a backup routine

Know the persistence boundary

The two Compose mounts are the persistence boundary:

• ./data:/opt/app/backend/data stores application state and the database.
• ./data/images:/opt/app/frontend/public/img stores frontend image assets.

The default configuration reference identifies DATA_DIRECTORY=./data and a SQLite URL of file:../data/pingvin-share.db?connection_limit=1. This is why backing up only a container layer, or only the database file, is insufficient.

Back up both directories

For a simple local backup, stop the application briefly so SQLite and file writes are quiescent, archive both directories, then start the service again:

cd ~/pingvin-share
docker compose stop
tar -czf pingvin-share-$(date +%F).tar.gz data
docker compose start

Copy the archive off the VPS. A backup that remains on the same disk does not protect against disk loss or a compromised host. Keep a retention schedule that matches how long users expect shares to remain available, and periodically perform a restoration on a separate directory or test host. Do not consider a backup usable until you have opened the restored database and verified representative uploaded files and images.

Plan storage separately from the database

SQLite is the documented default. For a heavy workload, evaluate storage throughput, free space, concurrent transfers, and database strategy independently; no official performance benchmark or minimum-resource profile is published. Avoid filling the filesystem: leave room for temporary upload data, logs, and at least one local recovery archive.

Make large uploads reliable

The installation guide states that Pingvin Share uses a built-in reverse proxy by default to reduce installation steps, but also warns: “However, this reverse proxy is not optimized for uploading large files.” For large-file workloads, use the Docker installation and an external reverse proxy such as Caddy.

Rank #4

Sale

UGREEN NAS DH4300 Plus 4-Bay for Beginners, Home Users & Remote Workers

• Entry-level NAS Home Storage: The UGREEN NAS DH4300 Plus is an entry-level 4-bay NAS that's ideal for home media and vast private storage you can access from anywhere and also supports Docker but not virtual machines. You can record, store, share happy moment with your families and friends, which is intuitive for users moving from cloud storage, or external drives to create your own private cloud, access files from any device.
• Smart Photo Backup & AI Album: Automatically back up photos and videos from your phone in real time and keep growing family memories organized with AI-powered photo albums. Semantic search, custom learning, and recognition of people, objects, pets, and similar photos help you quickly find the moments you want. Duplicate photo removal also helps keep your library organized—ideal for families and users with large photo collections.
• User-Friendly App & Easy Setup: Connect quickly via NFC, set up simply and share files fast on Windows, macOS, Android, iOS, web browsers, and smart TVs. You can access data remotely from any of your mixed devices. What's more, UGREEN NAS enclosure comes with beginner-friendly user manual and video instructions to ensure you can easily take full advantage of its features.
• More Cost-effective Storage Solution: Unlike cloud storage with recurring monthly fees, A UGREEN NAS enclosure requires only a one-time purchase for long-term use. For example, you only need to pay $629.99 for a NAS, while for cloud storage, you need to pay $719.88 per year, $1,439.76 for 2 years, $2,159.64 for 3 years, $7,198.80 for 10 years. You will save $6,568.81 over 10 years with UGREEN NAS! *NAS cost based on DH4300 Plus + 12TB HDD; cloud cost based on 12TB plan (e.g. $59.99/month).
• Your Data, You Control：No third-party clouds, no hidden access, UGREEN NAS provides a more secure and private data storage solution. It stores data locally on your private hard drives and does automatic backups. Thus, you can keep full control over it. The advanced encryption is TRUSTe certified in the United States and is awarded the first (and only) ETSI EN 303 645 certification mark for NAS products by TÜV SÜD Group.

$364.98

Buy on Amazon

Configure the entire request path

For the maximum file size you intend to accept, check each layer in order:

1. The browser or client must be able to maintain a long-running HTTPS request.
2. The public reverse proxy must allow a request body at least as large as the file and must not time out an idle or slow transfer.
3. The proxy must forward the upload method, headers, and complete path to port 3000.
4. The VPS firewall, load balancer, and any CDN in front of the VPS must permit the same body size and duration.
5. The host filesystem must have enough free space for the upload and resulting retained share.

Proxy-specific directives and defaults vary, so the Pingvin documentation does not prescribe universal body-size or timeout numbers. Set them from your real workload, then test a file near the intended limit over the public hostname. Watch docker compose logs -f pingvin-share and the proxy log while testing.

Recognize limit failures

• A rejection before the request reaches the container usually indicates a reverse-proxy body-size limit.
• A disconnect after a fixed interval usually indicates a proxy, load-balancer, or client timeout.
• A completed upload followed by a missing share points to storage exhaustion, permissions, or a failed application write.
• Uploads that work on localhost:3000 but fail over HTTPS indicate a proxy-path or proxy-limit problem rather than a Docker networking problem.

Optional scanning and integrations

ClamAV malware scanning

ClamAV is optional. The configuration reference documents CLAMAV_HOST and CLAMAV_PORT; the host default is 127.0.0.1 for a local service or clamav when running it as a Docker service, and the documented port is 3310. Make sure the Pingvin container can resolve and reach that host on the configured network. If scanning is enabled before ClamAV is reachable, uploads may fail or remain pending, so verify the scanner connection in logs before making it a production requirement.

Identity and storage options

The project README lists OIDC, LDAP, local storage, S3, expiration dates, visitor limits, and password-protected shares as capabilities. Treat these as separate design choices:

• Use OIDC or LDAP when account lifecycle and centralized authentication matter.
• Use local storage for the simplest single-VPS arrangement.
• Evaluate S3-compatible storage when object capacity or independent storage durability is more important than keeping files on the VPS disk.
• Set expiration dates, visitor limits, and share passwords according to the sensitivity and retention policy of your files.

These features do not remove the need to protect the VPS, reverse proxy, and backups.

Archived project and maintained-fork decisions

The original Pingvin Share README marks the project “Project Archived” and says it “has been archived since Jun 29, 2025.” That status matters when choosing an image: an old container can continue running, but it should not automatically be treated as a maintained security release.

Pingvin Share X presents itself as a fork, documents Docker Compose installation, and publishes a beta image channel. Its standalone instructions require Node.js 22 or newer, while the original standalone installation documentation required Node.js 16 or newer.

Before switching images, back up data and data/images, compare environment variables and database expectations, and test the fork on a copy of the data. Verify the image owner, release tag, security advisories, and rollback procedure. A Compose file that starts successfully does not prove that an existing database is compatible.

Best Value

Synology 2-Bay DiskStation DS223j (Diskless)

• Secure private cloud - Enjoy 100% data ownership and multi-platform access from anywhere
• Easy sharing and syncing - Safely access and share files and media from anywhere, and keep clients, colleagues and collaborators on the same page
• Automated Backup Protection - Set-and-forget backups for Macs, PCs and mobile devices to multiple destinations including cloud and external drives
• Home Security System - Record and monitor your property 24/7 with support for multiple IP cameras and remote viewing
• 2-Year Warranty - Reliable hardware backed by Synology's expert customer support team and ongoing software updates

$209.99

Buy on Amazon

Security and maintenance checklist

• Use SSH keys and restrict SSH exposure to the addresses or VPN users that administer the VPS.
• Allow only the ports required by SSH and the HTTPS reverse proxy; keep the application port private.
• Use a unique, strong administrator credential and do not reuse it elsewhere.
• Keep the host operating system, Docker Engine, Compose plugin, reverse proxy, and selected container image current.
• Review image tags instead of silently tracking an unreviewed latest build.
• Back up both persistent directories and test restoration on a schedule.
• Monitor disk space, failed containers, proxy errors, and unusually long-running uploads.
• Document who can access the VPS, where backups are stored, and how to revoke access.

Troubleshooting by symptom

The container exits immediately

Run docker compose logs --tail=200 pingvin-share. Check for a malformed Compose file, an image-pull failure, an occupied port, or a filesystem permission error on data. Confirm that the host has free disk space and that Docker can create the two bind-mounted directories.

The browser shows a 502 or connection refused

Verify docker compose ps, then test curl -I http://127.0.0.1:3000 on the VPS. If localhost fails, fix the container first. If localhost succeeds, inspect the reverse proxy upstream address, its network reachability, and whether it forwards to port 3000 rather than the documented backend port 8080.

HTTPS redirects loop or the scheme is wrong

Confirm that TLS terminates at one intended proxy, that the proxy forwards the original request information, and that TRUST_PROXY=true is set in Pingvin Share when the proxy is in front. Recreate the container after changing the variable.

Static images or a share page is missing

Check that the proxy maps every path, not just /, and that ./data/images is mounted at /opt/app/frontend/public/img. If you set CADDY_DISABLED=true, recheck the external proxy path rules.

Data disappeared after an update

Inspect the Compose file for removed or changed volume mappings. The application data and image assets must remain on the host at ./data and ./data/images. Stop the service, restore both directories from the same backup set, and start the reviewed image again.

ClamAV cannot be reached

Check the configured host and port, DNS or Docker service naming, and network membership. The documented port is 3310; a host value of 127.0.0.1 refers to the Pingvin container itself when ClamAV is in a separate container, so use the Docker service name in that arrangement.

Update and recovery runbook

1. Read the image release notes and check for database or environment-variable changes.
2. Confirm that a recent backup contains both data and data/images.
3. Record the currently running image tag with docker compose images.
4. Pull the reviewed image, then recreate the service with docker compose pull followed by docker compose up -d.
5. Check docker compose ps, application logs, the public HTTPS URL, login, a small upload, and a download.
6. If validation fails, stop the service, restore the previous image reference and backup, and document the cause before trying again.

This process separates an application-image change from a data migration and gives you a defined rollback point.

The Bottom Line

For a dependable VPS deployment, run Pingvin Share with Docker Compose, persist both host data directories, terminate HTTPS at a properly configured external proxy, and set TRUST_PROXY=true behind that proxy. Treat large uploads and the archived original repository as operational risks: tune the proxy deliberately, back up and test restoration, and verify a maintained fork or reviewed image before production use.

Quick Recap

SaleBestseller No. 1

UGREEN NAS DXP2800 2-Bay for Advanced Home Users, Remote Workers & Creators | Home Media & Data Center, Docker & VM, Plex, Fast File Transfer, Intel N100, 8GB DDR5, 2.5GbE, 2x M.2 NVMe, 4K HDMI(Diskless)

$389.99

SaleBestseller No. 2

UGREEN NAS DH2300 2-Bay for Beginners & Personal Users, Phone Backup | AI Album, Private Cloud/Remote Access, File Sharing, Multi-Device Backup, Home Entertainment, 4GB RAM on Board (Diskless)

$239.99

Bestseller No. 3

Synology DS225+ Private Cloud Media Server - Stream, Back Up Photos & Share Files, Intel CPU for Hardware Transcoding (2-Bay Diskless NAS)

$364.99

SaleBestseller No. 4

UGREEN NAS DH4300 Plus 4-Bay for Beginners, Home Users & Remote Workers

$364.98

Bestseller No. 5

Synology 2-Bay DiskStation DS223j (Diskless)

Secure private cloud - Enjoy 100% data ownership and multi-platform access from anywhere

$209.99

Product prices and availability are accurate as of the date/time indicated and are subject to change. Any price and availability information displayed on Amazon at the time of purchase will apply.