The reliable production path is to run ProcessWire behind Apache with PHP 8.x, create a dedicated MySQL or MariaDB database, enable mod_rewrite and .htaccess overrides, then complete the browser installer. On a new Ubuntu VPS, plan for package updates, SSH and firewall hardening, TLS, backups and monitoring as well as the application itself. This guide covers the prerequisites, three official installation methods, Apache configuration, permissions, cleanup and the fixes for the common “homepage works but internal URLs fail” problem.
Antihost offers Linux VPS plans with full root access, unlimited traffic on a 1 Gbps port and a 14-day free trial.
What ProcessWire needs on an Ubuntu VPS
ProcessWire requires an Apache-compatible web server, PHP (8.x is recommended), PDO database support, MySQL 5.6 or newer or an equivalent MariaDB release, Apache rewrite support with working .htaccess files, and either PHP GD2 or ImageMagick for image handling. The mbstring extension is recommended. Apache is the officially supported web server; nginx can be used only when you reproduce the required rewrite and security rules yourself.
As an Amazon Associate I earn from qualifying purchases.
Recommended Free Tools
| Component | Requirement or recommendation | What to verify |
|---|---|---|
| Operating system | Supported Ubuntu release with current security updates | lsb_release -a and successful package updates |
| Web server | Apache 2 with mod_rewrite and AllowOverride enabled for the site |
apache2ctl -M | grep rewrite |
| PHP | PHP 8.x recommended | php -v |
| Database | MySQL 5.6+ or a compatible MariaDB release | Server version and a login using the new application account |
| PHP database access | PDO with the MySQL driver | php -m | grep -E 'PDO|pdo_mysql' |
| Image processing | GD2 or ImageMagick | php -m | grep -E 'gd|imagick' |
| Text handling | mbstring recommended |
php -m | grep mbstring |
| Privileges | SSH account with sudo access during setup |
sudo -v |
Choose the ProcessWire release and deployment method
Use the master release channel for a production site. The ProcessWire download page reported master 3.0.259 and dev 3.0.274 when checked; those numbers are time-sensitive, so confirm the current download page immediately before downloading. The dev channel is for people who deliberately need unreleased changes and can accept more change between updates.
| Method | Initial deployment | Version control and repeatability | Best fit |
|---|---|---|---|
| ZIP archive | Download, extract into the document root and open the site URL | You must record the archive version and manage later replacements yourself | A straightforward single VPS or a first installation |
| Git | Clone the repository into the intended web root | Convenient for source-controlled deployments and explicit commits | Operators already using Git-based release workflows |
| Composer | Run composer create-project processwire/processwire |
Supports projects that already manage PHP dependencies with Composer | A codebase organized around Composer |
All three methods are official. None is universally best: ZIP minimizes moving parts, Git fits a repository workflow, and Composer is most natural when dependency management is already part of the project.
Prepare Ubuntu and secure basic network access
Log in and update packages
Use a sudo-capable account rather than running the application as root. Replace the example host name in later commands with the domain that will point to this VPS.
ssh [email protected]
sudo apt update
sudo apt full-upgrade -yReboot if the package manager reports that the running kernel or core services require it, then reconnect over SSH.
Free tools Windows power users keep installed
One-click scans. No signup required.
Configure the firewall before exposing the web server
Ubuntu’s UFW can allow SSH and the two web ports while leaving other inbound services closed. If your provider supplies an external firewall, apply equivalent rules there as well.
sudo ufw allow OpenSSH
sudo ufw allow 80/tcp
sudo ufw allow 443/tcp
sudo ufw enable
sudo ufw status verboseDo not enable the firewall until you have confirmed that the SSH rule matches the port and source you actually use; otherwise you can lock yourself out.
Install Apache, PHP, the database driver and image support
Ubuntu package names track the release’s supported PHP version. The following installs the common Apache and PHP packages; if your Ubuntu release names a versioned package differently, use its supported equivalent and verify the resulting modules.
sudo apt install -y apache2 mysql-server php libapache2-mod-php php-mysql php-mbstring php-gd php-xml unzip gitImageMagick is an alternative to GD. Install it, together with the PHP binding, when that is your preferred image stack and the packages are available for the Ubuntu release:
The Tool Desk
Outbyte Driver Updater FREEScan for outdated or missing drivers - takes under a minuteDriver Scan →Outbyte PC Repair FREERepair Windows errors before they cause bigger problemsFix Now →sudo apt install -y imagemagick php-imagickComposer is needed only for the Composer deployment route:
sudo apt install -y composerEnable Apache rewrite support and restart Apache after the PHP packages are in place:
sudo a2enmod rewrite
sudo systemctl enable --now apache2 mysql
sudo systemctl restart apache2Check the actual PHP build rather than assuming the package installed every extension:
php -v
php -m | grep -E 'PDO|pdo_mysql|mbstring|gd|imagick'
apache2ctl -M | grep rewrite
sudo systemctl --no-pager --full status apache2 mysqlYou need pdo_mysql, and at least one of gd or imagick. If an expected module is absent, install the matching Ubuntu package, restart Apache and run the checks again.
Create a dedicated database and least-privilege account
Do not give the web application a general-purpose administrative database login. Create one database and one account used only by this ProcessWire installation. The following example uses database name processwire and account name processwire_app; choose a long unique password and keep it in your password manager.
sudo mysqlCREATE DATABASE processwire CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci;
CREATE USER 'processwire_app'@'localhost' IDENTIFIED BY 'use-a-long-unique-password';
GRANT ALL PRIVILEGES ON processwire.* TO 'processwire_app'@'localhost';
FLUSH PRIVILEGES;
EXIT;The grant is limited to the new database, not to every database on the server. Record the database name, host (localhost in this example), user and password; the browser installer will request them.
Create the Apache virtual host
Create the document root
sudo mkdir -p /var/www/processwire
sudo chown -R $USER:www-data /var/www/processwire
sudo chmod 755 /var/www/processwireThe ownership shown is a workable starting point for copying files as your administrative user. You will refine ownership and write access after installation so that Apache can write only where ProcessWire needs it.
Write a site-specific virtual-host file
Create /etc/apache2/sites-available/processwire.conf with a text editor and use the domain that will resolve to the VPS:
<VirtualHost *:80>
ServerName example.com
ServerAlias www.example.com
DocumentRoot /var/www/processwire
<Directory /var/www/processwire>
Options FollowSymLinks
AllowOverride All
Require all granted
</Directory>
DirectoryIndex index.php index.html
ErrorLog ${APACHE_LOG_DIR}/processwire-error.log
CustomLog ${APACHE_LOG_DIR}/processwire-access.log combined
</VirtualHost>AllowOverride All is important because ProcessWire’s root .htaccess contains its rewrite and access rules. Without it, Apache may serve the homepage but fail to route page URLs correctly.
Enable and test the host
sudo a2ensite processwire.conf
sudo a2dissite 000-default.conf
sudo apache2ctl configtest
sudo systemctl reload apache2The configuration test must report Syntax OK. If it does not, fix the reported directive before continuing. Ensure the DNS A or AAAA record for the domain points to the VPS before using the browser installer.
Put ProcessWire in the document root
ZIP installation
Download the current master ZIP from ProcessWire’s official download page on your local computer or the VPS, then copy it to the server. Extract it directly into /var/www/processwire; avoid creating an extra nested directory such as /var/www/processwire/processwire-master.
scp processwire-master.zip [email protected]:/tmp/
ssh [email protected]
sudo unzip /tmp/processwire-master.zip -d /var/www/processwireIf the archive itself contains a top-level directory, move that directory’s contents up one level so that index.php, .htaccess, wire and site are immediately inside the configured document root.
Git installation
Clone the official repository into the empty document root:
sudo rm -rf /var/www/processwire/*
sudo git clone https://github.com/processwire/processwire.git /var/www/processwireFor production, check out the release or commit you have approved rather than deploying an unreviewed moving branch. Keep the working tree and your update procedure under source control.
Composer installation
From the intended web-root directory, run the official create-project command:
cd /var/www
sudo composer create-project processwire/processwire processwireComposer may create files owned by root when run with sudo. Correct the resulting ownership before opening the installer, and use a deployment process that records the resolved dependency versions.
What’s actually slowing this PC down?
Pick the symptom - the matching free tool is one click away.
Run the browser installer
Open the domain in a browser. ProcessWire’s installer checks the server environment and then asks for the database connection, site profile, administrator account and other setup values.
- Choose the installation profile that matches the site you intend to build.
- Enter the database name, host, user and password created earlier. Keep the host consistent with the account definition;
localhostand a network address can be treated differently by MySQL authentication. - Create a strong administrator name and password. Do not reuse the database password.
- Review the installer’s PHP and filesystem warnings. Resolve missing extensions or write permissions before proceeding instead of ignoring them.
- Complete the installation and sign in to the administrator area to confirm that pages, templates and assets load.
During setup, ProcessWire writes its database settings to site/config.php and creates the site asset structure. The installation is not finished until the cleanup and permission steps below are complete.
Remove installer files and tighten permissions
Delete setup entry points
After a successful installation, remove the installer script and installation directory from the ProcessWire root:
cd /var/www/processwire
sudo rm -f install.php
sudo rm -rf site/installLeaving these files available creates an unnecessary setup surface and can allow an accidental reinstall attempt.
Protect the configuration file
site/config.php contains database credentials. ProcessWire’s security guidance identifies it as the file that must not be readable by unrelated system users, other than the operator and Apache. Confirm its owner and mode:
sudo chown www-data:www-data /var/www/processwire/site/config.php
sudo chmod 640 /var/www/processwire/site/config.phpIf your deployment model uses a different Apache user or a shared administrative group, use that model instead; the requirement is that the web process can read the file while other users cannot.
Allow writes only where ProcessWire needs them
ProcessWire commonly needs to write under site/assets for uploaded files, generated images, caches and logs. Grant the web process access to the required directories, then keep code and configuration read-only where possible. A possible baseline is 755 for directories and 644 for regular files, provided those modes match your ownership model. Do not use broad 777 directory or 666 file permissions.
Crashes, No Sound, or Screen Glitches?
Random freezes, missing sound and display glitches usually trace back to one bad driver. Find and replace yours safely.Free scan · under a minuteWindows Errors? Fix Them Before They Spread
Repair common Windows errors and clear accumulated junk for a smoother, more stable PC - no reinstall needed.Free scan · no reinstallsudo find /var/www/processwire -type d -exec chmod 755 {} ;
sudo find /var/www/processwire -type f -exec chmod 644 {} ;
sudo chown -R www-data:www-data /var/www/processwire/site/assetsRun the file-mode commands only after you have verified which account performs deployments. If your deployment user must update code, use a shared group or a release-and-symlink workflow rather than making the entire tree writable by Apache.
Finish production hardening
- Install a TLS certificate and redirect HTTP to HTTPS once DNS resolves correctly.
- Keep Ubuntu, Apache, PHP, the database server and ProcessWire updated on a planned schedule. Review release notes before changing the production channel.
- Use SSH keys, disable password authentication after verifying key access, and restrict SSH exposure where your environment permits it.
- Back up the database and the ProcessWire
sitedirectory, especially uploaded assets and configuration. Test restoring a backup rather than assuming that a completed job is usable. - Monitor disk space, memory, Apache and database service health, TLS expiry and application error logs.
- Do not leave verbose PHP or ProcessWire debugging enabled on a public production site.
A VPS provides an isolated, dedicated environment suitable for production, but it does not provide automatic patching, backups, TLS or monitoring. Those remain the operator’s responsibility.
Independent reader supportYour contribution helps us test, update, and keep practical guides available for everyone.Troubleshoot the common installation failures
The homepage works but internal URLs return 404
This almost always points to Apache not applying ProcessWire’s rewrite rules. Confirm that the virtual host’s <Directory> block points to the same directory as DocumentRoot and contains AllowOverride All. Confirm the module and reload Apache:
apache2ctl -M | grep rewrite
sudo apache2ctl configtest
sudo systemctl reload apache2Check that the root .htaccess file exists and was not omitted when extracting the archive. In configurations where Apache serves the site from a subdirectory, review ProcessWire’s annotated .htaccess directives and set an appropriate RewriteBase rather than copying a rule blindly.
Quick wins for a faster PC:
Fix the driver behind crashes, sound loss and screen glitchesFind Drivers →Clear out junk files and repair common Windows errorsFree Scan →Changing .htaccess produces HTTP 500
Read the Apache error log immediately after reproducing the error:
sudo tail -n 50 /var/log/apache2/processwire-error.log
sudo journalctl -u apache2 -n 50 --no-pagerRestore the last known-good .htaccess, then test one directive change at a time. A syntax error, an unsupported directive or an override that is not permitted can all produce a 500 response. Always run apache2ctl configtest after editing the virtual-host file.
A blank page or unexpected application error appears
Temporarily enable an appropriate ProcessWire debug level while the site is inaccessible only to trusted administrators, reproduce the error, and inspect /site/assets/logs/errors.txt. Also inspect the Apache and PHP logs. Disable verbose debugging as soon as you have the diagnosis; production visitors should not receive stack traces, file paths or database details.
The installer reports that it cannot write files
Check the owner, group and mode of site/assets, its subdirectories and the configuration file. The account running Apache must be able to create the directories and files ProcessWire needs during installation. After the installer succeeds, remove unnecessary write access and keep site/config.php unreadable to unrelated users.
Do these 3 things before closing this tab:
1Scan for outdated or missing drivers - takes under a minute2Clear out junk files and repair common Windows errors3Fix the driver behind crashes, sound loss and screen glitchesnamei -l /var/www/processwire/site/assets
ls -ld /var/www/processwire/site /var/www/processwire/site/assets
ls -l /var/www/processwire/site/config.phpThe database connection fails
Verify that MySQL or MariaDB is running, that the PHP driver is loaded, and that the credentials work independently of ProcessWire:
sudo systemctl status mysql --no-pager
php -m | grep pdo_mysql
mysql -u processwire_app -p -h localhost processwireCheck for a spelling mismatch between the installer and the SQL account, and make sure the account host (localhost in the example) matches the host used to connect.
Images fail to upload or resize
Confirm that GD or ImageMagick is loaded in the PHP environment Apache uses, not only in a separate command-line PHP installation. Verify write access to site/assets, then restart Apache after installing or changing a PHP extension.
Post-install verification checklist
- The domain resolves to the VPS and Apache serves the intended virtual host.
- The homepage and several nested ProcessWire page URLs load without 404 responses.
- The administrator can log in and create or edit a test page.
- An image upload and thumbnail operation succeed.
site/config.phpis not readable by unrelated users.install.phpandsite/install/are gone.- Apache rewrite support is enabled and the site remains healthy after a service restart.
- HTTPS, backups, firewall rules, updates and monitoring are in place before public launch.
Which installation route should you use?
For one Ubuntu VPS with no existing deployment automation, use the current master ZIP and record its version. Choose Git when deployments are reviewed and promoted from a repository. Choose Composer when the ProcessWire project already has a Composer-based dependency and release workflow. Whichever route you choose, the operational requirements are the same: Apache must honor .htaccess, PHP must expose PDO and image support, the database account must be dedicated, and the installer files and configuration must be secured after setup.
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.
