RSS Feed

Search...

Archive for November 30th, 2011


The Symfony site gives brief information on how to build the Symfony2 documentation, but I felt it lacked some of the finer details for anybody who might be new to reStructuredText documents.  I decided to put up a blog post after trying to find a more detailed explanation and failing – I hope this helps others who have also just started using ReST files.

Install packages

Firstly, we need to install some required software packages.

Open up a terminal and install the python packages:

apt-get install python-setuptools python-dev build-essential

Next install the gargantuan LaTeX. LaTeX is a document preparation system that weighs in at over 1Gb. This is required to build the reStructuredText as PDF.

apt-get install texlive-full

Lastly, we install Sphinx, the python documentation generator

easy_install -U Sphinx

Initialise the Symfony2 Documentation directory

I personally like to keep the generated files under /var/www/symfony2docs as I create a vhost that points to the built HTML to browse whether I’m online or offline.

To mimic this, run:

mkdir /var/www/symfony2docs
cd /var/www/symfony2docs
sphinx-quickstart

The command sphinx-quickstart will run a project setup wizard. You can safely just press Enter to accept the defaults showing between [ ] brackets.

There are, however, four options that will require input. I fill them in as follows:

  • Project Name: Symfony2 Documentation
  • Author Name(s): SensioLabs
  • Project Version: 2
  • Do you want to use the epub builder (y/N) [n]: y

The question regarding the epub builder is set to “n” by default.  Change this option to “y” if you would also like to build the documentation into an epub format.

Install SensioLab’s configuration-block Sphinx extension

To install the extension, run the following:

mkdir /var/www/symfony2docs/_exts
cd /var/www/symfony2docs/_exts
wget https://raw.github.com/fabpot/sphinx-php/master/configurationblock.py

Next, we have to activate the extension by editing the conf.py file.

Search for:

extensions = []

Replace with:

sys.path.append(os.path.abspath('_exts'))
# Activating the configurationblock extension
extensions = ['configurationblock']

Download latest Symfony2 Documentation

We have two ways of retrieving the latest Symfony2 Documentation – either using Git or by downloading the latest tarball.

I usually download the latest documentation into the /tmp directory and then copy it into the Sphinx project from there.  Git creates symfony-docs directory whereas, the tarball creates a directory named symfony-symfony-docs-xxxnnnn (e.g. symfony-symfony-docs-dfe0182).  If using the tarball please verify the name of the folder created when unpacking the archive.

If using Git, run:

cd /tmp
git clone https://github.com/symfony/symfony-docs.git
mv /tmp/symfony-docs/* /var/www/symfony2docs 

If using the tarball, run:

cd /tmp
wget https://github.com/symfony/symfony-docs/tarball/master -O symfony-docs.tar.gz
tar -zxvf symfony-docs.tar.gz
mv /tmp/symfony-symfony-docs-dfe0182/* /var/www/symfony2docs 

Build Symfony2 Documentation PDF

We finally have all the files in the right locations to build the PDF.

cd /var/www/symfony2docs
make latexpdf

The output can be found in the _build directory

Build Symfony2 Documentation HTML

cd /var/www/symfony2docs
make html

Build Symfony2 Documentation EPUB

cd /var/www/symfony2docs
make epub

I enjoy using Windows as my primary OS on my laptop, but nothing beats developing for the web in Linux.  This article will show you how to install a local Web Server using Ubuntu Server 64-bit into VirtualBox to allow you to seamlessly continue coding in NetBeans and testing in the largest set of browsers.

1. Preparation

Before starting, you’ll need to download the following:

- VirtualBox (version 4.1.8 at the time of writing)
- Ubuntu Server 64-bit (11.10 at the time of writing)
- NetBeans IDE (7.0.1)
- PuTTY SSH Client

Begin by installing VirtualBox, NetBeans and PuTTY. Be sure to install the network host-adapters when prompted during the VirtualBox installation.

2. Create a new VirtualMachine

Open VirtualBox and create a New Virtual Machine.

When prompted, select the following:
  • Name and OS Type:  You can call it anything you wish, I tend to name it after the distribution (e.g. UbuntuServer).  Be sure to select Linux and Ubuntu (64-bit) as the Operating System.
  • Base Memory: The default is 512Mb but push this up to as much as your system can allow.  I have 8Gb of RAM so I give the VirtualMachine between 2.5 and 3Gb.
  • Virtual Hard Disk:  Ensure “Start-up Disk” is checked and “Create new hard disk” is selected
  • Virtual Disk File Type:  Leave it as the default VDI unless you have other requirements
  • Storage Details:  Set this to be Dynamically Allocated
  • Disk Size:  This is down to your own preferences.  I use a Dynamically Allocated storage type with a very spacious 50Gb maximum size limit.
Open the Settings of the new Virtual Machine and make the following changes:
  • System – Processor:  Set this to an amount appropriate for your system.  I have an i7 with 8 logical cores so I set this to 3 CPUs.
  • Display – Video:  I tend to push the Video Memory up a bit but this isn’t strictly required for a Server setup.
  • Network – Adapter 1:  Leave this set to NAT
  • Network – Adapter 2:  Enable this Adapter and set to use “Host-only Adapter” / “VirtualBox Host-Only Ethernet Adapter”.

3. Installing Ubuntu Server 64-bit

Now that all of the Virtual Machine settings are correct, it’s time to install Linux.  Click on Start and when prompted, select the Linux Ubuntu Server ISO you previously downloaded.

Click Start to fire off the installation of the Server software:

  • Select your language and then select “Install Ubuntu Server”
  • Run through the setup by setting the language, region, and keyboard
  • Primary Network Interface:  Select eth0
  • Hostname:  you can enter anything you wish to uniquely identify the server.  I usually call mine “thegrid”.
  • Partitioning Method:  Select “Guided – use entire disk and set up LVM”.
    The next screen will give you one option so select that and then confirm that you want to “Write the changes to disks and configure LVM”.  The screen after that asks you to confirm the maximum partition size. Use the entire partition so just leave the default value and select continue.
  • At this point the large part of the base installation will take place and may take a few minutes.
  • User Creation:  Type in your full name on the first screen followed by the username that you will use to login on the next.  Enter a password for your main user and finally confirm that you do not want to encrypt your home directory.
  • HTTP Proxy:  This can be left blank.
  • You will be asked how you want to manage upgrades.  Select “No Automatic updates” to ensure you have full control.
  • Software:  When prompted, choose to install the following (use spacebar to select options):
    - OpenSSH Server
    - LAMP Server
    - Mail server
    - Samba file server
  • Postfix Configuration:  You can leave the default “Internet Site” and then enter a system mail name (the hostname previously entered is used by default – use that and select continue).
  • The selected server software is now installed.  This can take a few minutes to complete.
  • Install the GRUB boot loader?  Select Yes

Installation is now complete.

4. Install vim-nox

I install vim-nox at the first opportunity to make the default vi a lot more user-friendly under Ubuntu.

Log into the Ubuntu Server and run:

sudo apt-get install vim-nox

5. Assign a Static IP to Ubuntu Server

At this point, we assign a Static IP to the Ubuntu Server.  This will allow you to SSH into the server from the Windows Host as well as to access VirtualHosts setup later.

Currently, only the first Ethernet Adapter 1 (eth0) has been setup within Ubuntu.  This adapter bridges to the Host’s external connection and will allow the Ubuntu Server Guest to access the Internet.

Previously we changed the VirtualMachine’s settings to enable Ethernet Adapter 2 to use the VirtualBox Host-Only Adapter.  It is through this Adapter that we can access the Guest OS from within the Host.  VirtualBox always assigns “192.168.56.101″ to this Adapter.

While logged into the Server, run:

sudo vi /etc/network/interfaces

Then add the following to the bottom of the file:

auto eth1
iface eth1 inet static
address 192.168.56.101
netmask 255.255.255.0

Finish by rebooting the system.

6.  SSH into the Server using PuTTY

At this point I prefer to switch over to using PuTTY.  SSH into the Static IP we have setup in the previous step.

We will use this terminal to finalise the setup of the Server.

7.  Create SAMBA share

Firstly, we need to add a user to the www-data group group (replace “username” with your own):

sudo adduser username www-data

Now we give the group write permissions to /var/www

sudo chown -R root:www-data /var/www
sudo chmod -R 2775 /var/www 

Now edit your smb.conf

sudo vi /etc/samba/smb.conf

And add the following (replacing username with your own):

[www]
 comment = www
 path = /var/www
 public = yes
 writable = yes
 valid users = username
 create mask = 0775
 directory mask = 0775
 force user = username
 force group = www-data
 follow symlinks = yes
 wide links = yes

Create a SAMBA user with a password

sudo smbpasswd –a username

Now just restart samba and enjoy

sudo service smbd restart

You will now be able to Map a Network Drive in Windows Explorer and use \\hostname\www as the address.

8. Bind MySQL to the Static IP

In the SSH Terminal, run:

sudo vi /etc/mysql/my.cnf

Change bind-address from 127.0.0.1 to 192.168.56.101

9. Setup the Fully Qualified Domain Name

At this point if you restarted Apache, you would get the following error:

“apache2: Could not reliably determine the server’s fully qualified domain name, using 127.0.1.1 for ServerName
… waiting .apache2: Could not reliably determine the server’s fully qualified domain name, using 127.0.1.1 for ServerName”

To fix this, run:

sudo vi /etc/hosts

It should look like (replacing “thegrid” with your hostname):

127.0.0.1       localhost.localdomain localhost
::1     thegrid localhost6.localdomain6 localhost6
127.0.1.1       thegrid
# The following lines are desirable for IPv6 capable hosts
::1     localhost ip6-localhost ip6-loopback
fe00::0 ip6-localnet
ff00::0 ip6-mcastprefix
ff02::1 ip6-allnodes
ff02::2 ip6-allrouters

10. Fix an Ubuntu 11.10 PHP5 quirk

There is a quirk with Ubuntu 11.10 related to legacy items removed but the configuration wasn’t changed.  The error thrown related to PHP not being able to load the dynamic library ‘/usr/lib/php5/20090626/sqlite.so’.

To fix this, just zip up the conf.d (in case you require it later):

sudo bzip2 /etc/php5/conf.d/sqlite.ini

11. Setup a sandbox virtualhost

The default location for your websites on the Apache server is in /var/www/.  We’ll setup a “sandbox” site but this procedure can be repeated for any other sites you need to create.

Firstly, create the site’s directory:

sudo mkdir /var/www/sandbox

Create a virtualhost configuration for the new site.

sudo vi /etc/apache2/sites-available/sandbox.localdev

Save the contents of the Apache config as:

<VirtualHost *:80>
 ServerAdmin webmaster@localhost
 ServerName sandbox.local.dev
 DocumentRoot /var/www/sandbox

 <Directory />
 Options FollowSymLinks
 AllowOverride None
 </Directory>

 <Directory /var/www/sandbox/>
 Options Indexes FollowSymLinks MultiViews
 AllowOverride All
 Order allow,deny
 allow from all
 </Directory>

 ErrorLog ${APACHE_LOG_DIR}/sandbox_error.log
 # Possible values include: debug, info, notice, warn, error, crit,
 # alert, emerg.
 LogLevel warn

 CustomLog ${APACHE_LOG_DIR}/sandbox_access.log combined
</VirtualHost>

Enable the new Apache config:

sudo a2ensite sandbox.localdev

(You can disable sites by running a2dissite instead of a2ensite)

Restart Apache:

sudo services apache2 restart

Finally, enable access to the website from within your Windows Host by editing the C:\Windows\System32\drivers\etc\host file to include the line:

192.168.56.101     sandbox.local.dev

12. Setup NetBeans to use the remote server

Open NetBeans and create a New Project (we’ll keep with the Sandbox example).  Ensure you set it to be “PHP Application from Remote Server”

Under “Name and Location”  type Sandbox for the Project Name.  Select the appropriate Source Folder, set PHP Version to PHP5.3 and click Next.

Under “Remote Configuration” set the Project URL to http://sandbox.local.dev.  Next click on Manage and setup the Remote Connection to use the new Ubuntu Server’s details.  Set the Initial Directory to /var/www.   If you don’t want to be asked to verify the connection each time specify a Known Hosts File (e.g. known_hosts.txt).  This will save all trusted hosts so use the same file across all projects.  Finally set the Upload Directory to “sandbox” and click Next.

Complete the New Project creation.

Lastly, click on File and select Project Properties.  Under the “Run Configuration” ensure that the Upload Files setting is set to “On Save” and “Preserve Remote File Permissions” is ticked.

Now everytime you save the file it will be automatically synced with the Ubuntu Server.  This means that you can continue to develop using NetBeans in Windows and immediately view these changes against your new LAMP server running locally on your laptop.