HOW TO INSTALL NEW ROUNDCUBE VERSION ON SHARED HOST CPANEL WITH PGP KEYS WORKING
So, you want to not wait for RoundCube to release 1.4 to cpanel, or, you have Roundcube on your cpanel setup and for whatever reason the Enigma plugin that makes the PGP stuff work – isn’t working. Whatever your reason is, the solution is not insanely hard, but it took me about a week and a lot of hours to figure out how to get it going. Hopefully this will save you many hours that I lost! 🙂
Probably this page will work for future stuff too for future releases so I’ll leave the download pages more general.
Before we begin, quick thanks to everyone at Roundcube for really improving the look, feel and security of everything. Really nice upgrades in the UI for version 1.4 RC!
STEP ONE – DOWNLOAD
- Get your version (in this case 1.4-rc) from this Roundcube download page
- Download compressed Roundcube file to your computer
- Upload compressed Roundcube it via FTP (or whatever method you like)
- In your cpanel File Manager, Right click on the compressed Roundcube file and ‘extract’ – the file will decompress and extract the directory with the same name in the same directory where you clicked ‘extract’
- Locate the newly extracted file and rename to something you like. This will form part of the URL when you log into your email. If you leave it as is the URL will be too long and annoying so changing it to something like ‘mail’ or ’roundcube’ would be smart. Maybe don’t call it ‘webmail’ because most shared hosting uses that? Not sure, I didn’t test that but something more unique would probably be smart.
- go to the URL of your domain, with the new directory folder and add ‘installer’ at the end and this will start installer. You can read details on the Roundcube installation page and we are now at step ‘Configuring Roundcube’
Create your MYSQL database for Roundcube
You’ll need a database to make Roundcube work. Although this kind of stuff seems scary, it’s not that scary as long as you don’t delete stuff that’s already there that you don’t know about. In short, all you are gong to do is create a database, create a user for the database, and then glue the user to the database. That’s it.
Before you begin this part you should have some kind of password manager software setup, I think, so you can create strong passwords and not lose them. Otherwise, ‘do it the way you like’.
- in your Cpanel home panel, go to ‘MYSQL Databases’
- in the top section, Create New Database, give your new database a decent name like ’roundcube_abc’ (no one sees this stuff, it’s just back end). You will note that it will automatically append something to the front. That will be part ofyour database name, not just the part you are typing in the field.
- Click ‘Create Database’ button
- Scroll down to the MYSQL Users section and in the ‘Add New User’ section at the top, create a new username with a strong password. You can use the password generator and then make sure to save it safely. You will note that it will automatically append something to the front. That will be part ofyour username name, not just the part you are typing in the field.
- Click ‘Create user’ button
Now you have both a database and a username. the last steps are to glue them together.
- Scroll down to ‘Add User to Database’
- From the ‘User’ dropdown, select the user you just created
- From the Database dropdown, select the database you just created above
- Click the ‘Add’ button
It will take you to another screen where it asks what permissions you want to give this user in this database. You will give it all permissions which should be the default (all boxes selected).
Confirm these changes.
Really you should read this entire page and learn a bit as your setup might be different and it’s good to review the items they mention, although most or much of it is for people who have full access to their servers, not cpanel people.
Once you start the installation process, there really isn’t too much documentation on how to actually set it up. It will start a kind of ‘installation wizard’ but not a lot of help is there during the process. You’ll need to have the following items near you before you begin:
- The email credentials that will be using Roundcube including: server names, type of email (ie. SMTP, IMAP), security protocol of each, ports for each. You can get all this from your email provider.
- The database name, user name, and user name password for the MYSQL stuff you created above
Once all this is in hand simply walk through all the fields and do your best. The details of that part is out of scope of this tutorial but there is one vital point which you absolutely must seclect in order to use encryption and PGP and that is, in the plugin section you must select the Enigma plugin which will add all the functionality.
Again, be sure to install the the Enigma plugin.
Fixing the enigma_pgp_homedir not specified error
After installation is complete and everything appears working, if you were to go to the settings and to PGP keys you will be greeted with a warning that enigma_pgp_homedir is not specified, or, if you tried to simply put the path in there as if it were a full control server, it probably won’t work. At least that’s what happened to me and the purpose of this tutorial.
The solution to properly point Roundcube to a secure folder was pretty hard to figure out but now that it’s figured out should be pretty easy for you.
You should apparently not put your pgp key folder into the enigma plugin folder, or in the document root folder. Frankly I”m not skilled enough to know all the whys but I’ve learned to trust people smarter than I. So, I put the directory in the main directory of my domain where roundcube is. You can mirror this for simplicity and probably should. So, here go the steps:
- In cpanel File manager go to: public_html/yourdomain.com
- Create a folder for your keys. For this tutorial I’ll call it ‘keez’ but you can call it whatever you want. Make sure permissions are 0755 (they should be after you create it)
- In File manager, navigate to this location: /yourRoundCubeInstallationFolder//plugins/enigma/
- Locate the config.inc.php.dist file
- Touch it, right click on it, and rename and remove the ‘.dist’ from the end of the filename and save the change
- Touch the newly renamed file again and right click and ‘edit’. This will open the Cpanel text editor.
- It will give you a warning that by editing you can break everything, which of course we know, so, click edit again and reall stick it to the man!
- Scroll down in the code stuff until you see this section:
// REQUIRED! Keys directory for all users.
// Must be writeable by PHP process, and not in the web server document root
$config[‘enigma_pgp_homedir’] = null;
Now is the fun part. All you have to do is enter in the path that points to your keys folder that you created in step 2 above.
Mine now looks like this:
$config['enigma_pgp_homedir'] = realpath(__DIR__.'/..'.'/..'.'/..').'/keez';
As long as you put your keys folder in the main directory of your domain and named it ‘keez’ this line shoud work. If you have your folder somewhere else you’ll have to adjust accordingly. What I learned was each instance of
'/..' moves up one level directory. So this command is saying ‘you will find the ‘keez’ folder by going up 3 levels from where you are now”.
Once you have adjusted this one line of code, click the ‘save changes’ button in your cpanel editor.
Go to your Roundcube email, go to ‘settings’ and go to ‘PGP Keys’ and you should now have working PGP functionality working in your Cpanel Roundcube, plus, you are running the new mobile-friendly version 1.4 now that all the paths are working.
I hope this helps!