Running on Linux

Development Installation Instructions for allReady

This installation guide was originally written targetting Ubuntu 16.04 but has not been updated for Ubuntu since then and was last confirmed not working. Instructions for Fedora and Arch have been tested and working as of September 2017.

* Microsoft SQL Server is optional if you choose to use a database hosted using Microsoft Azure. Alternatively you can run Microsoft SQL Server in a docker container to reduce the setup steps required.

Installing .NET Core SDK

Ubuntu

Instructions for installing .NET Core on Ubuntu linux from microsoft can be found here.

For Ubuntu 16.04 run each of these commands in a terminal:

sudo sh -c 'echo "deb [arch=amd64] https://apt-mo.trafficmanager.net/repos/dotnet-release/ xenial main" > /etc/apt/sources.list.d/dotnetdev.list'
sudo apt-key adv --keyserver hkp://keyserver.ubuntu.com:80 --recv-keys 417A0893
sudo apt-get update

These commands update your local package lists. Then install the .NET Core by running:

sudo apt-get install dotnet-sdk-2.0.0

Fedora

.NET Core falls short of several requirements for addition to the official Fedora repositories (namely around prebuilt binaries and bundled dependencies). The .NET SIG (Special Interest Group) maintains a repository of unofficial packages which can be installed through COPR.

# Add the .NET SIG repository
sudo dnf copr enable @dotnet-sig/dotnet

# Install .NET Core SDK
sudo dnf install dotnet-sdk-2.0

# Install .NET Core run-time
sudo dnf install dotnet-runtime-2.0

Arch

.Net Core is most easily installed through AUR.

# Install latest .Net Core runtime
yaourt dotnet

# Install .NET Core SDK
yaourt dotnet-sdk-2.0

Setting up a 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.

More detailed instructions for installing SQL Server locally can be found here To install the mssql-server Package on Ubuntu, follow these steps:

Install tools that are necssary for installing Microsoft SQL Server:

sudo apt-get install curl

Import the public repository GPG keys:

curl https://packages.microsoft.com/keys/microsoft.asc | sudo apt-key add -

Register the Microsoft SQL Server Ubuntu repository:

curl https://packages.microsoft.com/config/ubuntu/16.04/mssql-server.list | sudo tee /etc/apt/sources.list.d/mssql-server.list

Run the following commands to install SQL Server:

sudo apt-get update
sudo apt-get install -y mssql-server

After the package installation finishes, run mssql-conf setup and follow the prompts. Make sure to specify a strong password for the SA account (Minimum length 8 characters, including uppercase and lowercase letters, base 10 digits and/or non-alphanumeric symbols).

sudo /opt/mssql/bin/mssql-conf setup

Once the configuration is done, verify that the service is running:

systemctl status mssql-server

Install SQL Server command line tools

You can install the SQL Server commandline tools with the following commands:

curl https://packages.microsoft.com/config/ubuntu/16.04/prod.list | sudo tee /etc/apt/sources.list.d/msprod.list
sudo apt-get update
sudo apt-get install mssql-tools

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 freetrial 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 'allReadyDev'. When creating the database you will create a server for the database as well. Be sure to remember what your servername is as well as the admin account username and password.

After creating the database and server it will be deployed and you will then be able to access it.

Option 3: Run Microsoft SQL Server inside a docker container

The steps to install docker and create a SQL Server container are explained in the MacOSX setup instructions. The steps for Linux are very similar other than the initial installation of docker.

Installing NodeJS and NPM

Ubuntu

NodeJS and NPM can be installed by adding the nodejs PPA and using apt-get. More detailed instructions can be found here

Add nodejs PPA and update apt-get sources

sudo apt-get install python-software-properties
curl -sL https://deb.nodesource.com/setup_6.x | sudo -E bash -
sudo apt-get update

Install nodejs and npm

sudo apt-get install nodejs

Fedora

nodejs is supported in the official Fedora repositories from Fedora 18.x onwards, but packages are horribly out of date and the experience can be described as unstable at best.

# Install nodejs and npm
sudo dnf install nodejs npm

# Update npm to the latest version, as the Fedora repositories often lag behind
sudo npm install -g npm

A better approach is to use nvm (Node Version Manager). NOTE: this assumes you are using bash. Instructions will vary if using zsh/fish/etc

# Install nvm
curl -o- https://raw.githubusercontent.com/creationix/nvm/v0.33.4/install.sh | bash

# Reload shell configuration
source ~/.bashrc

# Install latest node.js
nvm install node

# Install latest npm
npm instal -g npm

Arch

The official Arch repositories are kept up to date with the latest node.js and npm releases

sudo pacman -S nodejs npm

Building allReady

Get the code

To set up the allReady development environment you will need to get the code from github. If you plan to contribute to allReady you should first fork the repository so that you have your own personal copy of the codebase to work with.

If you do not have git installed, you can install git with:

sudo apt-get install git

Once forked, you can clone the repository by typing:

git clone https://github.com/<Your Username>/allReady.git

Buidling the Web-app

After getting the code you can begin by building AllReadyApp.Core.

cd AllReadyApp/AllReadyApp.Core
dotnet restore
dotnet build

Then build the webapp:

cd ../Web-App/AllReady
dotnet restore
dotnet build

Setup the DB hosted locally

The connection string to the database needs to be tweaked in order to point at our SQL Server database.

Note that SQL Server on Linux doesn't have integrated security, so you will need to create and specify a user to login to the DB with.

To log into the Server Admin account (SA) use the password that you created when you installed SQL Server and ran the setup script.

If you set up SQL Server for Linux, run the sqlcmd program and create a login and a user and give that user CREATE DATABASE permissions:

/opt/mssql-tools/bin/sqlcmd -U SA 
1> create login AllReadyAdmin with password = 'p4ssw0rd!';
2> go
1> create user AllReadyAdmin for login AllReadyAdmin;
2> go
1> grant create database to AllReadyAdmin;
2> go
1> exit

Next cd into the allready/AllReadyApp/Web-App/Allready directory.
Create a file locally called appsettings.Development.json containing:

{
  "Data": {
    "DefaultConnection": {
      "ConnectionString": "Server=localhost;Database=AllReady;User ID=AllReadyAdmin;Password=p4ssw0rd!;MultipleActiveResultsets=true;"
    },
    "HangfireConnection": {
      "ConnectionString": "Server=localhost;Database=AllReady;User ID=AllReadyAdmin;Password=p4ssw0rd!;MultipleActiveResultsets=true;"
    }
  }
}

Note we're using the Development environment so we'll need to prefix our commands with ASPNETCORE_ENVIRONMENT=Development

Setup the DB hosted using an external SQL Server instance

While in allready/AllReadyApp/Web-App/Allready, create a file named appsettings.Development.json and update the following lines with the relevant connection strings for your SQL Server instance:

  "Data": {
    "DefaultConnection": {
      "ConnectionString": "Server=<location of azure server>;Database=AllReadyDev;User ID=<AdminLogin>;Password=<AdminPassword>;MultipleActiveResultsets=true;"
    },
    "HangfireConnection": {
      "ConnectionString": "Server=<location of azure server>;Database=AllReadyDev;User ID=<AdminLogin>;Password=<AdminPassword>;MultipleActiveResultsets=true;"
    },

Note we're using the Development environment so we'll need to prefix our commands with ASPNETCORE_ENVIRONMENT=Development

If you are using SQL Azure, be sure to also add a rule to the firewall settings for your SQL Azure instance to allow the IP address of your development machine.

Building NPM packages

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

npm install

Running the web-app

Now, 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.

Troubleshooting

Central Standard Time issue

If you are getting errors such as:

The time zone ID 'Central Standard Time' was not found on the local computer.

then try running a find and replace on the code, with Central Standard Time being replaced to GMT. This is just a temporary fix until the main repo is updated to resolve this issue.

Bad CSS

If your front-end dependencies seem mangled, from within the ./AllReadyApp/Web-App/AllReady/:

npm install

Errors and exceptions stating 'The keyword 'integrated security' is not supported on this platform.'

Be sure that when you try to run the web application from the command line you prefix all commands with ASPNETCORE_ENVIRONMENT=Development so that your appsettings.Development.json file is read and loaded. In that file the credentials that you supplied are used to connect to the database which is required when accessing a SQL server DB from linux.