How to Install and Configure MediaWiki on a VPS

This guide walks you through installing and configuring MediaWiki on a Virtual Private Server (VPS). You’ll end up with a fully functional wiki site, complete with a database, web server, and PHP, ready for your content. It assumes you have basic command-line familiarity and root access to your VPS.

What You’ll Need

• A VPS running a supported Linux distribution (Ubuntu 22.04/24.04 or Debian 12 recommended).
• Root or sudo access to the server.
• A domain name pointed to your server’s IP address (optional but recommended for production).
• SSH client (like PuTTY on Windows, or the terminal on macOS/Linux).
• At least 1 GB of RAM and 10 GB of disk space.

Step-by-Step

1. Update your system
   SSH into your VPS and run:
   sudo apt update && sudo apt upgrade -y
2. Install required packages
   Install Apache, PHP, MariaDB, and supporting libraries:
   sudo apt install apache2 mariadb-server php php-mysql libapache2-mod-php php-xml php-mbstring php-intl php-curl php-zip php-gd -y
3. Secure MariaDB
   Run the secure installation script:
   sudo mysql_secure_installation
   Set a root password, remove anonymous users, disable remote root login, and remove test databases.
4. Create a database and user for MediaWiki
   Log into MariaDB:
   sudo mysql -u root -p
   Then run:
   CREATE DATABASE mediawiki;
CREATE USER 'wikiuser'@'localhost' IDENTIFIED BY 'strongpassword';
GRANT ALL PRIVILEGES ON mediawiki.* TO 'wikiuser'@'localhost';
FLUSH PRIVILEGES;
EXIT;
5. Download MediaWiki
   Get the latest tarball from the official site. As of writing, version 1.42 is current. Use:
   cd /tmp
wget https://releases.wikimedia.org/mediawiki/1.42/mediawiki-1.42.1.tar.gz
   Verify the SHA-256 checksum against the official release page, then extract:
   tar -xvzf mediawiki-1.42.1.tar.gz
6. Move files to web directory
   sudo mkdir -p /var/www/html/mediawiki
sudo mv mediawiki-1.42.1/* /var/www/html/mediawiki/
   Set permissions:
   sudo chown -R www-data:www-data /var/www/html/mediawiki
7. Configure Apache
   Create a virtual host file:
   sudo nano /etc/apache2/sites-available/mediawiki.conf
   Add:

   <VirtualHost *:80>
       ServerAdmin admin@example.com
       ServerName yourdomain.com
       DocumentRoot /var/www/html/mediawiki
       <Directory /var/www/html/mediawiki>
           Options FollowSymLinks
           AllowOverride All
           Require all granted
       </Directory>
       ErrorLog ${APACHE_LOG_DIR}/error.log
       CustomLog ${APACHE_LOG_DIR}/access.log combined
   </VirtualHost>

   Enable the site and mod_rewrite:
   sudo a2ensite mediawiki.conf
sudo a2enmod rewrite
sudo systemctl restart apache2

8. Run the web installer
   Open your browser and go to http://yourdomain.com or http://your-server-ip. Follow the on-screen steps. Choose “MariaDB” as the database type. Enter the database name, user, and password you created. For the table prefix, leave it blank or use mw_. Set up the admin account and site name.
9. Move LocalSettings.php
   After the installer finishes, it will download a file named LocalSettings.php. Upload it to /var/www/html/mediawiki/ using SCP or FTP. Alternatively, you can copy the content and create the file via SSH:
   sudo nano /var/www/html/mediawiki/LocalSettings.php
   Paste the content, save, and exit. Then set permissions:
   sudo chown www-data:www-data /var/www/html/mediawiki/LocalSettings.php
10. Enable HTTPS (optional but recommended)
    Install Certbot:
    sudo apt install certbot python3-certbot-apache -y
    Run:
    sudo certbot --apache -d yourdomain.com
    Follow the prompts to obtain and install an SSL certificate.

Common Mistakes

• Wrong PHP extensions: MediaWiki requires specific PHP modules. Missing ones cause errors during installation. Double-check that you installed all the packages listed in Step 2.
• Permissions issues: The web server user (www-data) must own the MediaWiki files. If you forget the chown command, you’ll get permission errors.
• Database connection errors: Ensure the database user has the correct host (‘localhost’) and that you used the right password. Also, make sure MariaDB is running.
• Forgetting to move LocalSettings.php: The installer won’t work until this file is in place. It’s easy to miss the download and skip this step.
• Not enabling mod_rewrite: Without it, pretty URLs won’t work, and you may have broken links.

Tips

• Use a strong database password: Avoid simple passwords; use a password manager to generate one.
• Back up regularly: Copy both the LocalSettings.php file and the database. You can use mysqldump for the database.
• Keep MediaWiki updated: Subscribe to the official release announcements and update promptly to patch security vulnerabilities.
• Set up a cron job for maintenance: MediaWiki has maintenance scripts that should run periodically. For example, php maintenance/runJobs.php can be scheduled every few minutes.
• Use a separate database user: Don’t use the root user for MediaWiki; create a dedicated user with only the necessary privileges.

Troubleshooting

• Blank page after installation: Check PHP errors in /var/log/apache2/error.log. Common causes are missing PHP modules or incorrect file permissions. Re-run sudo apt install php-xml php-mbstring php-intl php-curl php-zip php-gd and ensure LocalSettings.php exists.
• Database connection refused: Verify MariaDB is running with sudo systemctl status mariadb. If it’s not, start it with sudo systemctl start mariadb. Also check that the database and user exist and the password is correct.
• 403 Forbidden error: This usually means Apache can’t access the directory. Check the <Directory> block in your virtual host and ensure the path is correct. Also verify file permissions: sudo chown -R www-data:www-data /var/www/html/mediawiki.
• Installer says “Can’t connect to MySQL”: Ensure the database server is listening on localhost. Try sudo mysql -u wikiuser -p -h localhost to test the connection. If it fails, re-run the GRANT commands.
• Images not uploading: Check the images directory permissions: sudo chown -R www-data:www-data /var/www/html/mediawiki/images and set it to 755. Also check PHP file upload settings in php.ini (upload_max_filesize, post_max_size).

Frequently Asked Questions

Do I need a domain name?

No, you can use your server’s IP address. However, a domain makes it easier for users to remember and is required for HTTPS certificates from Let’s Encrypt.

Can I install MediaWiki on a shared hosting account?

Yes, but this guide is for a VPS. Shared hosting often has restrictions on PHP settings and database access, but the web-based installer works similarly.

How do I update MediaWiki?

Back up your existing installation and database. Then download the new version, replace the files (keeping LocalSettings.php and the images folder), and run php maintenance/update.php from the command line.

What PHP version do I need?

MediaWiki 1.42 requires PHP 7.4.3 or later, but PHP 8.1 or 8.2 is recommended. Check your PHP version with php -v.

Can I use Nginx instead of Apache?

Yes, MediaWiki works with Nginx. The configuration is different, but the installation steps for PHP and the database are the same. You’ll need to configure PHP-FPM and Nginx server blocks.

How do I change the default logo?

Upload your logo to /var/www/html/mediawiki/resources/assets/ and edit LocalSettings.php to add $wgLogos = [ '1x' => 'path/to/logo.png' ];

Related

• RX 6800 XT vs RTX 3080: Which GPU Wins?
• OBS Failed to Connect to Server: Fixed
• Automation Testing: A Beginner’s Tutorial