Solution architecture
##Solution architecture
The allReady application is implemented as a Visual Studio 2015 solution that contains two projects: an ASP.NET 5 project that serves the web site and admin portal, and a cross-platform Cordova app project. The web application also exposes REST APIs used by the mobile app to access data.
###Web Application
An ASP.NET 5 web application provides the front-end web experience for volunteers accessing the allReady web site and the portal used by administrators. The site is powered by ASP.NET MVC 6 using .NET 4.6 and a dependency on .NET 4.5.1. Here's the landing page for the web site:
The web site relies on the following frameworks:
- Bootstrap: responsive layouts on mobile devices
- Font-awesome: scalable vector icons
- Hammer: gesture support
- jQuery: ubiquitous JavaScript library
- Knockout: MVVM bindings
####REST APIs
The same ASP.NET 5 project also exposes a set of Web APIs which are part of the MVC 6 framework. These REST APIs are used by both the web site and the Cordova mobile app.
####Data layer
Data is stored in a database that is accessed by the ASP.NET application using Entity Framework 7.
####Cloud services
The allReady web project is designed to be hosted in Microsoft Azure. The following services are used by this application when running in Azure:
- App Service Web Apps: hosts the web application.
- SQL Database: storage of relational data.
- Storage: storage of uploaded BLOB data.
####Authentication
Authentication of web site mobile app users leverages OAuth 2.0 with credentials from external authentication providers such as Facebook, Twitter, Google or Microsoft. Users can use their existing social media accounts to sign into the web site or mobile app. For more information, see Enabling authentication using external providers.
###Cross-platform mobile app
The mobile app project was added to the allReady solution as a Visual Studio Tools for Apache Cordova project.
The client app relies on the following frameworks:
- AngularJS: extensible web app framework
- Apache Cordova: cross-platform device deployment, including these plugins:
- Ionic: enhancements for Cordova apps
- Moment.js: working with date-time values
The app accesses the Web API exposed by the web app for data access.
Users can sign-in with supported social providers such as their Facebook, Twitter, or Microsoft. You must configure each of these providers for the mobile app separately, as described in the next section.
##Get started with the allReady solution
This section will help you get up-and-running with the allReady solution.
###Prerequisites
You will need the following to be able to run the allReady solution locally:
-
Visual Studio 2015, the F# Visual Studio tools, the tools for Apache Cordova (which are included in the latest Visual Studio release) and optionally the emulator for Android apps. All of the needed tools are supported by all versions of Visual Studio 2015 including the free Community Edition. Download Visual Studio 2015.
-
To use ASP.NET 5 RC1 with Visual Studio 2015, you will need to download and install the ASP.NET 5 runtime and tooling https://docs.asp.net/en/latest/getting-started/installing-on-windows.html#install-asp-net-5-with-visual-studio.
You will need the following to be able to run the allReady solution in Azure:
- An active Microsoft Azure account to deploy the web app. You can sign-up for a free trial of Azure here.
###Configure the web project
The AllReady project relies on configuration settings at runtime, such as whether to use a local database or an Azure SQL Database for data storage, whether to load sample data, default accounts information, and credentials for connecting to other services. These setting values can be stored in the project's config.json file. However, doing this makes it easier to accidentally expose secrets. ASP.NET 5 includes a secrets manager tool, and you should instead use this to locally store settings in your user account. When you publish the project to Azure Web Apps, you will need to set these same values as app settings in your web app.
Note: currently the codebase does not include any 'secret' values in configuration. Since we deploy both a dev and live site for this project via HTBox, we will configure 'production' values for testing and production environments. Additionally, we are working on how to best support open development with identity providers listed below for all contributors and will update this information when a full solution is found.
Configuration settings are accessed at startup using the Configuration property, which implements Microsoft.Framework.Configuration.IConfiguration. The following example gets the value of the InsertSampleData field that is a child of the Data node:
Configuration["Data:InsertSampleData"]
These topics show you how to use the secrets manager for app settings when running locally and how to add app settings in your web app in the Azure portal:
- Safe Storage of Application Secrets
- Enabling authentication using external providers
- Configure web apps in Azure App Service
The following app settings are used by the project.
####General settings
These settings control how the web app stores and seeds data:
| Key value | Description |
|---|---|
General:SiteBaseUrl |
Used when creating links (when composing emails). Set by default as localhost:33310 but should be overridden in deployments. |
####Data settings
These settings control how the web app stores and seeds data:
| Key value | Description |
|---|---|
Data:DefaultConnection:ConnectionString |
The local DB connection string. This setting is required to run the app locally. |
Data:InsertSampleData |
When true, seed data is loaded into the data store. |
Data:InsertTestUsers |
When true, test user accounts are created on start-up. |
Data:Storage:AzureStorage |
The Azure Storage service connection string. |
Settings in bold should be stored in the secrets manager.
####Authentication settings
These settings are the credentials for the app registrations of the social media platforms supported for authentication:
| Key value | Description |
|---|---|
Authentication:Facebook:AppId |
The ID of the Facebook app registration. For more information, see Register your apps for Facebook |
Authentication:Facebook:AppSecret |
The shared secret for the Facebook registration. |
Authentication:Twitter:ConsumerKey |
The consumer key of the Twitter app registration. For more information, see Register your apps for Twitter |
Authentication:Twitter:ConsumerSecret |
The shared secret for the Twitter consumer key. |
Authentication:MicrosoftAccount:ClientId |
The client ID of the Microsoft account app registration. For more information, see Register your apps for Microsoft account |
Authentication:MicrosoftAccount:ClientSecret |
The shared secret of the Microsoft account registration. |
All of these settings should be stored in the secrets manager.
####Connected service settings
The following settings enable the web app to connect to other services:
| Key value | Description |
|---|---|
ApplicationInsights:InstrumentationKey |
The instrumentation key used by Application Insights. |
Authentication:Twilio:Sid |
The ID the Twilio account to use for voice or SMS. For more information, see How to use Twilio for voice and SMS capabilities from Azure |
Authentication:Twilio:Token |
The authentication token for the Twilio account used to send email. |
Authentication:Twilio:PhoneNo |
The phone number to display in a Twilio voice or SMS. |
Authentication:SendGrid:UserName |
The username of the SendGrid account used to send email. |
Authentication:SendGrid:Password |
The password of the Microsoft account app registration. |
Authentication:SendGrid:FromEmail |
The email address that appears as the sender when users receive notifications. |
Authentication:MicrosoftAccount:ClientSecret |
The shared secret of the Microsoft account registration. |
All of these settings should be stored in the secrets manager.
###Configure the mobile app project
The URL of the AllReady web site is set in the domainUrl variable in the /www/app/services.js file.
###Run and test locally
Once you have set the required settings either in the config.json file or in the secrets manager, you can run and locally debug the projects. If you have not yet created a SQL Database in Azure, you should use Data:DefaultConnection:LocalConnectionString as the connectionStringPath value in Startup.cs.
Currently there are hardcoded user accounts for limited testing (this will of course be changed soon) For now:
- "DefaultAdminUsername": "[email protected]"
- "DefaultAdminPassword": "YouShouldChangeThisPassword1!" (all accounts use this default password)
- "DefaultUsername": "[email protected]"
- "DefaultOrganizationUsername": "[email protected]"
###Deploy to Azure
The AllReady project is designed to run hosted in Azure. The following sections describes the steps needed to get the AllReady web app running in Azure as you develop. Note that App Service Mobile Apps are currently available in the Azure Preview Portal.
Note: Again as with config, we will be hosting test and production instances of the application in the near future for tester contributors looking for instances of the application to test against and for others to reference. The instructions here are for self hosting in your own trial instance, if you choose, during development. However-- our goal is for all development to be able to be performed locally with alternatives or emulators for the online pieces.
####Create an Azure Web app
To publish the AllReady project to Azure, you must first create a new web app in an Azure App Service environment. To learn how to do this, see How to Create a Web App in an App Service Environment.
Once you have created your web app, you must create the required app settings. To run the site, you must create a connection string setting for Data:DefaultConnection:AzureConnectionString. To learn how to do this, see Configure web apps in Azure App Service.
####Create SQL Database
The next step is to create a new Azure SQL Database. To learn how to do this, see Create your first Azure SQL Database. Once you have created your database in Azure, make sure that Data:DefaultConnection:AzureConnectionString is set as the connectionStringPath value in Startup.cs.
Note: If you have created a firewall exception for your local computer, you can use this connection even when running on a local machine. For more information, see Step 5: Configure the firewall.
####Publish to Azure
Once you have your web app configured, you can publish the project to Azure. For more information, see Deploy a web app in Azure App Service.