LS Retail - Rauntímaeftirlit með bensínstöðvum

Rekstrarhandbók

Vor 2016

B.Sc. Tölvunarfræði

Arnar Dóri Ásgeirsson Ásgeir Daði Þórisson Hafþór Snær Þórsson Sigurður Már Atlason

Leiðbeinandi: Hannes Pétursson T-404-LOKA Prófdómari: Hlynur Sigurþórsson Lokaverkefni, vor 2016

Efnisyfirlit

Contents Efnisyfirlit ................................................................................................................................... 2

1. Back End - Web API - (C# ASP.NET) .................................................................................... 3

1.1 Almennt: ........................................................................................................................... 3

1.2 Web API og SignalR ......................................................................................................... 3

1.2.1 Uppsetning: ................................................................................................................ 3

1.3 Listener Service ................................................................................................................ 8

2. Front End - Web Client - (AngularJS) ..................................................................................... 9

2.1 Tengja framenda við API og SignalR ...............................................................................10

3. Database (Microsoft SQL Server) .........................................................................................11

4. Aðrar þjónustur .....................................................................................................................13

4.1 RabbitMQ ........................................................................................................................13

4.2 Jenkins (Continuous Integration) - optional ......................................................................14

1. Back End - Web API - (C# ASP.NET)

1.1 Almennt:

● Bakendi verkefnisins er skrifaður í ASP.NET umhverfinu frá Microsoft.

○ Target framework er .NET v. 4.5.2 og skal það sett upp á servernum.

● Verkefnið skal hýsa á IIS server (Internet Information Services).

○ Í Þróun verkefnisins var notast við útgáfu 8.5 á Windows Server 2012 R2, sem á

þeim tíma var nýjasta útgáfa þess. Aðrar útgáfur voru ekki prófaðar.

● Setja þarf upp tvær vefsíður (Web API og SignalR) og svo eina windows service.

1.2 Web API og SignalR

1.2.1 Uppsetning:

Visual studio solutionið inniheldur tvö project sem hýsa þarf á IIS. Í fyrsta lagi

LSForecourtHealth projectið sjálft (API) og hinsvegar SignlarR. SignalR er endapunktur fyrir

framenda verkefnisins til að taka við skilaboðum frá bakenda. Bæði þessi project innihalda

Publish profile (undir nafninu “DevProfile.pubxml” sem hægt er að nýta, en þeir prófílar build-a

verkefnið inn á File System undir “C:\inetpub\wwwroot\forecourt” og

“C:\inetpub\wwwroot\signalr” en hægt er að breyta þeirri slóð eða setja upp nýja Publish Prófíla

til að publisha t.d. í gegnum Web deploy eða Azure (ef sú þjónusta væri nýtt).

1.2.1.1 Build

1. Sækja þarf Solutionið LSForecourtHealth af https://bitbucket.org/ls-lokaverkefni/ls-

forecourt-health-api .

Clone-a skal verkefnið eða hlaða niður í zip.

2. Setja upp verkefnið - mögulega þarf að fara í ‘Build -> Clean’ og svo ‘Build -> Rebuild’ ef

upp kemur villa í fyrstu keyrslu. Þetta lætur Visual Studio fara yfir og sækja alla NuGet

pakka með verkefninu sem nauðsynlegir eru fyrir verkefnið.

3. Project dependency (hægri smellt á solution inni í VS -> Project Dependencies) - ætti að

koma sjálfgefið

a. LSForecourtHealth -> LSForecourtHealth.Models og LSForecourtHealth.Services

b. LSForecourtHealth.Services -> LSForecourtHealth.Models

c. LSForecourtHealth.Tests -> LSForecourtHealth, LSForecourtHealth.Models og

. LSForecourtHealth.Services

4. Hægri smella á LSForecourtHealth projectið (web api hlutinn) og velja publish.

5. Hér er hægt að nýta núverandi profile. Hann smíðar verkefnið á File system á slóðina

‘C:\inetpub\wwwroot\forecourt’.

6. Hægt er að búa til nýjan profile (eða breyta núverand) ef breyta á aðgerðinni.

7. Endurtaka skref 4 til 6 fyrir SignalR projectið.

1.2.1.2. IIS server

1. Hægri smelltu á Sites og veldu Add Website

2. Settu inn eftirfarandi stillingar (ath. Velja skal sama Physical path og valið var í Visual

Studio). IP tölur eru að sjálfsögðu aðrar.

3. Endurtaka skref 1-2 fyrir SignlarR

API verkefnið var hýst á porti 9090 og SignalR á porti 9091.

Hægt er að breyta þeim stillingum, eða setja upp undir lén.

1.3 Listener Service

Listener service projectið má nálgast hér:

https://bitbucket.org/ls-lokaverkefni/ls-forecourt-health-listener-service

Verkefnið er, sem stendur, consoler application og þarf að keyra það upp handvirkt.

Næsta verkefni fyrir þetta forrit er að byggja það upp sem þjónustu sem hægt er að keyra sem

Windows Service

Hægt er að publish-a verkefninu og fá þá setup process. Einnig er hægt (eftir að hafa buildað

verkefnið og keyrt upp) að fara í möppu verkefnisins:

ls-forecourt-health-listener-service\LSForecourtHealth_Listener\bin\Debug

Þar má finna LSForecourtHealth_Listener.exe sem er hægt að keyra upp - í stað þess að

keyra í gegnum Visual Studio.

Ath: Nauðsynlegt er að breyta eftirfarandi línu í rétta slóð á API serverinn.

Þessi stilling bendir (á þessari mynd) á localhost ef keyra á API upp á sömu vél í þrónu.

_apiEndPoint = new Uri("YOUR_NEW_API_URL/api/notifications/");

ATH: Þessi þjónusta var unninn á síðustu metrum í þróunarferlinu og því er ekki búið að

villuprófa hann að fullu. Möguleiki er að einhverjar villur komi upp við keyrslu, þ.e. ef koma upp

villur við að tengjast SQL servernum eða stillingar á honum séu ekki rétt uppsettar (sjá kafla 3).

Þá ætti að duga að ræsa forritið aftur.

2. Front End - Web Client - (AngularJS)

Framendi þessa verkefnis er byggður með Angular JS frameworkinu fyrir JavaScript.

Innihald þess verkefnis sem þarf að hýsa er eingöngu HTML, CSS og JavaScript. Flestir ef ekki allir

HTTP Serverar eru færir í það og er því nánast valfrjálst á hvers konar server það er hýst. Hægt er

að setja það upp á IIS server eða hýsa með t.d. Debian eða Ubuntu. Fyrir okkar demo notuðum við

GitHub pages. Í Grunt file-num má finna scriptu sem deployar á gh-pages branch.

Sækja má verkefnið hér:

https://bitbucket.org/ls-lokaverkefni/ls-forecourt-health

Til þess að build-a verkefnið fyrir production, þarf eingöngu að keyra ‘grunt’ skipunina í rót

verkefnisins (cmd eða bash). Þá verður til Dist mappa. Þessi mappa inniheldur minified og uglfied

kóða og aðra nauðsynlega file-a sem þarf að hýsa. Ef hýsa á verkefnið á IIS server þá skal benda á

index.html skránna í þeirri möppu.

Ítarlegri lýsingu fyrir uppsetningu (sem þarf að gera til að geta build-að verkefnið)má finna í

README.md skjali sem fylgir verkefninu.

2.1 Tengja framenda við API og SignalR

Til þess að framendinn tengist við API þjónustuna þarf að breyta þremur slóðum.

Fyrsta slóðin er undir ls-forecourt-health/app/index.html

Þessi slóð á að vera slóðin sem valin var fyrir signalr endapunktinn (sjá kafla 1.2)

<script type="text/javascript" src="http://YOUR_NEW_SIGNALR_URL/signalr/hubs"></script>

Næstu tvær slóðir eru í sama skjalinu, undir ls-forecourt-health/app/scripts/app.js

Þarna skal breyta SERVER_PATH og SIGNALR_PATH með nýju Url-i eða IP tölu.

'SERVER_PATH': 'http://YOUR_NEW_API_URL/',

'SIGNALR_PATH': 'http://YOUR_NEW_SIGNALR_URL/signalr'

Ath að þarna eru commentuð út localhost slóðir ef keyra á upp fram- og bakenda locally á sömu

vél í þróun. Þessi port eru skilgreind í API projecti og því óþarfi að breyta þeim (en má fjarlægja

áður en framendi er settur upp í production).

3. Database (Microsoft SQL Server)

Database serverinn í verkefninu er Microsoft SQL server 2014.

Tengistrengur á gagnagrunninn (hægt að stilla í visual projecti eða á IIS servernum):

● <add name="MockDatabase" providerName="System.Data.SqlClient"

connectionString="Data Source=SKOFLUNGUR.LSRETAIL.LOCAL;Initial

Catalog=MockDatabase;Integrated Security=False;User

Id=sql_user_haffi;Password=.,rosaleguradmin;MultipleActiveResultSets=True" />

● Hægt er að breyta notenda og lykilorði. Notandi þarf að hafa réttindi til þess að lesa og

skrifa í töflur.

Nauðsynlegar töflur:

● ALARM_LOG

● ALARM_STATUS

● ALARM_TYPE

● Asp user tables (if Microsoft Owin security is used)

○ AspNetRoles

○ AspNetUserClaims

○ AspNetUserLogins

○ AspNetUserRoles

○ AspNetUsers

● PRODUCTS

● PUMPS

● STATION_HEALTH

● STATIONS

● TANK_LOG

● TANK_STATUS

● TANKS

● USER_SETTINGS

● USER_STATIONS

Sjá meðfylgjandi SQL skjal sem inniheldur Create scriptur og foreign keys fyrir þessar töflur.

Þá er einnig meðfylgjandi sql skjöl sem innihalda uppsetningar á triggerum og stored

procedures í þessum töflum.

Mynd af tölfum á SQL server - tengingar milli tafla

4. Aðrar þjónustur

4.1 RabbitMQ

Rabbitmq er message queue þjóunsta sem auðveldar samskipti milli mismunandi þjónusta.

Rabbitmq er notað í þessu verkefni til þess að tryggja ‘reliable’ skilaboðaþjónustu.

Í þróun verkefnisins var queue-in keyrð á windows vél, raunar þeirri sömu og hýsti IIS verkefnið.

En til að dreifa álagi getur verið nauðsynlegt að keyra hana á sér vél. Hægt er að keyra hana á

Windows eða Unix umhverfi.

Keyra þarf upp RabbitMQ service (sem má sækja hér:

https://www.rabbitmq.com/download.html).

Gott getur verið að enable-a Management plugin (sem kemur með þjónustunni, en disabled by

default) með því að keyra (í innstal möppunni undir sbin) rabbitmq-plugins enable rabbitmq_management

Með managment plugin sett upp er hægt að fara inn á localhost:15672 til að fá upp vef viðmót

með yfirliti og stillingum fyrir þjónustuna. Þar er hægt að setja upp nýjar queue, routing-key og

exchange-a sem og að sjá fjölda skilaboða í queue, sækja skilaboð og fleira.

Nánari leiðbeiningar fyrir RabbitMQ uppsetningu má finna hér fyrir windows:

https://www.rabbitmq.com/install-windows.html (með binary file-um)

https://www.rabbitmq.com/install-windows-manual.html (manual uppsetning)

Og hér fyrir Debian / Ubuntu

https://www.rabbitmq.com/install-debian.html

RabbitMQ notast við Erlang og þarf það að vera sett upp vélinni.

Hægt er að sækja Erlang hér: http://www.erlang.org/downloads (sjá nánar í install

leiðbeinginum á rabbitmq.com)

4.2 Jenkins (Continuous Integration) - optional

Í þróun verkefnisins var notast við continuous intagreation tólið Jenksins. Tólið hentaði vel þar

sem kóðinn var hýstur á BitBucket með GIT. Jenkins og BitBucket bjóða upp á ýmis tól tengt

hvort öðru til að auðvelda samskipti þar á milli. Jenkins var sett upp á Windows, sömu vél og IIS

serverinn á meðan þróun stóð yfir, en einnig er hægt að hafa Jenkins á sér vél, hýst á Windows

eða Unix.

Jenkins er hægt að sækja hér: https://jenkins.io/

Leiðbeiningar fyrir uppsetningu má nálgast hér fyrir Windows: https://wiki.jenkins-

ci.org/display/JENKINS/Installing+Jenkins+as+a+Windows+service

Og hér fyrir Unix kerfi (velja viðeigandi distro):

https://wiki.jenkins-ci.org/display/JENKINS/Installing+Jenkins

Uppsett plugins fyrir Jenkins:

● BitBucket Plugin (með webhook á Bitbucket) - optional

● Git plugin

● Git Client plugin

● JUnit plugin (publishar test niðurstöðum á Jenkins)

● MSBuild plugin (til að builda bakenda)

● MSTest plugin (til að integrade-a MSTest við JUnit stuðninginn í Jenkins)

● MSTestRunner plugin (til þess að keyra unit test með MSTest)

● Slack Notification Plugin - optional

Helstu stillingar (undir Manage Jenkins -> Configure Jenkins):

● Git

○ Name: (Má vera hvað sem er)

○ Path to Git executeable: git.exe (að því gefnu að það sé stillt í path á vélinni)

● MSBuild

○ Name: (Má vera hvað sem er)

○ Path to MSBuild: C:\Program Files (x86)\MSBuild\12.0\Bin\amd64\MSBuild.exe

■ Ath, það kemur warning - það er í lagi. Slóð gæti verið önnur.

● MSTest

○ Name: (Má vera hvað sem er)

○ Path to MSTest: C:\Program Files (x86)\Microsoft Visual Studio

12.0\Common7\IDE\MSTest.exe

■ Ath, það kemur warning - það er í lagi. Slóð gæti verið önnur.

● CVS (ssh lyklar svo Jenkins geti sótt kóða af git)

○ Compression level: optional

○ Private Key Location: C:\Windows\system32\config\systemprofile/.ssh/id_rsa

(getur verið hvar sem er)

○ Known Hosts location:

C:\Windows\system32\config\systemprofile/.ssh/known_hosts (getur verið hvar

sem er)

● Global Slack Notifier settings:

( sækja Slack Jenkins CI app: https://slack.com/apps/A0F7VRFKN-jenkins-ci )

○ Team doman: nafnið á hópnum (http://DOMAIN.slack.com)

○ Token: (Finnur það í stillingum á Jenkins appi á Slack)

○ Channel: channel sem þú villt að Jenkins posti á.

○ Build server URL: slóðin sem Jenkins er hýst á.

Helstu stillingar fyrir projectið sjálft:

● Source Code Management:

○ Git

■ Repository URL: Slóðin á bitbucket.

■ Credentials: Gott er að setja upp user á git sem hefur eingögnu lesréttindi

á verkefnið. Hægt er að geyma login og ssh upplýsingar undir Credentials

á Jenkins og velja þann user hér.

■ Branches to build: Branch sem á að builda */master (default) en getur

verið hvað sem er, einnig hægt að bæta við mörgum branches.

■ Hægt að bæta við fleiri stillingum undir Additional Behaviours.

● BUILD (Röð aðgerða til að build-a project. Velja þarf Add build step til að bæta við

aðgerð)

○ Execute Windows batch command

■ Command: .nuget\nuget.exe restore

● (hreinsar nuget pakka og setur upp aftur, ef pakkar skyldu hafa

breyst)

○ Build a Visual Studio project or solution using MSBuild

■ MSBuild version: (nafn á stillingum sem settar voru upp hér fyrir ofan)

■ MSbuild Build field: LSForecourtHealth.sln (Solutionið sem á á að setja

upp)

■ Command Line Aguments:

● /t:Clean

/t:LSForecourtHealth_Models:Rebuild;LSForecourtHealth_Service

s:Rebuild;LSForecourtHealth:Rebuild;LSForecourtHealth_Tests:R

ebuild;LSForecourtHealth_SignalR:Rebuild /p:DeployOnBuild=true

/p:PublishProfile=DevProfile /p:Configuration=Release

■ Pass build variables as properties: (Hakað í)

■ Advanced:

● Continue Job on Build Failure (ekki hakað í)

● If warnings set the build to Unstable (hakað í)

○ Run unit tests with MSTest

■ MsTest version: (nafn á stillingum sem settar voru upp hér fyrir ofan)

■ Test Files:

● LSForecourtHealth.Tests\bin\Release\LSForecourtHealth.Tests.dl

● (slóðin á testin sem á að keyra)

■ Result File name: API_test_results.trx (má vera hvað sem er)

■ Continue on failed tests (ekki hakað í)

● NB: Projectið verður samt sett upp á IIS serverinn þar sem build

stillingarnar eru settar á DeployOnBuild=true. En Projectið verður

FAILED á Jenkins.

● Post-Build Actions

○ Publish MSTest test result report

■ Test report TRX file: API_test_results.trx (nafnið sem valið var hér að

ofan)

○ Fail build if no files are found: (hakað í)

● Slack Notifications

○ (engar færibreytur)

Gott er að setja upp Reverse Proxy fyrir Jenkins svo ekki sé hægt að komast inn á þjónustuna á

utanaðkomandi vélum, en það fer eftir uppsetningu kerfisins.