sploiselle/tech-writing-hw.md

## tech-writing-hw.md

      
    Raw
  

              tech-writing-hw.md
            
          
    How to Install MediaWiki with Lighttpd on Ubuntu 14.04

Introduction

MediaWiki is a popular open source wiki platform that can be used for public or internal collaborative content publishing.  MediaWiki is used for many of the most popular wikis on the internet including Wikipedia, the site that the project was originally designed to serve.
In this guide, we will be setting up the latest version of MediaWiki on an Ubuntu 14.04 server.  We will use the lighttpd web server to make the actual content available, php-fpm to handle dynamic processing, and mysql to store our wiki's data.
This guide walks you through installing your site in a subdirectory called /w/, which is how MediaWiki recommends installing it. We do not cover installing the application directly in your document root, which MediaWiki does not recommend.
Besides installing MediaWiki, we also show you how to:

Secure your website with an SSL certificate
Use "pretty"/search-engine-friendly URLs

Prerequisites

To complete this guide, you should have access to a clean Ubuntu 14.04 server instance.  On this system, you should have a non-root user configured with sudo privileges for administrative tasks.  You can learn how to set this up by following our Ubuntu 14.04 initial server setup guide.
When you are ready to continue, log into your server with your sudo user and get started below.
Step 1 – Install the Server Components

Because you're using Lighttpd, MySQL and PHP, you're building a LLMP stack. If you take a snapshot of your server at the end of this section, you could easily build new LLMP servers in the future.
Install Lighttpd

Update your installed Ubuntu packages:
sudo apt-get update
Install Lighttpd:
sudo apt-get install lighttpd
Lighttpd runs as a service, so you'll need to start it:
sudo service lighttpd start
Now that Lighttpd's running, go to http://<^>your-server's-IP-address<^>/. You'll see the default Lighttpd welcome page:

Install PHP 5

Install PHP 5 with the FPM and MySQL packages:
sudo apt-get install php5 php5-fpm php5-mysql
<$>[note]
Note: Ubuntu 16 does not support PHP 5, so these instructions will not work.
<$>
Install MySQL

Install MySQL:
sudo apt-get install mysql-server
Initialize the MySQL data directory, which will walk you through a number of steps to configure MySQL on your server:
sudo mysql_install_db
Complete the prompts in the terminal, including creating a password for your root MySQL user.
<$>[note]
Note: Make sure to note the password you choose because you will need it to log into MySQL in the next section.
<$>
Set MySQL to automatically start whenever you boot your server (otherwise reboots will bring down your site):
sudo update-rc.d mysql defaults
(Optional but recommended) Secure your MySQL installation:
sudo /usr/bin/mysql_secure_installation


Prompt
Recommendation


Enter current password
Enter the password you just created


Do you want to change the root password?
n—It was just set


Remove anonymous users?
y—Anonymous users post potential security risks


Disallow root login remotely?
y—You're going to create another user which is more secure to use with remote logins


Remove test database and access to it?
y—You're not using the test database, so remove it


Reload privilege tables now?
y—No harm in reloading privilege tables now


Step 2 – Configure MySQL and Create Credentials for MediaWiki

Log in to MySQL:
mysql -u root -p
Enter the password you created.
Create the database:
CREATE DATABASE my_wiki;

Create a database user:
GRANT ALL ON my_wiki.* TO '<^>sammy<^>'@'localhost' IDENTIFIED BY '<^>password<^>';

<$>[note]
Note: You'll need both this username and password to complete the MediaWiki installation, so make sure to note it.
<$>
Flush privileges (which you always need to do after creating a user):
FLUSH PRIVILEGES;

Exit MySQL:
exit

Step 3 – Configure PHP-FPM and Lighttpd

By default, Lighttpd supports SpawnFCGI. However, we're going to show you how to configure it to work with PHP-FPM instead, which can improve your MediaWiki site's performance.
Open the FPM php.ini file:
sudo nano /etc/php5/fpm/php.ini
Uncomment cgi.fix_pathinfo=1 by removing the ; in front of it so it looks like this:
[label /etc/php5/fpm/php.ini]
...
; http://php.net/cgi.fix-pathinfo
cgi.fix_pathinfo=1
...

Save your changes and exit (ctrl + X, Y, enter).
Move to /etc/lighttpd/conf-available/:
cd /etc/lighttpd/conf-available/
<$>[note]
Note: /etc/lighttpd/conf-available/ stores all of the configurations you want to potentially use. When you want to use them, create a symlink (ln -s) to the configuration in the /etc/lighttpd/conf-enabled/ directory.
<$>
Create a backup of 15-fastcgi-php.conf that keeps the spawn-fcgi configuration (which you're going to overwrite to use FPM instead):
sudo cp 15-fastcgi-php.conf 15-fastcgi-php-spawnfcgi.conf
Open 15-fastcgi-php.conf:
sudo nano 15-fastcgi-php.conf
To configure Lighttpd to use FPM, change this:
[label 15-fastcgi-php.conf]
fastcgi.server += ( ".php" =>
        ((
                "bin-path" => "/usr/bin/php-cgi",
                "socket" => "/var/run/lighttpd/php.socket",
                "max-procs" => 1,
                "bin-environment" => (
                        "PHP_FCGI_CHILDREN" => "4",
                        "PHP_FCGI_MAX_REQUESTS" => "10000"
                ),
                "bin-copy-environment" => (
                        "PATH", "SHELL", "USER"
                ),
                "broken-scriptfilename" => "enable"
        ))
)

to this:
[label 15-fastcgi-php.conf]
#PHP-FPM configuration
fastcgi.server += ( ".php" =>
        ((
                "socket" => "/var/run/php5-fpm.sock",
                "broken-scriptfilename" => "enable"
        ))
)

The above script runs PHP-FPM as a FastCGI server on php5-fpm.sock, instead of using SpawnFCGI on the default lighttpd/php.socket.
Save your changes and exit (ctrl + X, Y, enter).
Now, create symlinks in /etc/lighttpd/conf-enabled/ to point to the configuration files you want to use in /etc/lighttpd/conf-available/ :
sudo ln -s /etc/lighttpd/conf-available/10-fastcgi.conf /etc/lighttpd/conf-enabled/
sudo ln -s /etc/lighttpd/conf-available/15-fastcgi-php.conf /etc/lighttpd/conf-enabled/
Reload Lighttpd to detect your updated configuration:
sudo service lighttpd force-reload
Test PHP

At this point, your server successfully serves PHP pages, which you can test using phpinfo().
Create an info.php file in your document root:
sudo nano /var/www/info.php
Paste in the following strings:
[label info.php]
<?php
phpinfo();
?>

Save your changes and exit (ctrl + X, Y, enter).
Now go to http://<^>your-server's-IP-address<^>/info.php and you should see a standard PHP info page:

Step 4 – Install MediaWiki

With your web server configured, you're ready to install MediaWiki. apt-get's version of MediaWiki is outdated, so this guide shows you how to install the most recent version outside of a package manager.
Download and Move MediaWiki

Go to https://www.mediawiki.org/wiki/Download.
In the Latest Release section, copy the destination of the link Download MediaWiki Some Version Number.
Using the link you copied, download the MediaWiki .gz file to your server by using wget and pasting in the destination URL of the link you copied:
wget <^>paste in the URL copied from the last step<^>
Unzip the file:
tar -xzvf mediawiki-*.gz
Create the directory you want to use (/w/) and move MediaWiki's files into it:
sudo mkdir /var/www/w/
sudo mv mediawiki-*/* /var/www/w/
<$>[note]
Note: We recommend using /w/ as the subdirectory of /var/www/, but you can use any name you'd like. If you use the pretty URL instructions at the end of this article, it's also easy to change the name of /w/ to something more descriptive like /wiki/. However, MediaWiki does not recommend using your document root (/var/www/) directly.
<$>
Install Additional Packages

WikiMedia supports a number of additional packages that enhance its functionality.

git enables Git version control for pages (recommended)
php5-gd enables thumbnails for images your users upload (recommended)
php5-intl enables non-Roman alphabet support
php5-xcache enables a cache that improves your site's performance (recommended)
texlive enables mathematical formula display

The command below includes all additional packages, but you only need to include those that will improve your site:
sudo apt-get install git php5-gd php5-intl php5-xcache texlive
Restart the php5-fpm and lighttpd services to ensure WikiMedia can detect the additional packages:
sudo service php5-fpm restart
sudo service lighttpd force-reload
Set up MediaWiki

Go to http://<^>example.com<^>/w and then click set up the wiki.

Select your Language settings and then click Continue.
Click Continue to agree to the MediaWiki terms of service.
Enter your database information:


Field
Action


Database type
Select MySQL


Database host
Leave the value localhost


Database name
Leave the value my_wiki


Database table prefix
Leave this field blank


Database username
Enter the username you created to replace <^>sammy<^>


Database password
Enter the database password you chose


Click Continue.
On the Database Settings page, select InnoDB for the storage engine and Binary for the database character set.
Click Continue.
Enter the information you want to use for your administrator account:


Field
Action


Your username
Enter the username you want to use to log in to MediaWiki


Password & Password again
Enter the password you want to use


Email address
Enter your email address


<$>[note]
Note: If you selected to install php5-xcache, make sure to select Ask Me More Questions, otherwise you will not be presented the option to use the cache!
<$>
Click Continue.
If you installed php5-xcache, in the Advanced Configuration section, select PHP Object Caching.
Click Continue.
On the final page, your browser will automatically download a file called LocalSettings.php. If the download doesn't happen immediately, click Download LocalSettings.php.

Add LocalSettings.php

MediaWiki requires the settings stored in LocalSettings.php to make your site work, which includes tasks like connecting to the MySQL database you created.
On your local machine, open the LocalSettings.php file and copy its contents.
Create a LocalSettings.php file for your WikiMedia installation:
sudo nano /var/www/w/LocalSettings.php
Paste in the contents of your local LocalSettings.php file, which should look somewhat like this:
[label /var/www/w/LocalSettings.php]
<?php
# This file was automatically generated by the MediaWiki 1.26.3
# installer. If you make manual changes, please keep track in case you
# need to recreate them later.
...

Save your changes and exit (ctrl + X, Y, enter).
Check Your Site

You can now go to your new MediaWiki page at http://<^>your-server's-IP-address<^>/w
Your new Wiki displays:

Optional Step 5 – Secure Your Site

If you have an SSL certificate, you can use it to secure your MediaWiki site—protecting incoming and outgoing traffic via HTTPS. To do this you must have a:

Domain name that you can configure to point to your server
SSL certificate through a certificate authority (CA)

<$>[warning]
After installing an SSL certificate and configuring your automatic HTTPS redirects, visiting your site with your server's IP address will generate security errors.
<$>
Generate a CSR to Request or Re-key Your SSL Certificate

Because this guide assumes you're using a new server, you have to generate a certificate signing request (CSR) for this server and then use it to request a new certificate or re-key an existing one.
Move to the /etc/lighttpd/ directory, where you're going to store your SSL's files:
cd /etc/lighttpd/
Generate a CSR and private key for your server:
sudo openssl req -new -newkey rsa:2048 -nodes -keyout server.key -out server.csr
Using this new CSR, you will need to either re-key an existing certificate or request a new one from your SSL provider. You can access your CSR through nano:
nano server.csr
Install Your SSL on Lighttpd

After you have you've completed the request or re-key process with your SSL provider, download the certificate files they provide. This should be a bundle of two .crt files:

One file for your site
One file that chains your certificate back to the company (certificate authority or CA) who issued it—this file is called an intermediate certificate

Install Your Site's Certificate File

Open your site's .crt locally and copy its contents. The name of this file should be something that is either apparently random or contains your domain name, as well as end in .crt. Examples are <^>f8g9ii4fa.<^>crt and <^>example-com<^>.crt.
Create a new file, server.crt, on your server:
sudo nano /etc/lighttpd/server.crt
Paste in the contents of your site's local .crt file. It should look somewhat like this:
[label /etc/lighttpd/server.crt]
----BEGIN CERTIFICATE-----
avx4A6lNf4DD+qta/KFApMoZFv6yyO9ecw3ud72a9nmYvLEHZ6IVDd2gWMZEewo+
...
sNKR1EwRcbNhyz2h/t2oatTjMIGNBgNVHSMEgYUwgYKAFNLEsNKR1EwRcbNhyz2h
-----END CERTIFICATE-----

Save your changes and exit (ctrl + X, Y, enter).
Install Your CA's Intermediate Certificate File

Open your CA's .crt locally and copy its contents. The name of this file should contain some reference to the company that issued the certificate, as well as end in .crt. An example is <^>aGreatCA<^>.crt.
Create a new file, ca.crt, on your server:
sudo nano /etc/lighttpd/ca.crt
Paste in the contents of the CA's intermediate certificate .crt file. It should look somewhat like this:
[label /etc/lighttpd/ca.crt]
----BEGIN CERTIFICATE-----
ZmljYXRlIEF1dGhvcml0eSAtIEcyMB4XDTExMDUwMzA3MDAwMFoXDTMxMDUwMzA3
...
MDAwMFowgbQxCzAJBgNVBAYTAlVTMRAwDgYDVQQIEwdBcml6b25hMRMwEQYDVQQH
-----END CERTIFICATE-----
-----BEGIN CERTIFICATE-----
MIIEfTCCA2WgAwIBAgIDG+cVMA0GCSqGSIb3DQEBCwUAMGMxCzAJBgNVBAYTAlVT
...
qm5vjLyb4lddJIGvl5echK1srDdMZvNhkREg5L4wn3qkKQmw4TRfZHcYQFHfjDCm
-----END CERTIFICATE-----
-----BEGIN CERTIFICATE-----
MIIEADCCAuigAwIBAgIBADANBgkqhkiG9w0BAQUFADBjMQswCQYDVQQGEwJVUzEh
...
b2RhZGR5LmNvbS9nZHJvb3QtZzIuY3JsMEYGA1UdIAQ/MD0wOwYEVR0gADAzMDEG
-----END CERTIFICATE-----

Save your changes and exit (ctrl + X, Y, enter).
Create a .pem File

Make sure you're in the /etc/lighttpd/ directory where your SSL certificate files are stored:
cd /etc/lighttpd/
Create the .pem file, which is the file Lighttpd will use to secure your site (because of the directory you're in, this requires going in and out of root):
sudo su
sudo cat server.key server.crt > server.pem
exit

Open lighttpd.conf to add your SSL certificate's information to it:
sudo nano lighttpd.conf
At the bottom of the file, add the following:
[label /etc/lighttpd/lighttpd.conf]

#Configure SSL

var.confdir = "/etc/lighttpd"
$SERVER["socket"] == "<^>your-server's-IP-address<^>:443" {
	ssl.engine = "enable"
	ssl.pemfile = var.confdir + "/server.pem"
	ssl.ca-file = var.confdir + "/ca.crt"
	server.name = "<^>example.com<^>"
	server.document-root = "/var/www/"
}

#Automatically redirect to HTTPS

$HTTP["scheme"] == "http" {
    $HTTP["host"] =~ "<^>example.com<^>" {
        url.redirect = (".*" => "https://%0$0")
    }
}

Save your changes and exit (ctrl + X, Y, enter).
Configure MediaWiki for HTTPS

Now that you've configured Lighttpd to work with your SSL certificate, you should make sure MediaWiki also redirects visitors to HTTP.
Open LocalSettings.php:
sudo nano /var/www/w/LocalSettings.php
Change the value of $wgServer to https://<^>example.com<^>:
[label /var/www/w/LocalSettings.php]
## The protocol and server name to use in fully-qualified URLs
$wgServer = "https://<^>example.com<^>";

Save your changes and exit (ctrl + X, Y, enter).
Restart Lighttpd:
sudo service lighttpd force-reload
When you go to your wiki—http://<^>example.com<^>/w—it will automatically load as a site secured with HTTPS. If you look in your address, you'll see some symbol indicating that the connection's secured.
Optional Step 6 – Use Pretty URLs

By default, MediaWiki's URLs are long and neither intuitive to users nor friendly to search engines. Fortunately, with the way you've configured MediaWiki, you can easily improve them using mod_rewrite, which lets you rewrite URLs using any structure you choose.
Here are examples of the Default URL Structure and the Pretty URL Structure this guide shows you how to use instead:
Default URL Structure

http://example.com/<^>w<^>/index.php?title=<^>Page_title<^>
Pretty URL Structure

http://example.com/<^>wiki<^>/<^>Page_title<^>
Configure Pretty URLs

Edit your lighttpd.conf file to handle URL rewrites:
sudo nano /etc/lighttpd/lighttpd.conf
Uncomment "mod_rewrite" by removing the # in front of it so it looks like this:
[label /etc/lighttpd/lighttpd.conf]
...
        "mod_redirect",
        "mod_rewrite",
)
...

At the bottom of the file, insert the following:
[label /etc/lighttpd/lighttpd.conf]
url.rewrite-if-not-file = ( 
    "^/wiki/(mw-)?config/?" => "$0",
    "^/wiki/([^?]*)(?:\?(.*))?" => "/w/index.php?title=$1&$2",
    "^/wiki/([^?]*)" => "/w/index.php?title=$1",
    "^/wiki$" => "/w/index.php", # to avoid 404 when the user types /wiki instead of /wiki/
)

Save your changes and exit (ctrl + X, Y, enter).
You now need to configure WikiMedia itself to handle pretty/rewritten URLs, which is handled in LocalSettings.php:
sudo nano /var/www/w/LocalSettings.php
Beneath $wgScriptPath = "/w";, add the following lines:
[label /var/www/w/LocalSettings.php]
$wgArticlePath = "/wiki/$1";
$wgUsePathInfo = true;

Save your changes and exit (ctrl + X, Y, enter).
Restart Lighttpd:
sudo service lighttpd force-reload
Now, go to http://<^>example.com<^>/w. It will automatically redirect you to to something much nicer looking: http://<^>example.com<^>/wiki/Main_Page.
You can also test how other pages work by going to http://<^>example.com<^>/wiki/New or http://<^>example.com<^>/wiki/New_Page.
Conclusion

In this article, you accomplished a lot. You:

Built a LLMP server
Configured your server to use PHP-FPM
Created a MySQL database
Installed MediaWiki
Created a CSR, as well as installed an SSL certificate
Set up "pretty URLs" on MediaWiki

For a next step, we recommend making users log in to create pages on your MediaWiki site.
Prompt	Recommendation
Enter current password	Enter the password you just created
Do you want to change the root password?	n—It was just set
Remove anonymous users?	y—Anonymous users post potential security risks
Disallow root login remotely?	y—You're going to create another user which is more secure to use with remote logins
Remove test database and access to it?	y—You're not using the test database, so remove it
Reload privilege tables now?	y—No harm in reloading privilege tables now
Field	Action
Database type	Select MySQL
Database host	Leave the value localhost
Database name	Leave the value my_wiki
Database table prefix	Leave this field blank
Database username	Enter the username you created to replace <^>sammy<^>
Database password	Enter the database password you chose
Field	Action
Your username	Enter the username you want to use to log in to MediaWiki
Password & Password again	Enter the password you want to use
Email address	Enter your email address