Friday, October 17, 2014

Installing Drupal on FreeBSD

Drupal ports have been available on FreeBSD since quite a long time, and binary packages can be installed very quickly. However, manual setup is required to connect Drupal to the database and have Apache serve the Drupal website. In this post I'll describe the setup procedure of Drupal 7 on FreeBSD 10.0. The process will not be very different if different versions of Drupal or FreeBSD are used.

Installing Drupal

Drupal ports are available on FreeBSD and, in fact, multiple versions are available:

# pkg search drupal
drupal6-6.31
[...snip...]
drupal7-7.31
[...snip...]

Unless there is a compelling reason not to do so, install the latest one:

# pkg install drupal7

To successfully run Drupal, you need:
  • The Apache HTTP Server.
  • PHP.
  • A supported database server (PostgreSQL or MySQL).

The Drupal port, however, does not enforce these dependencies, so that you have to satisfy them manually.

Installing the Apache HTTP Server

Unless there is a compelling reason not to do so, install the latest available Apache port (apache24 at the time of writing):

# pkg install apache24

Once the port is installed, enable the corresponding service adding the following line to /etc/rc.conf:

apache24_enable="YES"


Installing the Database

Drupal supports both PostgreSQL and MySQL but the Drupal port does not install any, by default, although it installs the MySQL client utilities. In this post MySQL will be used but if you prefer using PostgreSQL instead, just skip this section and read this article instead.

Since the Drupal port by default defines the MYSQL option, when you install the binary package using pkg you'll also get a MySQL client port, such as what I got at the time of writing:

mysql55-client-5.5.40

As a consequence, you have to install the matching mysqlXX-server port:

# pkg install mysql55-server-5.5.40

If you try to install a different version (at the time of writing mysql56 is available), you may be requested to remove Drupal itself because of the inter-dependencies between the client and server MySQL packages.

Once MySQL is installed, enable the corresponding service adding the following line to /etc/rc.conf:

mysql_enable="YES"


Installing PHP

The installation of PHP is taken care of by the Drupal port. However, the PHP module for the Apache HTTP Server is not installed and must be installed manually. Make sure you install the PHP module that corresponds with the PHP version installed by the Drupal port. At the time of writing, the following modules are available:

# pkg search mod_php
mod_php5-5.4.33_1,1
mod_php55-5.5.17_1
mod_php56-5.6.1

Since the port depends on php5, then mod_php5-5.4.33_1,1 should be installed:

# pkg install mod_php5-5.4.33_1,1

The port takes care of modifying the Apache HTTP Server configuration file so that the PHP module is loaded. If you did not install the packages in order suggested by this post, then you may have lost that piece of configuration. In any case, make sure a line similar to the following is present in /usr/local/etc/apache24/httpd.conf:

LoadModule php5_module        libexec/apache24/libphp5.so


Installing drush

drush is an optional package offering an amazingly good command line interface to perform many Drupal-related management tasks: drush could even be used to install Drupal, but this topic is not covered by this post, since I prefer relying on a port tested specifically on FreeBSD. However, once you have tested that a specific release works correctly, you may find drush very useful to streamline your installations. If you are interested in using drush, you will find plenty of good information on the Internet. To install drush, the following command may be used:

# pkg install drush


Creating a Database for Drupal

A database for Drupal must be created in the DB server installed in the previous section. The MySQL port sets no password for the root user connecting from localhost; for this reason, setting its password is recommended (in bold the text input by the user):

# mysql -u root
Welcome to the MySQL monitor.  Commands end with ; or \g.
[...snip...]
mysql> set password for root@localhost=PASSWORD('your-password')
mysql> exit
Bye

Once the password is set, you can try to reconnect (in italic bold the variables whose name should be changed with your values of choice):

# mysql -u root -p
Enter password:
Welcome to the MySQL monitor.  Commands end with ; or \g.
[...snip...]
mysql> create database drupal_database_name;
mysql> create user 'drupal_user'@'localhost' identified by 'password';
mysql> grant all privileges on drupal_database_name.* to 'drupal_user'@'localhost' with grant option;
mysql> flush privileges;


Configuring the Apache HTTP Server

Now that everything is in place, we can configure the web server so that it starts serving the Drupal web application. The tasks to perform are the following
  • Configuring the required modules.
  • Configuring a virtual host to serve Drupal.
  • Configuring a MIME/type for PHP.

The modules required to run Drupal are mod_rewrite and the PHP module. The latter was configured automatically by the PHP module port, and the latter can be configured uncommenting the following line from /usr/local/etc/apache24/httpd.conf:

LoadModule rewrite_module libexec/apache24/mod_rewrite.so

The cleanest way to segregate the Drupal configuration is creating a virtual host for it. An additional advantage of this approach is that Drupal will be served from the root path (/) and you won't need to use any rewrite rule to achieve the same result. Assuming the host name and the port where Drupal will be published is drupal.host.name:80, then create a file in /usr/local/etc/apache24/Includes named drupal.conf and define the skeleton of the virtual host:

<VirtualHost *:80>
  ServerName drupal.host.name

  # Drupal directory configuration placeholder
  
  ErrorLog ${APACHE_LOG_DIR}/drupal-error.log
  LogLevel warn
  CustomLog ${APACHE_LOG_DIR}/drupal-access.log combined
</VirtualHost>

In the default configuration of Apache in FreeBSD, any .conf file in this directory is included automatically, so that no additional code is required to add the virtual host to the web server configuration. In this fragment I've used an environment variable (${APACHE_LOG_DIR}) to separate some server configuration variables that could be reused in external scripts. To define environment variables, a .env file must be created in /usr/local/etc/apache24/envvars.d such as:

The Drupal directory fragment defines the DocumentRoot of the virtual host and some of the required options:

DocumentRoot /usr/local/www/drupal7
<Directory "/usr/local/www/drupal7">
  Options Indexes FollowSymLinks
  AllowOverride All
  Require all granted
</Directory>

The option AllowOverride set to All is required so that .htaccess files shipped with Drupal are taken into account by the Apache HTTP Server. In this fragment, the path of the Drupal installation directory of the FreeBSD port is used. If you installed Drupal using alternative methods (such as drush), update the path accordingly.

The complete virtual host configuration file is:

Finally, the Apache HTTP Server must be instructed to execute the PHP code contained in PHP pages and to do so we need to add a MIME/type for them adding the following line in httpd.conf:

<IfModule mime_module>

  # Content has been trimmed

  # Add MIME type for PHP
  AddType application/x-httpd-php .php

</IfModule>

Once all the settings are in place, Apache can be restarted and you can point your browser to http://drupal.host.name/ where the Drupal installation wizard will welcome you and will require you to input the database configuration and other Drupal website settings.

To restart the Apache HTTP Server, the following command can be used:

# service apache24 restart

Configuring Drupal behind a Proxy Server

Machines connecting to enterprise network often are not connected directly to the Internet but require the use of a web proxy server instead. Drupal can be configured to use a web proxy server by setting the following variables in ${DRUPAL_HOME}/sites/default/settings.php. If this file does not exist, copy the file default.settings.php (shipped with Drupal) into settings.php. The configuration variable that enable proxy support are the following:

Depending on your proxy settings, different values may be used.

Beware that although Drupal itself (Core) supports a proxy, many third-party modules still do not. One notable exception at the time of writing is the reCaptcha module which will not work without a direct Internet connection.

Setting Up Clean URLs

Last but not least, clean URLs support may be enabled. Drupal performs a sanity check and will not allow you to enable the Clean URLs feature if the test does not pass. However, I have found plenty of false negatives when running Drupal 7 on FreeBSD: if the Clean URL test fails in your installation, try checking if clean URLs are working and use the workaround described in the official Drupal documentation and forcibly enable Clean URLs.

Saturday, September 27, 2014

fswatch 1.4.5 - Release Notes

fswatch 1.4.5 has been released.

New features and bug fixes added since v. 1.4.0 are:

  • Add custom record formats.
  • Localize fswatch and libfswatch using GNU gettext.
  • Add Italian (it) localization.
  • Add Spanish (es) localization.
  • Fix Makefile.am because of broken link when DESTDIR installs are performed.
  • Fix bug in fswatch-run wrapper script for ZSH which caused last argument not to be split when passed to xargs.
  • Add batch marker feature to delimit the boundaries of a batch of events.
  • Add Texinfo documentation.
  • libfswatch API is now versioned.
  • Improved Autoconf checks.
  • The inotify monitor now waits for events and honours the latency settings.
  • Automaticaly generate the ChangeLog using Git.
  • Update autogen.sh to honour some commonly used environment variables.
  • The inotify monitor now provides the same functionality provided by all the other monitors.
  • Recursive directory monitoring is now implemented.
  • Version and revision is now determined dynamically from Git by ancillary scripts invoked by the GNU Build System.
  • fswatch does not compile on OS X < 10.9 because some required C++11 classes are not supported by the C++ runtime.
  • fswatch does not compile on OS X < 10.9 because some required C++11 classes are not supported by the C++ runtime.
  • The libfswatch library has been added with bindings for C and C++.
  • fswatch let users specify the monitor to use by name.

Thursday, August 21, 2014

fswatch 1.4.0 - Release Notes

fswatch 1.4.0 has been released bringing few but important updates:
  • Monitor implementations are found at runtime so no more hardcoded options to choose a specific monitor (the plugging mechanism still needs improvements).
  • The fswatch engine has been moved to a separate library called libfswatch with bindings for C and C++. If you need to use the functionality of fswatch from your program, now it's very easy to do. The library and its headers are distributed in the same fswatch bundle.
  • On OS X fswatch can now be installed from either MacPorts and Homebrew (see README for more information).

I hope you enjoy using fswatch as much as I enjoy writing it.

Tuesday, August 19, 2014

Writing a MacPorts Portfile (and Testing It on a Local Repository)

As a MacPorts user, it is maybe funny that fswatch is available on Homebrew and not on MacPorts. Today I put an end to this idiosyncrasy of mine and submitted my first MacPorts port file.

I was pleasantly surprised to discover that, although a deceiving initial impression, setting up my first port file was way easier than I first believed. Furthermore, the MacPorts guys have been very supportive and provided many insights that helped me improve the port file and my understanding of the MacPorts port system (beyond what is described in the nice MacPorts Guide).

The Basic Portfile

The basic Portfile for a source tarball generated by the GNU Build System, that is a package which is built and installed with the now classic:

$ ./configure
$ make
$ make install

is typically very simple, since these two operations are performed out of the box by the Configure, Build and Destroot phases of a port installation life cycle.

In this case, the basic Portfile includes:
  • The modeline (optional).
  • The Subversion ID tag: placeholder string automatically expanded by the MacPorts infrastructure.
  • The PortSystem line: required by all ports.
  • The port name and version: many other port variables (including the source tarball name) depend on these values.
  • The category line: one or more port categories.
  • The platform: darwin most of the times.
  • The maintainers.
  • The short and long description.
  • The homepage.
  • The download URLs.
  • The checksums (used to verify the integrity of the downloaded files).
  • The dependencies (optional).
  • The configure arguments (optional).
A fully working, basic port is the following:

In this example you can see how the download URL is split in two pieces: the master_sites and the distfiles (or distnames). The rationale behind this choice is the fact that a package may typically be hosted by multiple master sites (such as mirrors).

In this example, distfiles is specified. This variable contains the full distribution file name, including the suffix (the file extension). By default this value is set to ${distname}${extract.suffix}. You may as well define the distname (which defaults to ${name}-${version}) and the extract.suffix separately. These parameters, in the example above, are redundant, since they simply set the corresponding default value (and use_zip is used as a shortcut to set extract.suffix and other variables related to processing zip files).

A Portfile for a GitHub-Hosted Project

fswatch, such as many other projects nowadays, is hosted at GitHub.  Although not yet documented on the MacPorts Guide, a recently added PortGroup called github greatly simplifies  the Portfile for such projects. The only existing documentation, at the moment, is this port group source code.

Many of the aforementioned configuration variables are inferred by a much simpler GitHub configuration such as:

github.setup        emcrisostomo fswatch 1.3.9
github.tarball_from releases

This expands to:
  • name is set as the GitHub project name (fswatch in this case).
  • version is set as the GitHub version tag (1.3.9 in this case).
  • The download URL and the distribution file name is inferred from the repository configuration and the corresponding release URL. If the distribution file name is different than the default (${name}-${version}) then you still have to configure it as described in the previous section.
The resulting Portfile is the following:


Checking Your Portfile

The port utility can check whether a Portfile conforms to the MacPorts guidelines using the lint command:

$ port lint --nitpick fswatch
--->  Verifying Portfile for fswatch
--->  0 errors and 0 warnings found.

In the example above the fswatch Portfile passes verification with no errors nor warnings. Be sure to check your Portfile before submitting it to the MacPorts repository.

Testing Your Portfile With a Local Repository

You can test and store your Portfiles in a local repository before submitting them to a public repository in a private repository. Furthermore, you can take advantage of the MacPorts package management features to maintain your own local packages.

Adding a Portfile to a local repository is very simple:
  • Create the local repository directory somewhere (if it does not exist).
  • Create a subdirectory (if it does not exist) named after the primary category of the port you are adding.
  • Create a subdirectory named after the port.
  • Move the Portfile into this directory.
  • Make sure the user macports has sufficient privileges to read the repository (I usually give him ownership of the port directory).
  • Update the port repository indexes running portindex from the repository root.

If you have not done it yet, you have to configure MacPorts to use your local repository, adding a line in $MACPORTS_HOME/etc/macports/sources.conf:

file:///ports

right above any other repository so that ports in the local one take precedence over ports in the public repository.

If everything is setup correctly, you will be able to query and install ports from your local repository.

Further Readings

A basic Portfile such as what I described in this blog post is just the beginning: we only scratched the surface of what MacPorts can offer you. If you want to get further information about MacPorts and the facilities it provides (either from an user or a developer standpoint), start from the MacPorts Guide.

Public Domain Flags Archive (in Vector Image Format)

Some time ago, when I was implementing the EMCCountryPickerController component I described in some earlier posts (such as this one), I soon realised I needed high quality images of the flags of all the countries listed in the ISO 3166-1 standard. And since the EMCCountryPickerController library is GPL-licensed, I needed images whose license was compatible with it in order to distribute them together with the component.

I found decent collections of flags in the internet but at the end I decided to build my own, especially in order to overcome problems that arose from the limited resolution of many image collections.

I picked the flags from Wikimedia Commons since they're available in SVG format (a widely used vector image format). This way, if I need to, I can render a flag at any resolution.

I then assembled a GitHub repository where you can find:
  • All the flags in SVG format.
  • All the flags in PNG format scaled to a width of 256 pixels.
  • All the flags in PNG format, scaled to a width of 512 pixels.

The following is a shell script that can be used to render the flags archive at the desired widths.

The script requires librsvg to be installed.