Configuring Ubuntu/Xubuntu and Apache 2 for local development environments

Most Web server howtos out there are concerned with production environments, where you need a high level of performance and security. As a developer who runs Apache 2 on localhost, you have other requirements, such as quick configuration and flexibility. It’s inconvenient to edit (usually copy & paste) your virtual hosts configuration and add entries to /etc/hosts whenever you are working on new projects (e.g. on GitHub) – especially, if you just want to test something.

Here’s a complete guide for how to set up Apache 2 on Ubuntu/Xubuntu 12.10. Other distributions should not be much different, if they provide the same packages. You should be able to just copy & paste most of this into a terminal window (make sure to replace {username} with your actual username) :

1) Install the Apache Web server software (if not done yet):

sudo apt-get install apache2.2-bin apache2.2-common apache2-mpm-prefork apache2-utils

2) Install additional packages, such as PHP 5 (if needed):

sudo apt-get install libapache2-mod-php5 php5-cli php5-common php5-dev php5-suhosin

3) Install dnsmasq (a DNS forwarder), so that you can use wildcard subdomains on localhost:

sudo apt-get install dnsmasq

Configure dnsmasq to resolve *.localhost to in /etc/dnsmasq.d/localhost.conf:


Make sure to execute the editor with sudo, so that you have write permissions (applies to all steps, in which you have to edit files in /etc). Example for nano:

sudo nano /etc/dnsmasq.d/localhost.conf

Hint: Control-X closes the editor and Control-O saves the current file.

4) Configure the DHCP client to use the DNS forwarder in /etc/dhcp3/dhclient.conf:

prepend domain-name-servers;

5) Configure Apache in /etc/apache2/sites-available/localhost:

<VirtualHost *:80>
 <Directory /home/{username}/coding>
  Options Indexes FollowSymLinks MultiViews
  AllowOverride All 
  Order allow,deny
  allow from all
 VirtualDocumentRoot /home/{username}/coding/hosts/%0
 ServerName localhost
 ServerAlias *.localhost
 ErrorLog /home/{username}/coding/logs/error.log
 CustomLog /home/{username}/coding/logs/access.log combined

Don’t forget to create the directories:

mkdir ~/coding
mkdir ~/coding/logs
mkdir ~/coding/hosts

6) Although not strictly required, I found it very convenient to execute Apache with the permissions of my own user (I don’t want files that belong to “www-run” in my home directory). You can configure this in /etc/apache2/envvars:

export APACHE_RUN_USER={username}
export APACHE_RUN_GROUP={username}

Warning: This means Apache can access all your files. Don’t do this, if you are not sure about the implications.

7) Enable/disable Apache modules/sites and restart all services:

sudo service dnsmasq restart
sudo dhclient
sudo a2enmod alias vhost_alias rewrite
sudo a2dissite default
sudo a2ensite localhost
sudo service apache2 restart

8) I suggest creating a directory named ~/coding/github for your GitHub projects and something similar for other sites/repositories you can group. You can then easily link your subdirectories to hostnames like this, without touching any config files:

cd ~/coding/hosts
ln -s ../github/test/htdocs test.localhost

~/coding/github/test/htdocs can be accessed with any local Web browser at http://test.localhost/

Hint: Apache was configured to allow the use of .htaccess files for project specific settings. You normally find an example .htaccess file in the project documentation. In step 7, we already enabled RewriteEngine because it is commonly used in .htaccess files.

That’s it :)