iTechGuides is reader-supported. When you buy through links on our site, we may earn an affiliate commission. As an Amazon Associate I earn from qualifying purchases. Learn more
Need a server to try this on? Antihost offers Linux VPS plans with NVMe storage, full root access and a 14-day free trial.
The reliable way to self-host Piwigo is to provision a Linux VPS with Nginx or Apache, a MySQL-compatible database, PHP 8.2 or newer, an image library, and storage for both your originals and Piwigo’s generated sizes. You can install it manually into the VPS web root or use Piwigo’s official Docker deployment. Docker is more repeatable and isolated; a manual install integrates directly with the operating system’s web stack.
Whichever route you choose, put the site behind HTTPS, keep the public URL independent of the Piwigo release number, and design backups for the database and photo/configuration files before you import a large library.
What a Piwigo VPS deployment contains
Piwigo is open-source web gallery software. A production installation is a small web application stack rather than a single executable:
- Web server: Nginx or Apache receives HTTPS requests and serves or proxies Piwigo.
- PHP: The current requirements list PHP 8.2 or newer.
- Database: MySQL 5.6 or newer, or MariaDB 10.1 or newer.
- Image processing: ImageMagick is recommended; GD is supported as an alternative.
- Optional media tools: ExifTool enables metadata-related plugins, and FFmpeg supports poster generation for the VideoJS use case.
- Storage: Keep the originals plus generated multiple-size images, thumbnails, logs, database files, and operating-system headroom.
Piwigo’s requirements do not specify a universal CPU, RAM, or maximum photo count. Size the VPS from the number and resolution of photos, the amount of thumbnail generation, concurrent visitors, and the plugins you intend to run. A small personal gallery and a public archive with frequent imports have very different workloads.
#1 Best Overall
- Read Before You Buy — No Video Output: These adapters support charging and USB 2.0 data transfer, but cannot transmit video signals. Except for standard USB webcams (which use USB data only), they are not compatible with HDMI/DisplayPort cables, video-capable USB-C hubs, or docking stations with video output.
- Convert USB-A Ports to USB-C: Designed to connect USB-C earphones, cables, flash drives, card readers, and other USB-C accessories to standard USB-A ports. Plug-and-play with no drivers or software required.
- Aluminum Alloy Housing: Built with a sturdy aluminum alloy shell that aids in heat dissipation and protects against daily wear and scratches. Designed to maintain a stable and secure connection.
- Compact & Travel-Friendly: The ultra-compact design allows the adapter to stay plugged into your device without blocking adjacent ports or adding bulk, reducing wear and tear on your original USB ports.
- 12-Month Warranty: Backed by a 12-month manufacturer warranty for peace of mind. Designed to meet strict quality control standards for reliable everyday performance.
Choose Docker or a manual installation
Both routes produce a normal Piwigo site. The difference is where the web stack lives and how you maintain it.
| Decision area | Official Docker deployment | Manual deployment |
|---|---|---|
| Isolation and repeatability | The application and database workflow are described by compose.yaml; recreating the stack is straightforward. |
Files use the VPS’s own PHP, web server, database, extensions, users, and service configuration. |
| Host integration | Container networking, volumes, port publishing, and proxy headers become part of the design. | Direct integration with the existing Nginx or Apache document root and system packages. |
| Updates | Back up data and configuration, then update the compose image or deployment as directed by the current Piwigo guide. | Check requirements, replace application files with the new release, and preserve the writable and user data directories. |
| Troubleshooting | Check container logs, service names, volumes, network connectivity, and reverse-proxy headers. | Check PHP modules, filesystem ownership, web-server rules, database access, and PHP/web-server logs. |
Choose Docker when you want a self-contained, repeatable stack and are comfortable with containers. Choose a manual install when the VPS already has a carefully managed PHP and database environment, or when you need direct host-level control. Neither option removes the need to manage operating-system security, TLS, updates, and backups.
The Tool Desk
Outbyte PC Repair FREEClear out junk files and repair common Windows errorsFree Scan →Outbyte Driver Updater FREEScan for outdated or missing drivers - takes under a minuteDriver Scan →Prepare the Linux VPS
1. Secure administrative access
Create a non-root administrator, use SSH keys where possible, apply the distribution’s security updates, and restrict inbound ports to the services you actually expose. The public web service normally needs TCP 80 and 443; the database should remain private unless you have a specific, secured remote-administration requirement.
2. Plan names, storage, and the public URL
Decide whether Piwigo will use a dedicated domain, a subdomain, or a subpath such as example.net/gallery. Keep the public directory or URL independent of a release number so an upgrade does not force a link change. Measure the available disk space against your originals and the additional generated sizes; photo directories can consume substantial space.
3. Install the stack or Docker
For a manual installation, install Nginx or Apache, PHP 8.2 or newer with the extensions required by your distribution, a supported MySQL-compatible server, and ImageMagick or GD. Add ExifTool or FFmpeg only when a plugin or video workflow requires them. For Docker, install Docker Engine and the Compose plugin, and verify that your SSH account can run Docker commands according to your distribution’s policy.
Route A: install Piwigo with the official Docker deployment
1. Create a dedicated directory
Use a directory that will remain stable across image updates, for example:
Rank #2
- 5-in-1 USB-C Hub: Experience comprehensive connectivity featuring a Power Delivery input, two USB-A 2.0 ports, a USB-A 3.0 port, and an HDMI port. (Note: The USB-C power delivery input port is only for connecting an external wall charger to power your laptop and cannot power peripheral devices.)
- 90W Pass-Through Charging: Achieve optimal charging with 90W pass-through power to your laptop, supported by a total input of 100W, with the hub reserving 10W for operational efficiency. (Note: Wall charger not included.)
- Quick Data Transfers: Accelerate your productivity with rapid data transfers using a high-speed 5Gbps USB 3.0 port and two 480Mbps USB 2.0 ports.
- 4K HDMI Display: Enhance your visual experience with a hub capable of delivering 4K resolution at 30Hz in both mirror and extend modes. Please note that this hub is compatible with MacBook (macOS 12 and newer), Windows 10 and 11, ChromeOS, and laptops equipped with DP Alt Mode and Power Delivery. Note: This device is not compatible with Linux.
- What You Get: Anker USB-C Hub (5-in-1, 4K HDMI), welcome guide, 18-month warranty, and our friendly customer service.
mkdir -p ~/piwigo
cd ~/piwigoDownload the official Piwigo compose.yaml into this directory from Piwigo’s Docker installation documentation. Do not rename the directory after you begin; stable paths make backups and service management less error-prone.
2. Create the environment file
Create .env beside compose.yaml. Set the variable names defined by the downloaded compose file for the published port, database password, timezone, and, if offered, the UID and GID that should own mounted files. Use a long, unique database password and protect the file from other local users:
chmod 600 .envDo not commit .env to a public repository. It contains deployment secrets and is part of the recovery set you must preserve.
3. Start the services and inspect logs
docker compose up -d
docker compose ps
docker compose logsThe first command starts the application and database in the background. Check that both services are running and read the logs for database initialization, permission errors, or a port conflict. If the published port is already occupied, change the port value in .env and recreate the services.
Do these 3 things before closing this tab:
1Repair Windows errors before they cause bigger problems2Scan for outdated or missing drivers - takes under a minute3Clear out junk files and repair common Windows errors4. Put Nginx in front of the container
Piwigo’s Docker guidance advises using a reverse proxy such as Nginx. Configure a server block for your domain and proxy the public location to the port published by Compose. A typical domain-based location is:
location / {
proxy_pass http://127.0.0.1:8080;
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;
}Use the actual published port from your .env; 8080 above is only an example. Test the Nginx configuration, reload it, and then obtain a TLS certificate for the domain through your normal certificate-management process.
Rank #3
- Sleek 7-in-1 USB-C Hub: Features an HDMI port, two USB-A 3.0 ports, and a USB-C data port, each providing 5Gbps transfer speeds. It also includes a USB-C PD input port for charging up to 100W and dual SD and TF card slots, all in a compact design.
- Flawless 4K@60Hz Video with HDMI: Delivers exceptional clarity and smoothness with its 4K@60Hz HDMI port, making it ideal for high-definition presentations and entertainment. (Note: Only the HDMI port supports video projection; the USB-C port is for data transfer only.)
- Double Up on Efficiency: The two USB-A 3.0 ports and a USB-C port support a fast 5Gbps data rate, significantly boosting your transfer speeds and improving productivity.
- Fast and Reliable 85W Charging: Offers high-capacity, speedy charging for laptops up to 85W, so you spend less time tethered to an outlet and more time being productive.
- What You Get: Anker USB-C Hub (7-in-1), welcome guide, 18-month warranty, and our friendly customer service.
For a subpath such as /gallery, proxy that location and pass the prefix as well:
location /gallery/ {
proxy_pass http://127.0.0.1:8080/;
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-Prefix /gallery;
}Keep the trailing slashes consistent with your chosen path, and test image URLs, administration pages, log-in redirects, and uploaded files. A missing forwarded prefix commonly causes links or redirects to omit the subpath.
5. Complete the browser installer
Open the domain or subpath in a browser. On the first run, enter the database host shown by the Compose setup (the documented service name is piwigo-db:3306), database user, password, database name, and table prefix. Then create the webmaster identifier, password, and email address and select Start Install. Sign in to the administration panel after the installer finishes.
6. Verify the result
- Confirm that the site loads through HTTPS, not only through the published local port.
- Upload a test image and verify that the original and generated sizes display.
- Check that the administration panel can create an album and that the database container remains healthy after a restart.
- Record the exact Compose directory, environment values, published port, and proxy configuration in your operational notes.
Route B: install Piwigo manually
1. Download and extract the full archive
Obtain the full Piwigo archive from the project’s official download channel, extract it on a trusted workstation or directly on the VPS, and transfer the extracted contents with an FTP client or another secure file-transfer method. Place them in the web root or a stable directory such as photos. The directory name should not contain the Piwigo release number.
2. Configure the web server and permissions
Point an Nginx or Apache virtual host at the extracted directory, enable PHP handling, and configure HTTPS for the domain. The web-server account must be able to read the application and write the directories Piwigo identifies as writable. Avoid making the entire tree world-writable. If you use a subpath, make sure the web-server rewrite rules and the site’s base URL agree.
3. Create a database and account
Create an empty MySQL or MariaDB database and a dedicated database user with a strong password. Grant that account access only to the Piwigo database. Note the database host, port, name, user, and password; the browser installer will request them.
Rank #4
- Dual Converters, Infinite Potential：Includes 2× USB C male to USB A female adapters and 2× USB A male to USB C female adapters. Perfect for a wide range of uses—tablets with Bluetooth keyboards, expand USB ports on macbook, and more. Two different converters for all your daily needs
- Next-Level 10Gbps & 3A Charging: No more slow 480Mbps, this usb to usb c adapter has a transfer speed of up to 10Gbps, allowing you to do more transferring in less time. This usb adapter fits both USB A and USB C charger, supporting up to 3A fast charging
- Upgraded Exquisite Craftsmanship: With an aluminum alloy housing and metal connector, the usbc to usb adapter is extremely durable and sturdy. Rigorously tested to withstand more than 10,000 times of plugging and unplugging, ensuring long-lasting performance
- Broad Compatible: The usb c to usb adapter widely supports all USB C/ USB A devices like laptops, tablets, cellphones, car chargers, and phone chargers. Such as compatible with MacBook Pro/Air 2023/2022, Thunderbolt 4/3 Devices,Apple MagSafe Watch 9/8/7/SE/Ultra, iPad Pro 2022/2021, Samsung Galaxy S23/S20/S10, and iPhone 17/16/15 Pro. Plug and play
- Please Note: To reach 10Gbps speed, keep the cable under 3.3 ft. For USB A Male to USB C adapters, try flipping the USB C connector. USB C Male to USB A adapters support bidirectional 10Gbps transfer within 3.3 ft
4. Run the browser installer
Open the selected domain or path. An uninstalled instance redirects to the installer. Enter the database host, user, password, database name, and table prefix, then create the webmaster account and email address. After installation, sign in, upload a test image, and confirm that thumbnails and resized images are generated.
5. Keep application and user data separate
During future upgrades, replace the application files only after checking the new release’s requirements. Preserve the directories containing galleries, uploads, and local customizations. A stable public directory prevents an upgrade from changing every gallery URL.
Backups and upgrades
What to back up before an update
Before a Docker update, make a database dump and copy each of the following artifacts:
What’s actually slowing this PC down?
Pick the symptom - the matching free tool is one click away.
- The Piwigo database dump.
galleries, containing gallery content managed by the installation.upload, containing uploaded content.local, containing local configuration and customization.compose.yamland.env, which describe and configure the container deployment.
For a manual installation, use the same database-and-data principle and additionally preserve the web-server configuration and any deployment scripts you maintain. Keep at least one backup copy away from the VPS, because a disk failure, account compromise, or accidental deletion can affect every local copy.
Make and verify a database dump
Use the database tools supplied by your distribution and the credentials for the Piwigo account. For a database named piwigo, a transaction-consistent MySQL dump can be created with:
mysqldump --single-transaction --routines --events piwigo > piwigo.sqlStore the dump with the corresponding date and deployment version, restrict its permissions, and confirm that it can be read. A backup is not complete until you have periodically performed a test restore into an isolated database or temporary instance.
Best Value
- 5-in-1 Connectivity: Equipped with a 4K HDMI port, a 5 Gbps USB-C data port, two 5 Gbps USB-A ports, and a USB C 100W PD-IN port. Note: The USB C 100W PD-IN port supports only charging and does not support data transfer devices such as headphones or speakers.
- Powerful Pass-Through Charging: Supports up to 85W pass-through charging so you can power up your laptop while you use the hub. Note: Pass-through charging requires a charger (not included). Note: To achieve full power for iPad, we recommend using a 45W wall charger.
- Transfer Files in Seconds: Move files to and from your laptop at speeds of up to 5 Gbps via the USB-C and USB-A data ports. Note: The USB C 5Gbps Data port does not support video output.
- HD Display: Connect to the HDMI port to stream or mirror content to an external monitor in resolutions of up to 4K@30Hz. Note: The USB-C ports do not support video output.
- What You Get: Anker 332 USB-C Hub (5-in-1), welcome guide, our worry-free 18-month warranty, and friendly customer service.
Copy large photo directories safely
Use a transfer method that preserves file names, timestamps where useful, and interrupted-copy recovery. Check the destination size and file counts after copying; a successful command does not prove that every original and generated file is present. Encrypt backups at rest when they leave the VPS, and document where the encryption key is held.
Quick wins for a faster PC:
Scan for outdated or missing drivers - takes under a minuteDriver Scan →Clear out junk files and repair common Windows errorsFree Scan →Fix the driver behind crashes, sound loss and screen glitchesFind Drivers →Apply the update
- Schedule a maintenance window and stop imports or bulk edits.
- Create and verify the database and file backups.
- Read the target release requirements and migration notes.
- For Docker, update the image or Compose definition as directed, then recreate the services and inspect logs.
- For a manual install, replace the application files while preserving the user-data directories and configuration.
- Open the site and administration panel, test a gallery and a fresh upload, and watch logs for PHP, database, or permission errors.
Self-hosted operators own their backup and redundancy design. Piwigo’s hosted service advertises regular backups and replication to a standby server, but those protections do not automatically apply to a VPS you administer.
Independent reader supportYour contribution helps us test, update, and keep practical guides available for everyone.Permissions, ownership, and the Piwigo CLI
Ownership mistakes often appear after an upgrade, a restore, or a container recreation. The web-server user differs between a plain Apache installation, Docker, and other layouts, so do not blindly apply a username from another tutorial. Check which account runs the PHP/web process, inspect the ownership of galleries, upload, and local, and grant only the write access Piwigo needs.
Piwigo’s official command-line tooling can diagnose ownership and perform gallery database backups. Use it when the installation layout supports the tool, and run diagnostics after changes to containers, PHP packages, or filesystem mounts. If a command reports a mismatch, correct ownership for the actual runtime account rather than making files globally writable.
Troubleshooting by symptom
The browser shows a connection failure
- Confirm that the Compose services or PHP/web-server services are running.
- Check that the published port in
.envmatches Nginx’sproxy_pass. - Verify the VPS firewall and cloud firewall allow HTTPS.
- Inspect container or web-server logs for a startup failure.
The installer cannot connect to the database
- For Docker, use the database service host and port from the Compose definition, not
localhostinside the application container. - Verify the database name, user, password, and table prefix.
- Wait for first-time database initialization to finish, then inspect the database service logs.
- For manual installs, confirm that the database account is allowed to connect from the web server and that the database service is listening on the expected address.
Images upload but thumbnails fail
- Confirm ImageMagick or GD is installed and available to the PHP runtime.
- Check free disk space; generated sizes can substantially increase storage use.
- Inspect ownership and write permissions on the relevant gallery and upload directories.
- Review PHP memory and execution limits if processing large originals times out.
Redirects or links lose the subpath
Check that Nginx sends X-Forwarded-Prefix with the exact path, that X-Forwarded-Proto reflects HTTPS, and that the proxy’s trailing-slash behavior matches the location. Test both a fresh browser session and an existing administrator session.
Recommended Free Tools
The site breaks after an upgrade
Read the application, PHP, database, and proxy logs together. Confirm that the new release still meets the PHP and database floors, restore the pre-update database and preserved directories if necessary, and correct ownership before retrying. Do not delete the only copy of the previous application or its configuration until the upgraded site has passed your tests.
A practical operating checklist
- Use a dedicated domain, subdomain, or stable subpath; never tie the public URL to a release number.
- Terminate HTTPS at Nginx or Apache and forward the original host, client address, protocol, and, for subpaths, prefix.
- Keep the database private and use a dedicated account.
- Monitor disk usage for originals and generated sizes.
- Keep Piwigo, PHP, the database, Docker (if used), and the Linux host patched.
- Back up the database,
galleries,upload,local, and deployment configuration before updates. - Store a copy off the VPS and test restoration on a schedule.
- After every upgrade, test login, album browsing, a new upload, thumbnail generation, and administrator functions.
The Bottom Line
For most new VPS deployments, the official Docker route is the easiest to reproduce: keep compose.yaml and .env in a stable directory, place Nginx in front of the published port, and complete the browser installer. Choose a manual install when direct integration with an existing PHP stack matters more than isolation. In both cases, the decisive operational work is sizing storage correctly and maintaining tested, off-site backups of the database and Piwigo’s data directories.
Quick Recap
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.
