Pro tip: Troubleshooting common Roundcube installation issues
Email is as ubiquitous a service as it comes. From business to personal uses, promotional and marketing -- these communications all thrive off of email's ease of use and ability to reach millions of users almost instantaneously!
And yet, few things seem worse than when its powerful messaging capabilities are offline or otherwise unavailable. It can bring businesses to a grinding halt, which is one of several reasons why managing email takes up quite a bit of IT resources in ensuring the highest level of service and uptime possible.
Setting up Mail in OS X Server is not a difficult task inherently, nor is configuring Roundcube webmail installer to serve as the webmail front-end for users to access email from a browser. However, just as there are issues that can creep up during any installation, Roundcube has a few that are common to many installations and will prevent end users from accessing their webmail correctly until resolved.
For the purposes of this article, we'll assume that the Mail service for OS X Server is installed and configured properly and that users are able to send/received email. We'll also assume that the Websites service for OS X Server has been configured with an internet-facing fully qualified domain name (FQDN) and that Roundcube has been installed into a directory within the web server's folder for that domain.
The following errors may be seen when attempting to complete the Roundcube installer configuration -- specifically, during step three or Test config as Roundcube verifies the information entered in prior steps and marks the sections with a green OK for verified or red NOT OK, which indicates that an error has occurred.
1. Check config file
Roundcube webmail is a PHP web application that requires configuration in order for it to perform its functions. Particularly, the "config.inc.php" must be first created and then copied to the Config folder located within the Roundcube folder at the root of the domain host folder.
Roundcube performs step one as a means of offering a GUI to configure the email settings specific to your organization. Step two gathers the previously entered data and allows the user to confirm that it's correct before creating the config.inc.php file. The newly created file must then be copied to the Config folder before proceeding to step three -- otherwise, the verification will run and the Roundcube installer will not find the necessary configuration file in place and label it as NOT OK (Figure A). More importantly, Roundcube will simply not function properly without this configuration file in place, as it won't be able to detect the database or connect to the email service.
Figure A
Check the config file.
2. Check if directories are writable
There are two directories used by Roundcube to record important information and changes to the PHP app. Both the Logs and Temp folders are located within the root Roundcube folder in the domain host folder. Both Logs and Temp require read/write access in order to be able to write logs files as errors and other useful information (Figure B).
Figure B
Be sure to check if directories are writable.
Be default, the Logs and Temp folders do not have the necessary rights assigned to them. Doing so requires administrative credentials and Terminal.app. Entering the following commands, one line each, will modify the folder permissions for each directory and allow the Websites service read/write access to each folder for recording information on the fly.
sudo chmod -R 777 /path_to_roundcube_root_folder/logs
sudo chmod -R 777 /path_to_roundcube_root_folder/temp
3. Check DB config
The DB config error is arguably the most common issue when setting up Roundcube, and it's also the most ambiguous one to troubleshoot (Figure C). Since Roundcube relies on several services to run, each presents a different variable or wrinkle in the solution that may (or may not) be part of the problem.
Figure C
Check for a DB config error.
While the error deals specifically with not being able to access the database itself, there are variables introduced by MySQL (database server), Websites service (web server), and Mail service (email server). Additionally, there may also be issues pertaining to network configuration, DNS, and/or ISPs preventing access to certain service ports.
This makes resolving this type of error potentially frustrating to pinpoint the exact source. However, some of the typical culprits are as follows:
A. Database not setup/configured properly
i. Check the MySQL database to verify proper configuration. You may wish to create a new db just to test the settings.
B. User Account to access db not setup/configured properly
i. Again, check the MySQL account settings, paying particular attention to the privileges granted to the account. If ALL privileges are not granted to the account for the db, it will fail to connect.
C. Websites service not on
i. Websites service may have stopped working due to an error or related system issue. Enter the following commands in Terminal.app to start, stop, and view the status of the web server.
sudo serveradmin start web
sudo serveradmin stop web
sudo serveradmin fullstatus web
D. Incorrect config.inc.php file configuration/file missing
i. Review step one above for reconfiguring/replacing the missing file.
E. DNS not resolving domain to IP
i. Verify authoritative DNS forward and reverse lookup records for the domain pointing to your webmail server. Ensure the records are pointing to/from the correct IP/domain.
ii. If not using a static IP or hosting email from SOHO behind a dynamic IP, check DNS settings on both OS X Server and authoritative DNS server
F. Network configuration
i. Verify correct static IP address(es) have been assigned to web/mail services.
ii. Ensure proper Firewall rules have been created to allow traffic to/from service ports/IP addresses.
iii. If not using a static IP or hosting email from SOHO behind a dynamic IP, ensure port forwarding entries have been created to forward specific traffic (80,443 for web; 3306 for SQL) to a specific IP.
iv. Confirm port-based traffic is not conflicting with other application traffic configured to route through the same port.
G. ISP blocks on certain ports
i. Check with your ISP for ports being blocked at their level that may cause interference with services running from your organization. Ports such as 25 are commonly blocked due to SMTP relays being a vector for SPAM proliferation.
ii. Confirm port-based traffic is not conflicting with other application traffic configured to route through the same port.
Roundcube troubleshooting can be tricky at times due to the number of dependencies required and working together to provide access to the web app. However, many of the issues may be resolved relatively quickly with a little due diligence.
Furthermore, Roundcube -- being an open-source product -- has quite the loyal following and is heavily supported though their support portal that contains links to user-support forums, wikis and even professional, paid support services from Kolab Systems.
