ls retail - rauntímaeftirlit með bensínstöðvumk.pdfhægt er að publish-a verkefninu og fá...
TRANSCRIPT
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.