Appliance:Simple Machines Forum Appliance

From rPath Wiki

Appliance Homepage: smf.rpath.org

Software Homepage: simplemachines.org

Current Version: Simple Machines Forum 1.1.9 packaged in appliance version 2.1.1.9 | Download

Description: The Simple Machines Forum (SMF) Appliance includes the SMF package, a minimal Linux operating system, and an administration interface. The SMF package was built from a direct download of the SMF tarball, and when installed on a Conary-based system, it includes the appropriate Apache and PHP configuration in addition to updating the permission and ownership of the installed forum files. The goal of the appliance is to provide a forum with minimal need to install, configure, or maintain the underlying operating system, all of which should be accomplished through the administration interface in any web browser.

SMF Community Forum thread for this project: http://www.simplemachines.org/community/index.php?topic=168444

In compliance with a redistribution agreement with Simple Machines, LLC, and in accordance with the Simple Machine license, the appliance delivers the software exactly as downloaded from simplemachines.org. If applicable, work-arounds for known bugs have been applied to the software to ensure the optimal appliance experience.

This appliance includes software protected by the Simple Machines License and the GNU General Public License. This software should be free for all users and only redistributed in accordance to these licenses.

Download

Visit the SMF Appliance Releases page to select a release for download. Note the list at the bottom of the page that includes several options ready to be deployed on various hardware platforms and hypervisors. Choose the one that best fits your deployment needs:

• Installable CD/DVD (32-bit and 64-bit)
• Raw Filesystem, Xen Virtual Appliance which is a Xen DomU that can be deployed on a Xen hypervisor (Dom0) (32-bit only)
• Amazon Machine Image (AMI) which is a Virtual Appliance for use on Amazon EC2, a cloud computing environment that is only pennies per hour of use (32-bit only)
• VMware (R) Virtual Appliance for use in VMware Player or any other VMware virtual environment (32-bit and 64-bit)

Install and Configure

Install the appliance in accordance with its image type. After installation, step through two points of configuration as described in the following sections: the appliance and the forum.

Configure the Appliance

Appliance administration is provided through a convenient web interface, eliminating your need to drop to a command line for ongoing maintenance. This interface is powered by rAPA and customized for use on the SMF appliance. Access this interface by from a web browser over secure HTTP by hostname and secure port 8003, resembling the following URL:

https://<hostname>:8003

The initial user name and password for the management interface is admin with a password of password. Step through the initial wizard to reset the administrative password, specify notification emails, adjust network settings (if necessary), set up a root password (otherwise blank), and configure a backup plan. See the Appliance Administration pages for more information about the various administration options in this interface.

The inline text in the rAPA interface, customized for the SMF appliance, provides further information and instructions about the tasks you can perform in that interface.

Backups for the appliance not only include some essential Linux operating system configuration, but also include dumping the SMF database and backing up that dump file along with all other SMF files.

Configure the Forum

The appliance is configured so that a user who uses a web browser to access the hostname or IP address of the new system is immediately redirected to the forum URL:

http://<hostname>/forum

If you have not yet set up your forum, the install.php file runs by default prompting you to complete two consecutive forms with information used to initialize the forum. These setup steps are just the native Simple Machines Forum software configuration. As you complete this initial setup, note that MySQL is in its default username and password (root with no password). Complete the configuration by:

• Modifying the forum name
• Selecting a forum administrator username and password
• Identifying the email address for the forum administrator
• Typing root as the database admin user name, and leaving the password blank

Please note that if you change from using the default MySQL username and password, the appliance backup mechanism will not perform as configured for the appliance, and you will need to use the SMF built-in tools or the MySQL command line for performing backups of the SMF database itself.

Updating to 2.1.1.9

If you have appliance version 2.1.1.6 or higher, updates should only require these steps:

1. Log in to the administration interface at https://<hostname>:8003.
2. If you do not have a recent backup of your appliance, be sure to launch a backup before running your update.
3. Click Updates on the left.
4. Click to check for updates.
5. If updates are shown as available, click to apply those updates.

In case there are issues with your update, use View and Apply Rollbacks to roll the system files back to their previous state. Rollbacks to not restore a previous database schema, though; in the rare case you have an issue with a database update, do a simple database restore from your backup dump. (See MySQL documentation throughout the Internet for more information.)

If you choose to perform updates to the SMF software either at the system's command line or through the SMF interface itself, this will likely break the appliance update mechanism built into its web management interface. This is not discouraged for those familiar with maintaining software on a Linux operating system, but it is important to note that you have the update options within the management interface, too, which is automatically configured to run the update or upgrade scripts as appropriate between any two given versions of SMF.

A user named apache owns the files in /srv/smf/, and the appliance ownership settings may require adjustments to get the SMF updates to work through the forum's administration pages.

Future Features

The development team has a goal to add the following to future versions of the appliance:

• A 2.x beta release with an appropriate update path from 1.1.x built in to the appliance.

Developer Notes

The following are notes that I have been making as I go regarding the development process for the appliance. --SEW

17 June 2009

Though I am not working in a professional capacity with rPath, I am still excited about the SMF appliance and dedicated to keeping it going. I still have not tackled the new 2.x branch, but I have spent a lot of time ensuring 2.1.1.6 will upgrade to 2.1.1.9, and that known issues with the upgrade process are addressed with workarounds in the appliance. A new release is going out today!

10 November 2008

Because I like to use the SMF appliance as an example and demonstration resource for my work in rPath Training, I knew I needed to get the project up-to-date. Most of what I would have said here has already been said at the SMF community thread dedicated to this project, so check it out there:
http://www.simplemachines.org/community/index.php?topic=168444

20 December 2007

My SMF-saavy colleague found this awesome link to help parse the information in SMF packages. We need to use this because we are not using FTP for installing and maintaining the packages in our SMF appliance: http://www.smfhacks.com/smf-package-parser.html

20 November 2007

I have packaged SMF 1.1.4 and updated the appliance to version 2.0, released on label smf.rpath.org@smf:2. The rAPA interface has been customized for the appliance, including replacing the standard rPath product logo with the Simple Machines Forum logo as currently shown at simplemachines.org.

INSTALL NOTES

If you have not installed this appliance before, this is an excellent time to get started. This is because there have been several enhancements to the underlying Conary software that will make it easier to deploy, update, and administrate your appliance, and that will make it easier for me to keep it up-to-date. From this point forward, an update is a one-click operation in the rAPA interface and should rarely require command line access.

UPDATE NOTES

If you have an installed appliance, the update to this version requires dropping to a command line. (After this update, I will ensure that future updates can be done in the rAPA web interface.) As your appliance's root user, run the following commands to update to the latest Conary (required for the migrate to run successfully), to migrate the Conary-managed files to their latest versions on the smf:2 label, and to remove the install.php file:

#> conary update conary
#> conary migrate group-smf=smf.rpath.org@smf:2
#> conary remove /srv/smf/install.php

Future updates will automatically skip install.php after an update; if the file is just removed with rm, a Conary group script in the appliance group still ensures it is removed after an update. Additionally, if scripts are needed to update to a new database schema, those will be run automatically.

If you have questions or concerns about updating an existing appliance, feel free to leave a comment on my blog entry at stefw.livejournal.com.

27 August 2007

I have packaged SMF 1.1.3 at smf=smf.rpath.org@smf:2.

INSTALL NOTES

This package installs SMF version 1.1.3 in its entirety as from the download at simplemachines.org. Use conary update on a Conary-based system to install the package:

#> conary update smf=smf.rpath.org@smf:2

As with previous installations, the installed package is available at http://HOST/forum where "HOST" is the hostname or IP of the install target. Use the two initial configuration screens to set up the forum name, SMF database, and initial user account. The MySQL database user is root and has a blank password.

UPDATE NOTES

For those with installed packages and appliances, note the following if you wish to proceed with a Conary-based update to version 1.1.3:

• The appliance hasn't yet moved to smf.rpath.org@smf:2 and still includes SMF 1.1.2; watch smf.rpath.org to see when group-smf is available on smf:2.
• The new smf package can be used to update smf=smf.rpath.org@smf:1 (previous release), but this will require a manual (command-line) removal of /srv/smf/install.php file after the update. The following commands will do the trick:

#> conary update smf=smf.rpath.org@smf:2
#> conary remove /srv/smf/install.php

Note that the second command will ensure that the install.php is not reinstalled during future Conary updates. Use this with caution as it is intended for those who will update the software regularly and should not need to repeat a setup for the SMF MySQL database.

• In the appliance for @smf:2, I plan to include a rAPA plugin that should cover the necessary quirks for initial SMF configuration as well as continued Conary-based updates.

25 June 2007

In an attempt to learn how to develop rPath Appliance Platform Agent plugins for appliances, especially for Appliance:Fogawi, I started with a simple plugin for this SMF appliance. It appears to be working fine, but I am having an issue cooking my groups in 64-bit flavors. Not knowing if anyone has deployed with 64-bit flavors, I don't want to break the appliances when they update, so I am going to wait until my group cooks work before I release the appliance with the new plugin.

The plugin itself is only really applicable to initial configuration of the forum after the appliance is installed. The idea was to have a plugin in the agent interface that linked to the forum main page with a message to use the forum software itself to complete initial configuration and ongoing administration. The plugin, then, is not very applicable to existing installs, but it will not hurt to have it in there as a reminder to link back to the forum itself for forum-specific maintenance.

When I have verified that the plugin works as intended on a new installation of a released SMF appliance, I will move on to adding it with other plugins in Fogawi.

9 April 2007

After having used the open-source Simple Machines Forum PHP forum software, even since it was the cgi-bin-based YaBB, and after administrating two forums using the software, I decided to package the software and create an appliance that would facilitate using that software in a Virtual Private Server (VPS) or other environment dedicated to the forum. Because I was using Conary package management, I knew I could create a package that would install the downloaded tarball and configure file permissions and ownership as needed. I also knew I could build an appliance group that could be used to create images for more than just a VPS.

The SMF package seemed straightforward at first: unpack the tarball and add Apache and PHP configuration. I created a conf file to package with the software and ensured that my package recipe would install that for the required Apache and PHP configuration:

Alias /forum %(smfdir)s
<Directory %(smfdir)s>
    php_value max_input_time 30
    php_value post_max_size 8M
    php_value upload_max_filesize 8M
    php_value session.use_trans_sid Off
    php_value memory_limit 16M
    php_value max_execution_time 30
    php_value register_globals Off
</Directory>

For a true appliance experience, there should be no need for additional administrative tasks after the installation. The administrator should perform some simple configuration tasks if necessary and then leave the appliance to its end users except for scheduled checks and updates. In its initial draft, the package still required permission changes to allow certain files and directories to be writable. Therefore, I used SetModes method in my package recipe the necessary permissions: I used 0755 for directories and 0644 for files. This step allowed me to bypass the permissions advisory when I made the initial attempt to access the forum.

After attempting my forum configuration, I received an error that the install.php file was not deleted, even though I checked for it to be deleted after installation. At this point, I noted that root was the owner and group on all the contents added by Conary, unlike a typical tarball install made by a non-root user. For administrators to make the changes necessary during installation and regular forum administration, I changed owner on the same writable directories and files to apache:root, making the web service the owner.

Following more tests, I noticed that this was not sufficient to remove the install.php, and making install.php itself owned by apache was also not sufficient. I made a test adjustment to the recipe to give ownership to apache for all contents in /srv/smf (where the package installs the files), and I used conary verify after successful forum configuration to determine what files were deleted and modified since the package install. Knowing this, I adjusted to set owner for both install files that were deleted during the test, and I set owner for the top level (/srv/smf) to ensure that the files could be deleted.

Also, I discovered during one of the tests that the mode was correct on the files, but not the directories; an associate recommended using the ExcludeDirectories method on each directory to force the related directories to be packaged as directories in Conary, overriding Conary's default to include files individually. This solved the problem with the directory permissions. Recipe for smf package

To add to the appliance nature, I packaged a redirect page (index.html file) that would redirect hostname to /forum.

After the packages tested successfully, I added them to the appliance group group-smf. The group started with group-core for the core operating system, with a conditional to choose the flavor of group core appropriate for the architecture (32-bit or 64-bit). Added to the group were Apache and its depedencies, PHP and the components needed to tie PHP with MySQL, and MySQL and MySQL server.
Recipe for group-smf