Skip to content

Latest commit

 

History

History
242 lines (138 loc) · 15.5 KB

README.md

File metadata and controls

242 lines (138 loc) · 15.5 KB
Raw

Rock RMS

Build status

Rock RMS is a Relationship Management System (RMS) and plugin-friendly framework written as an ASP.NET 4.5 C# web application. It uses Entity Framework 6.1, jQuery, Bootstrap 3, and other open source libraries.

The following guide documents how NewSpring Web uses and deploys Rock.

Quick links:

Getting Started

Take a peek at the Rock Developer 101 book to get started. Some more information can be found on the wiki.

If you're completely new to .NET, C# and SQL Server, you may want to read through this overview. If you're completely new to Github and Git, read through the Contribution guidelines.

Primary Differences

We try our best to stay in sync with the base repository; however, we have a few primary differences:

Repo Size

If you clone the base repository, you'll notice that there are a LOT of binary files. This doesn't work so well for quick build and deployment times (even with caching certain folders). So we've removed the following folders to reduce the overall size:

  • ./Applications
  • ./Checkin Labels
  • ./Installers
  • ./packages

Applications and Installers can be downloaded through the Rock Shop (for production) or from the base repo (for debugging/development). We don't use the stock Check-in Labels; all our labels can be found here. Packages are automatically downloaded in production or development via Nuget.

Deploy Configuration

We use Appveyor to do continuous deployment to different environments. It's fast, free (for one build at a time), and relatively easy to set up. We depend on Node/Norma to add plugins to the build and MSBuild to compile the entire solution. You'll notice the following files in our repo:

  • ./appveyor.yml

    This file contains all the build settings for AppVeyor. You can use Appveyor's UI instead, but you won't be able to track changes (especially helpful if something breaks). Formatting wise, Appveyor requires all spaces in this file (no tabs!).

  • ./Norma

    This file contains the build settings for Norma, such as plugins to download, files to copy, etc.

  • ./package.json

    This file contains all the dependencies for Norma.

  • ./RockWeb/app_offline-template.htm

    This file displays a helpful user message while Rock is upgrading or rebooting. This file exists in core but has been heavily customized with NewSpring branding.

  • ./RockWeb/before-deploy.ps1

    This file specifies what should happen before a deploy, such as saving web.config and setting the "Rock is restarting" message.

  • ./RockWeb/deploy.ps1

    This file specifies what should happen during a deploy, such as setting permissions, and restoring web.config.

  • ./RockWeb/web.config

    For security reasons our deploy process ignores any Github changes to the web.config. If there's an update in the Spark repo, you'll need to manually copy that change to each server. Keep in mind that any change to web.config will restart IIS.

Dev Environment

We have a lot of systems running in production: some we're proud of, and some we're not. We also have a native app for iOS, Android, Windows, and others. That means we often need to test systems (including Rock) from non-Windows environments. We've customized a couple things to make testing a little more friendly:

  • ./Rock.sln

    This file contains links to all the projects necessary for Rock to run, as well as links to any plugin projects. Note that if a plugin isn't downloaded locally, Visual Studio will gracefully ignore the reference. Rock.sln also specifies the name and URL of the web project.

    Note: We changed the Rock website name and URL to be http://rock.dev instead of RockWeb with a URL of http://localhost:6229. This allows us to load and debug Rock cross-platform. See New Environments for more details.

Custom Plugins

We've written a few plugins for Rock, including a CyberSource gateway, a CacheBreak project for API's, and an Attended Check-in module. We store plugins at the same folder level as Rock, then reference them in ./Rock.sln with a relative path (..\rock-cache-sync\cc.newspring.CacheBreak.csproj).

The following list details other minor blocks or packages we've added:

WebAPI Upgrade

In order to fully support Twilio and other API calls, we upgraded the Microsoft.AspNet.WebApi packages to version 5.2.3. The core version of Rock is at 5.2.2.

New Environments

If you were already given a VMDK, most of these steps should be completed. Also, this guide assumes you'll be running Rock inside a Windows environment, either as a VM or dual-boot. If that's not the case, talk to us because we'd love to optimize our development/deployment strategy.

If you haven't already experienced the joy of developing in Visual Studio with IIS, we'd highly recommend it: faster build times, easier debugging, cross-platform browsing, and bypassing the occasional VS insanity. You'll need to set up an IIS site pointed at ./RockWeb, your database has to be configured for IIS requests, and Visual Studio has to run as Administrator (so you can attach to IIS when debugging).

If you don't want to go the IIS route or prefer to use Visual Studio for everything, you can still get cross-platform browsing with some trickery. You'll also want to set a static IP on your VM and add a hosts reference to rock.dev with that IP.

Running Rock

The VMDK file you should've received can be run in VirtualBox, Fusion, or Parallels. If you're wondering what settings you should use, go back to New Environments.

Our Rock version is hosted at http://rock.dev and you can use IIS Manager to control access to it.

If you need to debug code, open Visual Studio and attach to w3wp.exe. If you don't need to debug, you can develop themes or change Block code in the running site: ./RockWeb.

Connections

./RockWeb/web.connectionstrings.config defines your database attachments, although only one can be active (comment out the others). The only connection you'll probably need is localhost\SQL. If you're using SQL Server LocalDB, the Server property will be something like (localdb)\ProjectsV13.

Note: If you get an error running Nuget or starting the Rock project, make sure RockWeb is set as the startup project (Solution Explorer will display it in bold).

Here's a sample connection string:

<?xml version="1.0"?>
<connectionStrings>
  <!--<add name="RockContext" connectionString="Server=productionserver.azure.com; Initial Catalog=Rock;
        User Id=RockAdmin; password=SomeRidiculousPasswordAPasswordManagerCreated; MultipleActiveResultSets=true"
        providerName="System.Data.SqlClient" />-->
  <add name="RockContext" connectionString="Server=.\SQL; Initial Catalog=Rock;
        Integrated Security=true; MultipleActiveResultSets=true" providerName="System.Data.SqlClient" />
</connectionStrings>

Migrations

If you need to build or update a new database, look for the Nuget Package Manager Console and enter this command: update-database -ProjectName 'Rock.Migrations'. Note that if you had any Nuget updates while Visual Studio was open, you'll need to reload Visual Studio to successfully run the Package Manager Console.

Alternatively, follow the guide to set your own migration shortcut. This will use the connection defined in web.connectionstrings.config to build or upgrade your database.

Maintenance

Eventually you'll need to run ./FreeSpace.bat to clear out old files and keep your Windows install trimmed down. This will also defrag your unused space, which allows you to shrink the disk from Fusion/VirtualBox after you shut the OS down.

Deploy Process

We actively develop against our Rock fork and occasionally "cherry pick" changes from core, instead of waiting for the official or beta releases. While this does mean we get faster features or bugfixes, we're also some of the first to find out about breaking changes.

We follow the below process to verify changes don't cause issues in production:

####1) Review recent changes in Spark/pre-alpha-release.

This branch is typically the last phase in the development cycle before a Rock release (develop -> pre-alpha-spark -> pre-alpha-release -> hotfix / master release). Click here to start a PR to NewSpring/pre-alpha-release.

You'll want to be sensitive to the following changes:

  • Migrations (will require downtime and typically can't be rolled back)
  • Check-in or workflow actions (could make for Sunday surprises, and not the good kind)
  • Model or ModelService updates (can affect performance)

####2) Fix code merge conflicts and test any migrations against a local database.

Since we've modified multiple files, you'll need to make sure changes (theirs or ours) aren't accidentally overwritten. You'll also want to test migrations against a recent copy of our database so that any Sites, Blocks, or Attributes we may have tweaked don't cause dependency problems.

####3) Merge NewSpring/pre-alpha-release into NewSpring/alpha.

Alpha is our "did anything break?" environment and is set to automatically deploy when code is committed. Click here to start the PR to NewSpring/alpha.

####4) Merge NewSpring/alpha into NewSpring/beta and deploy.

Beta is our "does everything work?" environment and does not automatically deploy when code is committed. Click here to start the PR to NewSpring/beta.

####5) Document all feature changes for the Web Operations team to review.

If you reviewed well in step one, you'll have a list of changes to send for testing on Beta. You'll want to document the default behavior as well as expected error states. You may also need to clarify where the new or updated feature lives.

####6) After Operations signoff, merge NewSpring/beta into NewSpring/master and deploy.

Master is our "go live" environment and does not automatically deploy. After a successful build, you'll need to trigger a deploy from Appveyor during planned or co-ordinated downtime.

####7) Clear cache on newly deployed servers.

It's a good idea to clear cache on the Rock and Check-in servers after a deploy, so that any changes to Sites, Blocks, or Attributes are immediately present. Theoretically IIS should pick up those changes after a restart, but it occasionally doesn't.

Learn More

Jump over to our Rock website to find out more. You can also:

Community

Rock is crafted by a community of developers led by the Spark Development Network. You can join us on the forums at Rock RMS or on our Slack channel.

License

Rock is released under the open-source Rock Community License.