I thought this specific tutorial might help others who have the same set up as me: in need of setting up a test environment for trying custom SuiteCRM code before deploying it. A developer may wish to give you some code, log in and patch it themselves for testing, etc, or, you might want to try something without breaking something.
I wrote this blog about doing a similar thing on your own localhost hacking machine but it wasn’t easy to let a developer patch the files (remote access) for me so I decided to apply the same skills and do it again on a remotely-accessible server.
This blog also assumes you already have your main Suitecrm site set up. If you don’t you could hack your way through my loosely written blog if that helps.
So from this point on we assume you have the key elements already installed on the remote server: Apache2, Mysql, PHP stuff and LetsEncrypt.
Setting up the Subdomain
- Log into your Digital Ocean (DO) space
- Click under the domain within which you wish to place the production server (I use the same domain but you can do whatever). Mine was ‘dev.domain.com. By doing this right away, the domain can be propagating through the internet so that there is less delay time as you do the rest fo this tutorial. Note, if your domain is not there and then you have to set that up first via ‘networking’ in the DO space. Likely there are great tutorials out there to do that.
Set up the Directory for the SuiteCRM Files
There is a section nearer to the end of this tutorial where I lost most of a day (SFTP), so heed this next tip:
TIP Do NOT put your developer directory on the same level as your production directory unless you are super skilled with SFTP, SSH, file permissions, and a whole bunch more. Make it one level below your production server.
I use /var/www/html directory for my production site. If yours is different adjust the path accordingly.
- Move to the html directory:
- Create a folder called something like ‘testing’ (whatever you want):
- Then create your actual directory for the files below that
TIP As smart as I thought I was using a short and logical name, do NOT name your directory ‘dev’ like I did above once. I forgot there was a linux-critical directory at the top level called dev and I accidentally messed up permissions on that so I realized it’s best to call everything ‘suite___’ or some other code that you will always remember when typing directory…
Now you have a directory for your production SuiteCRM files.
Set up the Virtualhost file so that the server can send traffic to the Dev SuiteCRM files
Assuming you still have your 000-default.conf in your /etc/apache2/sites-available directory from when you installed your Ubuntu:
- Move to the ‘sites available’ apache directory:
- Copy the default and give it a new name for your dev site such as
cp 000-default.conf dev-world.conf
- Adjust your new flashy conf file so that it receives traffic from your dev.domain.com domain and so that it points to the files in your new directory you just made:
sudo nano dev-world.conf
Make sure the following items are added and uncommented in the top section there in the appropriate place (lots of other examples online about setting up virtual host files for Ubuntu servers if you feel you need to study this one more):
If you are intense and you think someone might add www before all that you could add this too:
Save your changes.
EDIT: forgot these commands to enable your new conf files, etc:
disable default site
enable your conf:
Let’s Encrypt it
Assuming you already set up LetsEncrypt, and assuming your domain has propagated long enough to be reached (I had fails in the past because of not waiting long enough for propagation, so note this!) then you should now be able to run the LetsEncrypt certbot command and get https working.
Scroll to the bottom of this blog post if you want details on that.
Run the certbot command and answer all the questions accordingly:
sudo certbot --apache
Backup your SuiteCRM files and Database
Just follow this blog I wrote if you need to learn how to back up your files.
Create a New Test Database (separate from your production database)
Assuming your files are backed up as per above, it’s time to create a new test database and import your backed up database into it. This database is a separate one in case something goes sideways. I was thinking about sharing it with the production one but yeah – probably not smart. This isn’t that hard to do so might as well be safe, says I.
This recent blog i made gives the step by step for getting your Suitecrm files and database set up for import into the dev environment you are trying to setup.
If your server doesn’t have a mysql mariadb kind of setup (it should if you are on the same one as your Suitecrm setup…) then you can follow my recent blog for more of that in section 3. Otherwise:
Log in to your secure mysql installation (this will be same password as your original secure installation password from your production install):
sudo mysql -u root -p
Create the test bed database (I named it ‘devsuitecrm’):
CREATE DATABASE devsuitecrm;
I thought I could skip this next step but I learned the long and hard way you need to create a unique username and password for your new database. You could use same as your old one but I’m going to try with brand new both:
Create the user and password for the database replacing username and password in the following code with yours between the apostrophes:
CREATE USER 'username_here'@'localhost' IDENTIFIED BY 'new_password_here';
Do whatever this does, lol:
GRANT ALL ON devsuitecrm.* TO 'username_here'@'localhost' IDENTIFIED BY 'same_password_here' WITH GRANT OPTION;
TIP I had endless problems connecting to suitecrm database because of auto-generated characters in the password. This post indicates the forward slash might be the cause. I made sure to remove the forward slash in my password, delete the original mysql user / password, and then re-create but it still never worked. Finally, I removed all special characters from the password, did the above again, and everything worked. I’m not sure if this is mysql or suitecrm but but pw should allow special characters!
Tell mysql to switch to / use this new empty database you just created:
Into this new database, we will import the backup sql file with this
source /path/to/your/suitecrm.sql; (of course adjust to where your file is…) and press ‘fire’ and see what happens. If it starts working you should see a stream of ‘Query OK 0 rows affected..’ messages as it works its way through.
TIP If you are used to using the ubuntu terminal and the tab / autofill feature, it just doesn’t seem to work while logged into mysql / mariadb. It works for stuff inside mysql, but not outside (like the path you need now…) It’s hard to remember the path and easy to make mistakes so what I do to have the path copy-able and paste-able is log out of mysql with
exit; if i’m logged in, go to where the file is with
cd, then run
pwd which will print the current working directory and then
ls to print file name. Then I log back into mysql admin and copy the path from the terminal with my mouse and the filename since they are now visible right above as well as the filename itself. Just a trick that seems to work for me but I feel there must be a better way, haha.
In my case, my sql file was sitting temporarily in my home directory in a folder called ‘suite_backups’ so I did this command to bring it in with this workflow:
Log into mysql admin:
sudo mysql -u root -p
Swithc to database:
Type ‘source’ and paste in the path after copying from terminal command (result of
Type a forward slash to make room for file name in the path:
Copy the filename from terminal and paste into path:
Type the final semi colon and you have your final command to press enter and run:
Congrats. You probably have your database info from your production site now in your development database.
Move the Backup SuiteCRM Files into the dev production folder
Disclaimer on this step: there may be a better way with less steps but this works. The suitecrm backup file is a .zip. As a result, you’ll have to unzip it and get the files into your /dev directory. What I do is this workflow:
- create the backup zip file with Suitecrm admin GUI
- Move the backup .zip (let’s name it ‘suitecrm_backup.zip’ for this example) to my home folder (this is probably the extra step you don’t need but I feel more comfortable working in my home directory because it says ‘home’, lol) with the
- Make sure I’m in the home directory with the
- Unzip the backup file there while I’m in the home directory since the command is more simple and fast: ‘unzip suitecrm_backup.zip’
- Check if the new extracted directory is there with
- Move the contents (only) of the directory to your /dev/ directory: sudo mv suitecrm/* /var/www/html/testing/deeptesting
TIP That little asterisk is the difference of moving just the contents or the whole directory so if you forget it the whole directory will move and you’ll have to reverse it and do it again or do other file gymnastics..
If everything worked well, you now have the files in your appropriate directory and you have a copied version of the original database.
Re-installing SuiteCRM as Dev Environment
We aren’t quite done yet.
Now we’re going to run a command to get ‘composer’ in there. Disclaimer is I have no idea what composer is nor what it does but it seems Suitecrm needs it…
From inside your new ‘deeptesting’ directory run
sudo composer install
It will do a bunch of ‘stuff’….
Now your config.php file will be mysteriously missing if you had it before. my guess is that it will be recreated after it forces you through the installer / database connector thing…and I was right.
Re-Run the Database connector thing with SuiteCRM GUI
If all is done, and you should now be able to go to your dev.domain.com and it should bring up the ‘installer’ wizard kind of thing to connect to your database. Just use localhost for the host and all the mysql stuff you made for your new credentials. I used the same admin/pw for my production side for the admin user to keep things a bit more simple but you don’t have to.
Now you should be able to log into your instance as a developer and not worry about breaking things.
If you get stuck, don’t forget my notes about the mysql password and the special characters. If you can’t seem to connect, try with a long random password without special characters and if it works, you know the issue.
FTP User Creation / VSFTP
Here is my advice: don’t even bother with FTP. I spent most of a day trying to make it work and it sucked bad. SFTP wasn’t a walk in the park either but it a) finally worked (unlike FTP) and b) it’s more secure so yeah. But if you’re dead set on doing FTP, please find This video as a nice starter to learning about it.
Setup the SFTP user with SuiteCRM Dev folder access (and nothing else)
First, learn this in depth. Slowly read it, study it know it, it’s very well written and great
Then, the critical learning element for me was this, as addressed at the TOP of this blog:
In my /var/www/html/ directory, I had two directories:
- my production site
- the development site I just made above
However, when the remote person wants to log in, they are going to see and have access to both directories (which is bad). So, what I did to solve this was put the development directory one level deeper and then adjusted all the permissions again, as well as the associated documents as follows:
- sshd_config (this line: ChrootDirectory /var/www/)
- /etc/apache2/sites-availble conf files (both the main and the -le (letsencrypt) files for the document root directory so that suitecrm would corrrectly load.
Now I have both SFTP access to only that directory and the dev crm is still working
But if you kept yours one level deeper as recommended, it’s likely you won’t have to go through this pain (hopefully). But if you did it like I did it accidentally, now you know a solution.
- what a chroot is
- what a document root is (compared to chroot)
- and all those ‘tip’s above.
A great day’s learning if that’s worth anything…
I also thought it would be way shorter and easier but I hope this walk-through has helped one or more of you save a lot of time and headaches as a lot of this stuff is just pulling it all together in one place.