Apache2: Activating User public_html Directories & Virtual Directories- Hosts- Domains under Ubuntu Linux for a Private LAN
Summary: Let the hacker beware
These pages describes how I activated the public_html user directories to be served up by the Apache web server and set up virtual directories, meaning fake domains. The audience is developers and home users who want to work on their websites at their desktop computers. I describe what has worked for me and some problems you might encounter using Ubuntu Linux 7.10 (Gutsy Gibbons) desktop software. I have no idea if this is applicable to the GUI-less server software. These are experiences I had using computers in my home. They may or may not work for you. I also don't know the distinctions between virtual hosts, virtual directories, and virtual domains.
Step 1: Installing Apache2 and php5
In a terminal (Applications...Accessories...Terminal), type everything after "$"
me@myhost$ sudo apt-get install apache2 php5
and press enter. Yeah, you need to be connected to the internet. You will be told you're getting some extra software packages with that order. Just say, "Yes, super-size me". The software php5 is not necessary, but at some point it will probably be useful to you if you are developing your own website. You can also use System...Admin...Synaptic Package Manager to install the software.
Test Step 1: When you install apache2 in Ubuntu linux, it is set to start automatically on each boot. You should be able to open a web browser and type in "http://localhost" and see the default apache directory. Click on the directory for the "It Works!" message. If you can't do this, don't proceed. One thing to check is that you have the IP 127.0.0.1 associated with "localhost" in the /etc/hosts file. You can also check this through the GUI System...Admin...Network...Hosts Tab.
Error - Gotcha if Any Reinstalls Done
Subtitled "Don't do what I have done". If you have a problem and decide to reinstall apache... just using "mark for reinstallation" or "reinstall" on the command line did NOT get me a fresh /etc/apache2 setup. I'm not sure which package all this stuff is in, but if you select all the titles with "apache2" in them and "completely remove", or "force remove", or "--purge", then you will be able to start anew again. Research "apt-get" for the right commands. Make sure you check the timestamp on the files in the /etc/apache2 directory when you THINK you have a new installation!
Step 2: Activating the User's public_html Directory with userdir
Background: Firstly, create a directory (folder) called "public_html" in your home directory, with your file browser, or:
me@myhost$ mkdir public_html
There are a couple of reasons to do this. When you have a web server shared by many people, like a shared-hosting ISP, it is necessary to give each user separate access to the "live" files. I have found that on a simple development machine, it is also easier to have your work all within your own home directory and not have to worry about permission and folders owned by the root user. What it gets you is the ability to access your websites in your home directory by a URL in the form http://localhost/~myhome. We can improve upon this with virtual directories, but first things first.
There are only two commands you need to enter to activate the User Directory feature, and then one command to reload the configuration files. The last command includes an absolute path, so it doesn't matter where you execute it from. The first two "ln" commands assume you are in the directory /etc/apache2/mods-enabled. What you need to do is create two symbolic links (soft links, symlinks) in the stated directory pointing to the corresponding module in /etc/apache2/mods-available (which is where they really live). So, if "$" is your prompt,
me@myhost$ cd /etc/apache2/mods-enabled
me@myhost$ sudo ln -s ../mods-available/userdir.conf userdir.conf
me@myhost$ sudo ln -s ../mods-available/userdir.load userdir.load
me@myhost$ sudo /etc/init.d/apache2 restart
On your home system, restarting apache will give you a warning "apache2: Could not reliably determine the server's fully qualified domain name, using 127.0.1.1 for ServerName" simply because you are at home and don't have a fully qualified domain name. No problemo.
Test Step 2: Open up a browser and type http://localhost/~myhome, where "myhome" is your username. For Debian and Ubuntu, your home directory is located within the "/home" directory. Apache should show the folders and files you have in your directory, or even display a web page if you have an "index.html" file in there. If you get sent to the internet or the default apache2 directory, something is wrong and you shouldn't go to the next step.
Step 3: Virtual Directories + Domains for PRIVATE LAN DEVELOPMENT SERVER
Background: There is a HUGE benefit to using virtual directories for the do-it-yourself website developer. You can create all of your development sites exactly the same as for your live web server. For example, if you have a site on a shared hosting environment that you do not have full control over, then the path "/" is the "top of the world" to your instance of the Apache sever. You cannot duplicate these paths using the "~user_name" address. Enter virtual directories, or fake little domains, for your desktop environment.
Part A - Networking: Okay, this is hardly networking so don't sweat it. There are no wires to get tangled, as everything happens within your own machine. The end result is that we need to modify the /etc/hosts file, which can be done through the administrative GUI, System...Administration...Network. Keep in mind there is always more than one way to achieve things. I am describing a method that uses a fixed IP for my server. You CAN do this even if your Linksys or other router is set to DHCP. It makes it much easier when you want to have other machines in your house access your server.
Note:Steps 1-4 below now have an expanded explanation on their own Linux Fixed IP Address page.
- Start the System...Admin...Network GUI and enter your password.
- Click on our Network connection in the "Connections" tab and then click the "Properties" button.
- Uncheck "roaming mode" and at "Configuration" choose "Static IP".
- You need to know what your network IPs are, but here are some typical examples. IP=192.168.1.xx (anything but 1), Subnet Mask=255.255.255.0, Gateway=192.168.1.1 (that is your Linksys or other router from your ISP).
- Click on the "Hosts" tab and click the "Add" button.
- Enter the 192.168.1.xx number in the IP box and ALL the virtual domains you want to use in the Aliases box (they should all point to the same server), separated by spaces. For example, I use "com" and "newcom" for my current site and a new version of my site.
- Click "Okay" and "Close". We are done with networking. Now we tell Apache what to do with the data.
Part B - Create Apache Virtual Directories: We will now be concerned with the directories in /etc/apache2 called "sites-available" and "sites-enabled" (you see a pattern here?). This is extremely easy to do if you know the trick that you really don't need most of the stuff in the "default" virtual directory file if you are just working in your home. The simplest thing is to just show you what I use. This will be a physical file in the "sites-available" section. Later we make links.
WARNING: Like I said at the top, these notes are for usage on a PRIVATE LAN, i.e., NOT the internet. Here you can read where someone sent me a apache virtual directories warning. If you try to use these notes on the internet, then you are an idiot and I cannot help you.
<VirtualHost *>
ServerName com
DocumentRoot /home/utree/public_html/com
</VirtualHost>
Dude! You cannot believe it is that easy if you ever looked at the "default" file in that directory. The pre-formatted code above is the content of a plain text file I can call anything I want, but will name it "com" so as to keep my sanity. "ServerName" is the name of the virtual directory, or "fake domain", that will allow you to enter "http://com" in your browser to see the site. The "DocumentRoot" is the absolute path to another file called "com" (not the one we just made, but a directory file). My username is "utree" because er, never mind why. Within utree's home directory, I have created a file called "public_html" where all my websites are. Each website has a directory within public_html, like "com", to keep all of the files for that website. I happen to keep the names consistent throughout, but that is not necessary. So the next file we create would be /etc/apache2/sites-available/newcom (you can use $sudo gedit to make it simple) and would look like this:
<VirtualHost *>
ServerName newcom
DocumentRoot /home/utree/public_html/newcom
</VirtualHost>
Follow this pattern for all of your virtual directories (fake domains).
Part C - Make Apache Virtual Directories Available: Luckily, there is really nothing new here. You follow an exactly analogous procedure to activate virtual directories that you did to activate User Directory modules. We create symbolic links within the directory /etc/apache2/sites-enabled to the sites in the "sites-available" directory.
me@myhost$ cd /etc/apache2/sites-enabled
me@myhost$ sudo ln -s ../sites-available/com com
me@myhost$ sudo ln -s ../sites-available/newcom newcom
me@myhost$ sudo /etc/init.d/apache2 restart
Test Step 3: Okay, by now I'm assuming you actually have some kind of a website you are working with and that the contents of it are within a directory, like "newcom", in your public_html folder. Open up a browser and try the address "http://newcom/" (I don't think you need the trailing slash). Apache should serve up the index.html file in that directory, or even the index.php file if you have PHP installed correctly. Note: If you don't see the file php5.conf in /etc/apache2/mods-enabled, then you don't have php installed correctly. Ready for extra credit?
Step 4: Configure a Client Machine for Virtual Directories
Case A - Linux: No problemo. We have done this already in Step 3, Part A, #5-7. I'm not going to paste the whole thing here. The objective is to modify /etc/hosts to relate the server's IP (you're glad it's fixed now, eh?) to ALL of the virtual domains you want to be able to use. The link goes to the GUI explanation, but it is as simple as adding a line to /etc/hosts in the form of "192.168.1.xx com newcom", where "xx" is the fixed IP of your web server (not your client) and "com newcom" are the virtual domains separated by spaces.
Case B - Windows: Not really that much harder, I just can't help you out as much. Currently, I have one Windows XP computer, but I'm not sure why I still have it, as I don't use it for anything any more. There are two files "hosts" and "lmhosts" kept in C:\windows\system32\drivers\etc. You set them up just like /etc/hosts under linux: one line for each IP and aliases, separated by spaces (e.g., 192.168.1.xx com newcom). The test I did seems to indicate you only need to set up the "hosts" files for web browser usage. I don't think it could hurt to keep them both up to date. Here are some notes on host files. I think I remember one time where only the Administrator could use the file, but this seems too silly to be true. It's worth a try if you have problems...
Step 5: Configuring PHP
Remarks: If you use the Debian or Ubuntu package managers, you are ready to go "out of the box" for just about everything. I'll list a couple of tweaks that might be applicable to a home server development environment. None of this is required if you only intend to use static HTML pages.
Setting the include_path: This is probably the most common thing you would want to do. I think the includes path is commented out of the original php.ini file. For a time I used an absolute path for this variable and it made the multiple websites NOT be completely the same as on-line. The simple trick is to use only relative paths and keep all of your includes in a directory of the same name on all of your sites. It is NOT the same physical directory, just the same name. "inc" seems to be a common standard. Here are the steps:
- Open a text editor as root ($sudo gedit) and open the file /etc/php5/apache2/php.ini.
- Go to the section "Paths and Directories", around line 476 in 2007-12.
- Copy the following:
include_path=".:/inc:./inc:../inc:../../inc:../../../inc:../../../../inc"
- Optional: Or, if you are using shared resources, like PEAR:
include_path=".:/inc:./inc:../inc:../../inc:../../../inc:../../../../inc:/usr/share/php"
- Create a blank line under the line that says "Unix", and paste in your include_path value. There should be only one without a semi-colon (comment) symbol.
- Here is the restart apache command again:
$sudo /etc/init.d/apache2 restart
- If your site is "deeper" than I have the path set up for, then first rethink your site. Second, you can just extend the line with another colon and a ../../../../../inc entry.
- Note for shared Web Hosting: If you use a shared server, I haven't found a work around. I put a php.ini file in each directory containing that one line from #3:
Enable PHP for .html Files: You might have migrated an existing .html page to PHP and want it processed by the PHP interpreter. I use a generic extension of ".file" for everything that is not an index page so that it is totally generic and I can change technologies in the future without changing the file name. To set it up:
- Open a text editor as root ($sudo gedit) and open the file /etc/apache2/mods-available/php5.conf
- Add the extensions you want to the line that starts off "AddType application/x-httpd-php" (e.g., .php .html .htm .file) separated by spaces.
AddType application/x-httpd-php .php .html .htm .file
- ORYou may need to use this wording now. I don't know why it may have changed.
AddHandler application/x-httpd-php .php .html .htm .file
- Here is the restart apache command again:
$sudo /etc/init.d/apache2 restart
Seeing PHP As Text & The "phtml" Error: Okay, let me put on my Captain Obvious hat and say, "You don't have PHP configured correctly". I can think of 2 or 3 things to do for apache2 and php5:
- Make sure you that the file /etc/apache2/mods-available/php5.conf exists. If not, you don't have a chance.
- See the note on the first page about reinstalling apache and php.
- If you make changes, it can't hurt to restart the server (you know, $sudo /etc/init.d/apache2 restart). You can also go to System...Administration... Services and (un)check the Web Server box.
Epilogue: Good Luck, I hope some of this is useful, but remember it may not work for you. Always make backups of files you are changing. I collected all this information after making lots of mistakes over a few years. Thanks to the Free Software community for posting all the information in various places. I can't say what information came from where. Recycle, rinse, repeat.