Having a non-production "test" server with all of your live data copied to it is one of those things that I think all Rock admins know is a good idea, but unless you're actually a developer and regularly managing databases the thought of actually creating it can be a little intimidating.
If you haven't thought about it yet, be assured that being able to test workflows, bulk updates and new blocks on a copy of your data, instead of risking the integrity of your actual production data, definitely makes things easier and might even help you sleep better at night.
You need to have file level access to the server hosting your website, so you can manually copy the existing files from your current Rock instance, to a new directory.
You need to be able to manage your SQL databases - I'm assuming you're using SQL Server Management Studio
You'll also need to have your first instance of Rock already up and running
You'll also need to be performing regular backups of your first database (If you're not not, stop and read this first).
This article is based on my own experience, and for what it's worth, I'm using on-premises servers (both the IIS host and my SQL Server host) running Windows Server 2012.
For this article I'm using SQL Server Express 2014 with Tools
A word about PCI compliance
Since this article was written, that it's been pointed out by some in the community (correctly, in my opinion), that having your sandbox on the same hardware as your production data is not PCI-compliant. If your production instance of Rock needs to be PCI compliant (for instance, if you're taking payments through Rock), you will need to copy your files and backups to a separate server and deploy them there instead as outlined below.
Step 1: Copy files
On your IIS (web) server, open up File Explorer and find the root of your website (the location you placed Start.aspx when you first Installed Rock. By default, this is C:\\inetpub\\wwwroot.
Right-click this directory and choose "Copy". Paste it somewhere and name it something meaningful to you-
RockSandbox, for instance.
Step 2: Create a separate database
Open up SQL Server Management Studio. Expand your server and right-click the "Databases" directory therein, then select
Under "Source", keep "Database" selected, and then select your production database from the drop-down. It will find your most recent backup and assume you want to restore to the same database as the
Destination. But we don't. So next to "Destination", type a new database name into the
Database input (rather than selecting anything from the dropdown). I recommend keeping things consistent and use the same name for the database as your used for the new directory in step 1. Assuming it found your most recent backup of your production database, you can leave the
Restore to and
Restore Plan settings as they are. Click OK to start.
It will give you a progress bar and then inform you that your database was restored. Click OK and now you'll see your new database on your server. Now you can close SSMS.
Step 3: Point the new installation to the new database
In file explorer, open up the directory you created in Step 1.
web.ConnectionStrings.config, right-click it and choose "Open With", then select "Choose Program". Uncheck "Use this app for all .config files" and then find and select notepad.
Find "Initial Catalog=" and replace the following database name with the name of the new database you just created. For instance, you might be changing
Initial Catalog=rock to
Initial Catalog=rockdev. Save and close the file.
Step 4: Create a new site
Now open up "Internet Information Services (IIS)", expand your server and the "Sites" directory therein. You should see your Rock site here- depending on whether you renamed it during setup or not, it will either be called "Default Website" or whatever you renamed it to.
Right-click on "Sites" and click "New Website". Again, I recommend keeping things consistent and using the same name as you gave the new directory in step 1. Click the ellipsis (
...) button next to "Physical Path" and find the new directory you created in Step 1.
The rest of this form requires a little bit of knowledge of IIS setup and especially your existing Rock site.
Probably the easiest configuration is to leave the bindings set to "All unassigned IP addresses" and set the "Host Name" to the address you'd like to use to access this test installation, such as rockdev.rocksolidchurchdemo.com. With this configuration however, you'll need to also go and make sure that your production Rock site is set up with the correct host name as well- if that one's left blank (the default configuration), you may accidentally be loading your production site at the new address AND the existing address instead of keeping them separate.
Alternately you can tell this new site to only be bound to a specific IP address- meaning that you're going to need to update your DNS records so that it's addressable.
As always, it's best to only use https since you're typing in passwords and dealing with sensitive data, but that does require a wildcard certificate, since IIS can't serve different certs per site and you need https on BOTH your production and your development site.
If you usually have a non-https site that simply redirects to your https version, consider whether you want to do the same for your development site.
Step 5: Configure a few options in your new Rock site
Launch your new site by typing in the address you gave it in IIS.
At this point, you should probably make some trivial change, say to the front page, and then log in to your production Rock installation to make sure that it HASN'T gotten the same change. As long as they're different, congratulations: you now have a development environment to test in with impunity!
But, as far as your new installation knows, it's the only Rock installation you have. That means it wants to send out notifications, run jobs and everything your normal installation does. So, here are a few more things that are highly recommended on all new (or restored) development servers:
You don't want your development site sending out reminder e-mails, scheduled messages and the like- we'll leave that for your production site to take care of.
The easiest way, in my opinion, should be to simply disable the communication transports and/or mediums so there's simply no means of your sandbox sending any messages out.
Admin Tools ->
Communication Transports in your development instance, then click on each "Active" transport and change "Active" to "no".
However, there's a bug prior to v5.0 that allows communications to be sent out even through disabled mediums and over disabled transports. So it's best to also simply disable any jobs (and possibly workflows) which might send out e-mails.
Admin Tools ->
System Settings ->
Jobs Administration, and then edit and de-activate any jobs like this on your dev server. At a minimum, disable
Send Communications and
Send Attendance Reminders. Depending on what location services you use, you should probably disable
Location Services Verify as well so you're not racking up double charges by having your development site pinging your paid service.
You may have other jobs that bear disabling as well- look this list over carefully and when in doubt, disable any non-system jobs.
Update API Keys
This varies wildly from church to church, but if you have API keys for external apps, Google analytics, etc, you'll probably have to edit or disable those.
Consider whether things like a background check provider needs to be disabled as well, or put into a "test" mode.
In general, if you don't know what these are, it likely means you haven't created any and so you probably don't have to worry about them. Be sure to ask questions about this of anyone who has helped you customize Rock.
The other item I found quickly in my initial use of a secondary site is that it goes dormant pretty quickly and has to spin up again when you come back. That's because the keepalive routine is actually pinging your original site. So go to
Admin Tools ->
General Settings ->
Global Attributes and change the URL configured in both
Global Application Root and
Internal Application Root to match the address of your dev site.
Consider whether you'd like this sandbox to run the BETA versions of Rock- if so, sign up for the mailing list and then while you're on the
Global Attributes page, change your
Update Server Url to
Finally, it's obviously pretty important that you make sure you're always on the right site. So consider whether you want to add an HTML block to the login page (go to /page/3 on your new site and you can use the admin bar to add elements like normal), to the main internal page, or if you want to apply a different theme to the alpha site entirely. What you choose to do depends largely on what you're testing.
David Stevens in the Rock Community provided this great and simple solution: go to the "Pre-HTML" section of the "Smart Search" block in the navbar and add the following code:
<h4 style="position:absolute;left:80px;top:6px;">You're on the development server ¯\\_(?)_/¯</h4>
This changes the head of all of your pages using the current template on the development server to something like this:
If you want to have it on all of your pages, you can run this in Power Tools -> SQL Command (notice we have to use Unicode for the "face" in this case, since we're using an HTML form):
SET PreHtml = '<h4 style="position:absolute;left:80px;top:6px;">You are on the ALPHA server ¯\\_(ツ)_/¯</h4><script>$(".navbar-static-top").css("background-color","khaki");</script>'
WHERE [BlockTypeId] = 254
If you do update the blocks all at once using this SQL command, you'll need to clear Rock's cache before it will show up. So from the admin bar (hover your mouse at the bottom of the browser window), click the
i icon to bring up the
System Information dialogue. Then click the orange
Clear Cache button. Once it informs you the cache has been cleared, you can refresh the page and you should see your message show up on all your templates with the Smart Search block on it.
A few 'gotchas'
Take careful note of this: It's unwise and unsafe to develop something in your development site and then try to import it to your production site! Tempting, I know, especially when you've spent potentially hours developing the workflow you've finally perfected. But don't import it. Once you've got it working perfectly, re-create it from scratch in your production site. Why? Because from the moment you created the backup you used to create the database, the two sites have gone their different ways. Pages have been created in one and not the other, people have been edited and created in one and not the other, so IDs will have incremented differently in the two sites. Links to a new page you need to create will be a different page id, etc. So I know it's a bummer, but you really just need to create your new items in production from scratch while using your development site as a reference.
Updates from one Rock version to the next will, of course, have to be done in each site separately.
Resetting the Dev Site
There will probably come a time when you need to bring the dev site back into sync with your production site. That is, you want to erase everything you've done in the dev site and not in the production site.
Step 1: The beginning of this process is always going to be to launch IIS and "Stop" your dev site. Also open up the
Application Pools in your IIS instance and stop the pool associated with your dev site.
Step 2: Delete the directory with the dev files in it (the directory you created in step 1 at the beginning of this article). If both sites are on the same version of Rock and you haven't installed any plugins, you can possibly skip this step. But it's always safer to copy your production Rock files to the development instance to make sure you're totally in sync.
Step 3: If you do delete and re-create the files in step 2, be sure to edit your
web.ConnectionStrings.config file again (step 3 at the beginning of this article)
Step 4: Restore your Rock Development database from the most recent backup of your production database.
In SSMS, right-click
Databases under your server, and select
Restore Database.... Under "Source", keep "Database" selected, and select your production database (just called 'Rock' in my examples) from the drop-down. That will set your destination database to 'Rock' as well, so go and change "Destination" to "rockdev" or whatever you called your development database...this time you can select your development database from the drop-down. No need to change any restore options or create a new database name after the initial database creation.
- Step 5: Start the IIS site and application pool again, then load the development site in your browser. Be sure to run through step 5 above again, disabling jobs, resetting APIs, visually distinguishing this site, etc. (Once you get to know exactly what you're doing you'll probably be able to develop a few SQL commands that do everything you need at once).
Hopefully having a development site proves to be as helpful to you as it has been for me! Let me know if you know of anything I missed, or better/more efficient ways to do the steps mentioned here. Rock on!
For the SQL- and Scripting-inclined amongst us, the Spark team also put together their own scripts and recommendations for handling this process.