Running on Mac OS X

Development Installation Instructions for allReady

This installation guide was built and tested for Mac OS X Sierra with the latest updates as of March 20th 2017 and should work with future version of Mac OS X.

Required Dependencies

XCode with Developer Tools
Homebrew
.NET Core SDK
Microsoft SQL Server*
Docker*
Git
NodeJS/NPM

* - Microsoft SQL Server and its dependencies are optional if you choose to use a database hosted using Microsoft Azure or alternatively you can run SQL Server in a linux docker container.

Installing XCode

Install XCode from the OSx App Store. Ensure you select Developer Tools when installing.

Installing Homebrew

To determine if Homebrew is already installed, check in the /usr/local directory for a folder called 'Homebrew'

For instructions on how to install Homebrew see their website here

Installing NodeJS and NPM

With Homebrew already installed execute the following command to install NodeJS and NPM:

brew install node

Installing .NET Core SDK

Instructions to install the .NET Cored SDK on Mac OS X can be found here

Follow all instructions including the steps to compile some test code to verify everything is configured correctly.

Setting up a MS SQL Server database

Option 1: Installing SQL Server locally

To install Microsoft SQL Server locally your machine must have at least 3.25 gigabytes of RAM. If your machine has <= 3.25 GB of RAM you will not be able to install Microsoft SQL Server using this guide.

In order to run an instance of MS SQL Server locally on Mac OS X, you will have to install the Docker platform. Note docker requires CPU Hyper Threading, so your Mac hardware and/or VM must support this to proceed. Install the Kitematic tool to be able to view your Docker containers and then finally create an MS SQL Server instance.

Install Docker

Via Docker Website Launch the disk image and follow the instructions
Launch the Docker application after installed (if needed)
Click Docker menu on top right dock and choose “Kitematic”
Follow instructions to install Kitematic (if needed)

Create a MS SQL Service instance within Docker

Configure the docker preferences so that the memory for new docker containers is at least 3.2GB. This is required for SQL Server to run: https://docs.docker.com/docker-for-mac/#advanced Go to the SQL Server for Linux image page for more details: https://store.docker.com/community/images/microsoft/mssql-server-linux
Download the SQL Server Linux docker image:

docker pull microsoft/mssql-server-linux

Create a container named allready_sqlserver:

docker run --name allReady_sqlserver -e 'ACCEPT_EULA=Y' -e 'SA_PASSWORD=yourStrong(!)Password' -p 1433:1433 -d microsoft/mssql-server-linux:latest

Run SQLCMD to create the database:

docker exec -it allReady_sqlserver /opt/mssql-tools/bin/sqlcmd -S localhost -U sa -P yourStrong(!)Password >create database allreadydb >GO >

Update the connection strings in appsettings.json in the source code of the web application:

"ConnectionString": "Server=tcp:localhost,1433;Initial Catalog=allreadydb;Persist Security Info=False;User ID=sa;Password=yourStrong(!)Password;MultipleActiveResultSets=False;Encrypt=True;TrustServerCertificate=True;Connection Timeout=30;"

Note that you need to make sure you set TrustServerCertificate=True

For more detailed information go to this site and follow the instructions under the section "Get the Docker Image". This site has some good information and some Docker configuration you may want to take advantage of as well.

See this link for a similar link to the one above, however this one is an official link from Microsoft. The above link has a lot more information but this is good to have in your back pocket.

Option 2: Using Microsoft Azure to host a SQL Server DB for you

Create a free trial Microsoft Azure account at https://azure.microsoft.com/en-us/free/

After creating an account and subscribing to the free trial service navigate to the Microsoft Azure portal.

From the portal you can click on New(green plus sign) > Databases > SQL Database and begin to create the allReady database.

You can name your database whatever you'd like however for this guide we will be calling it 'AllReady'. When creating the database you will create a server for the database as well. Be sure to remember what your server name is as well as the admin account username and password.

After creating the database and server it will be deployed. To access it from your machine select the database server in the Azure portal, click on overview and then click Set Server Firewall. Then click Add Client IP to add a firewall rule to allow your IP to access the database. Click save and wait for up to 5 minutes for the changes to take effect. You will then be able to access the database.

Install sql-cli (mssql) Command Line Tool for MS SQL Server

Using NPM, run the following command to install the sql-cli command line tool:

npm install -g sql-cli

Building allReady

Overview

To set up the allReady development environment you will need to retrieve the code from the allReady repository on GitHub. If you plan to contribute to allReady you can fork the repository so that you have your own personal copy of the codebase to work with. You can either choose to download your fork or a branch from the main repository.

Install Git

If you do not have Git installed, you can download and install from here

Download Source

To download the source code, clone the repo with the following command:

git clone <repo URL>

Building the Web-app

After downloading a copy of the code you can begin by restoring the dependent packages for the project.

Navigate into the top-level directory of the repo and complete a restore with the following command:

cd AllReadyApp
dotnet restore AllReadyWebOnly.sln

Now build the webapp:

cd ../Web-App/AllReady
dotnet build

Database Configuration

The connection string within the software to the database must be modified in order to point at and connect to our MS SQL Server.

It does not matter which user connection account is used with the database. If you create one on your own, assure that it has 'create database' permissions.

Configure the Database Connection

While in allready/AllReadyApp/Web-App/Allready:

Update the file config.json with replacing the default text with the following:

{
  "Data": {
    "DefaultConnection": {
      "ConnectionString": "Server=<localhost or URL of database>;Database=AllReady;User ID=<user id>;Password=<password>;MultipleActiveResultsets=true;"
    },
    "HangfireConnection": {
      "ConnectionString": "Server=<localhost or URL of database>;Database=AllReady;User ID=<user id>;Password=<password>;MultipleActiveResultsets=true;"
    }
  }
}

Building NPM packages

From within ./AllReadyApp/Web-App/AllReady/ run:

npm install

Running the web-app

From within allready/AllReadyApp/Web-App/Allready run the app with:

ASPNETCORE_ENVIRONMENT=Development dotnet run

Setting the environment variable ASPNETCORE_ENVIRONMENT=Development gives us more useful error messages in the app for diagnosis during development.

To access the web app, navigate to the following URL via your browser: http://localhost:5000