Article: Run your own online support center »
FERDY CHRISTANT - SEP 9, 2006 (01:44:55 PM)
Recently I have opened up an online support center for my s3maphor3 software brand:
From the online support center, registered users can submit change requests, report bugs and problems, and request information concerning the software I produce. All in all, an intuitive, open, web-based service that brings structure to my change management process.
This article will explains you how to set up your own web-based support center using open source software in less than one hour. Useful for developers working on open source software, but also for a small business that sells their software over the internet.
The change management software that we will use is called Mantis, an open source bug tracker based on PHP. Mantis requires both a PHP server and a database server, where MySQL is prefered. For the full requirements of Mantis, go here. In essence, this means that you need access to PHP hosting, where you have control over the scripts that get installed to the web server, as well as the required database on the database server. PHP hosting is dirt cheap nowadays, and otherwise you always have the option to host it from your home server.
The installation effort of Mantis really depends on your PHP hoster. If you have a PHP machine that is properly configured (database creation access, SMTP routing working, etc) it is dead easy. When you have a shared hosting provider, things may be more difficult. So, let's take this step by step.
- Download Mantis. You can download the latest version of Mantis here. Once downloaded, extract it to a directory on your local machine. The directory will be called something like "mantis_1.0.5". At this point, you may want to rename this directory to something more user friendly. I have chosen to rename it into "support", since that will look much nicer in the URL once we uploaded the application.
- Upload Mantis. Provided that you have proper access to your PHP hoster, you can now upload the "support" directory to your web root. Most providers provide FTP access to do this. Once completed, we need to change the file permissions of the directory contents, because the installation script requires write access to some files. Because I could not find which files require it, I decided to give all files in the support directory this access level. If you know a better way, please let me know. Anyway, the way to grant the write access to files may differ per provider. Mine gives me a visual way to change the permissions for the uploaded files. If you have command line access only, you will need to "chmod 777" all files in the directory recursively.
- Run the install script. This step is crucial. When you run the Mantis install script, it will try to create the bug database and generate configuration settings. The install script will present you a setup screen once you access your Mantis installation (at address "http://yourdomain/yourdir", i.e. "s3maphor3.org/support"). The setup will ask you to provide a database name and some user credentials. If your provider allows you to install new databases from a script, simply follow the instructions on the setup screen. If the installation is indicated as a success, continue to the next step. If not, please consider the following instructions:
My provider does not allow me to generate a new database from a script. Instead, I have to use their front-end web interface to create one. Perhaps your provider gives you a phpMyAdmin interface. Either way, just manually create a database, and remember the database name, and the user name and password to access the database. Go back to the Mantis setup screen, and enter the database details of the database you just created. If installation is successfull, continue to the next step. If not, follow the instructions below:
Even when manually creating the database and entering the connection details, I got a fatal error indicating that the connection was refused. Mantis tried to setup the tables inside the database, but failed. Go back to the install script and enable the checkbox that prints out the SQL statements. Run the install script. It will now output a long list of SQL statements to setup the database tables. Copy it, and manually execute the query against your database. I did this using phpMyAdmin, but there's other software to do it. Finally, I went back to the install script, disabled the print SQL check and ran it again. This time it was successfull. I hope you don't have to do all this, consider it a worst case installation scenario.
There, the hard part is done. Now it is time to setup your copy of Mantis. When installation is successfull, you are proceeding to the login screen of Mantis. You will also see two warnings, marked in red text. Let's deal with those first.
- Change the administrator password. One of the warnings indicate that you need to remove the administrator account or change the password of it. At the login screen, log in as "administrator" with password "root". You may expect the administrator's user name and password to reflect the values you entered in the setup screen, but this is not the case. When logged in, go to "my account". From there, change the administrator password and email address. You can also change other preferences, such as email notifications from there.
- Remove the admin directory. You should really remove the "admin" directory inside your Mantis installation from the server, because anybody can access it without logging in. Before you do, you can open it as a URL to adjust the style sheet settings of your installation. Once removed, go back to the Mantis login screen. All warnings should be gone now.
- Test email notifications. Mantis has an extensive email notification feature, which allows user to track bugs. It is also used to signup new users, so it is crucial that it works. If you're lucky, it works out of the box. If you're not lucky, you need to do a bit of extra work. Let's test it. Log out as an administrator and go back to the login screen. From there, click on "Signup for a new account". Enter the details of your new non-administrator user, and provide an email address you have access to. Once you submit the form, check the inbox of the provided email address to see if the automated account activation email arrives. If it works, continue to the next step. If it doesn't, follow the instructions below:
Sending email by SMTP from scripts did not work for me out of the box, due to my providers' restrictions. In most scenarios this means that you will need to find a SMTP server address from which you can send emails. Most SMTP servers are not open, so it is likely that you also need authentication information, such as a valid username and password. Once you have collected this information, you need to manually edit a config file. The config file is located in your Mantis directory and is called "config_inc.php". Open it in edit mode, it will have the database connection details in there. We now need to add SMTP settings to make email notifications work. Here is the config file contents that I used. I have scrambled setting values to protect the security of my setup:
// database hostname. use 'localhost' if PHP and DB is one same machine
$g_hostname = 'mysql.myprovider.com';
$g_db_type = 'mysql';
$g_database_name = 'yourdbname';
$g_db_username = 'yourdbusername';
$g_db_password = 'yourdbpassword';
// use PHPMailer to send out emails
$g_phpMailer_method = 0;
$g_validate_email = 'ON';
// server address of SMTP server
$g_smtp_host = 'smtp.myprovider.com';
// user name and password to authenticate with SMTP server
$g_smtp_username = 'yourSMTPusername';
$g_smtp_password = 'yourSMTPpassword';
$g_administrator_email = 'firstname.lastname@example.org';
$g_webmaster_email = 'email@example.com';
$g_from_email = 'firstname.lastname@example.org';
$g_return_path_email = 'email@example.com';
Save the config file once you are done editing it, and check again to see if email notifications work. Without it, Mantis essentially is not usable.
Assuming you have successfully completed the installation and configuration steps, it is now time for the fun part: getting Mantis ready for your usage. The following instructions are suggestions to make Mantis ready for your users, but you can choose to do things differently of course.
- Create projects. You are probably setting up a support center to support applications or services. These are called projects in Mantis. By creating projects, users can assign bug reports and change requests to them. To create a project, log in as the administrator and go to "Manage". Next, click on "Manage project". From there, click on "create new project". Per project, fill out he basic details and click on "add project".
- Add project details. Oddly enough, you can only add extra project settings once you saved them. So go ahead and open an existing project in edit mode. If you are supporting complex projects, you may want to use the sub projects feature to further structure your change management.
Next, you can add "categories". These are not project categories. They are categories in which bug reporters can assign tickets. I have chosen to provide the following categories: change request, bug report, problem report and request for information. I am using this for all my projects. Once you assigned them to your first project, you can easily reuse them by using the "Copy categories from" feature. If you're supporting software, you will also want to assemble the list of versions in the project details. This way you can keep track of the bugs found in which version of your application.
Finally, you can assign user accounts to the project, only those users will be able to submit tickets for it. If you're supporting open source software, you should not use this feature, so that everybody can submit tickets.
- Customizing the appearance.
Almost done. Let's make some small changes for the sake of a better user experience. First, it is nice to post a welcome message on the main screen. This message will appear to users once they are logged in. You can welcome users and tell them about your service. To do this, Mantis has a news section. When logged in as an administrator, go to "Edit news". From there you can post your message. If you want the message to be permanently displayed, enable the "Announcement, stay on top" checkbox.
Next, you may want to customize the big ugly Mantis logo. You can do this by simply replacing the file "mantis_logo.gif" in the "images" directory of Mantis with your own logo. If you would like the supply extra formatting, or would like to rename your logo file, you will need to edit the reference to it in the "core\html_api.php" file in the Mantis directory.
- User acceptance test. We should be done now, so let's test it. Place yourself in the position of a new user. Go to the login screen, and signup for a new account. Wait for the activation email to arrive and activate the account. Report a new issue using the "Report Issue" link, upload a screenshot image in the issue and submit it. Access your support email address to see if you have an email notifying you of the new issue. Open the link in the email and see if you can access the uploaded file. Change the status of the issue and see who gets an email about it. Complete the cycle until the issue is in status "resolved". Note that users can adjust their email settings in their account settings.
a working, customized support center in action
Of course, there is a lot more to Mantis than this article can and will tell you. Yet, I hope that with the help of this article you will be able to quickly set up a professional support tool for your own organization. Like subversion, it has brought tremendous improvements in the structure and professionalism of my software development. I hope it does the same to you.