Rekstrarhandbók

Vorönn 2017 T-404-LOKA, Lokaverkefni Rekstrarhandbók Ingþór Birkir Árnason Jan Hinrik Hansen Logi Guðmann Þorgrímur Jónasarson Kennari: Hallgrímur Arnalds Leiðbeinandi: Sigurjón Ingi Garðarsson Prófdómari: Símon Óttar Vésteinsson 12. maí 2017 Efnisyfirlit 1 Framendi 3 1.1 Dependencies 3 1.2 Uppsetning 3 1.3 Keyrsla 3 1.4 ESLint 4 1.5 Stílar 5 1.5.1 BEM - Block Element Modifier 5 1.5.2 StyleLint 5 1.5.3 Gulp task 5 2 Bakendi 6 2.1 Dependencies 6 2.2 Uppsetning 6 2.3 Handhægar upplýsingar 8 2.3.1 Admin aðgangur 8 2.3.2 Postman 8 2.4 PHPUnit 8 2.5 Documentation 9 3 Forritunarreglur 9 3.1 Almennar reglur 9 3.2 VueJS 9 3.3 CSS 10 3.4 PHP - Laravel 11 2 1 Framendi Framendinn er skrifaður í Vue.js með vue-webpack-boilerplate (https://github.com/vuejs-templates/webpack) sem grunn. 1.1 Dependencies Til þess að geta keyrt framendann er nauðsynlegt að hafa node og node package manager (npm). Hægt er að sækja node.js ásamt npm á Node.js heimasíðunni (https://nodejs.org/en/). 1.2 Uppsetning 1.) Sækja git repository-ið. git clone https://github.com/toggi737/Lokaverkefni_vue.git 2.) Setja upp nauðsynleg dependencies í gegnum npm. npm install 3.) Búa til dev.env.js skrá sem að inniheldur stillingar fyrir þína vél. Nauðsynlegt er að búa til dev.env.js skrá undir config möppunni sem að inniheldur upplýsingar um þann API sem að þú vilt nota. Það er hægt að gera með því að keyra cp dev.env.js.example dev.env.js í config möppunni. Hér má sjá dæmi um skránna ef nota á production API-inn. var merge = require('webpack-merge') var prodEnv = require('./prod.env') module.exports = merge(prodEnv, { NODE_ENV: '"development"', API: '"https://api.dagbokin.is/v1"', }); 3 Passa þarf upp á að hafa bæði einfaldar og tvöfaldar gæsalappir utan um API strenginn eins og sjá má hér fyrir ofan. 1.3 Keyrsla Eftir þessi skref hér að ofan ætti framendinn að vera tilbúinn til keyrslu. Til þess að keyra framendann upp í development mode má keyra npm run dev Þá ætti framendinn að opnast í vafra á vélinni þinni með URL-ið http://localhost:8080 Til þess að build-a framendann fyrir production er svo hægt að keyra npm run build 1.4 ESLint Kerfið kemur með ESLint config-i sem að passar upp á að JavaScript kóði sé alltaf með sama stílnum. Config-ið sem er í notkun byggir á eslint configi frá Sindre Sorhus sem að kallast xo https://github.com/sindresorhus/eslint-config-xo, en er þó með örlitlum breytingum. Hægt er að setja upp ESLint plugin í mörgum editorum sem að sýnir manni villu um leið og maður brýtur einhverja reglu, en einnig failar build-ið og birtast skilaboð í vafranum, sé einhver regla brotin. Hentugt getur verið að slökkva á eslint í ákveðnum file eða línu á meðan maður er að forrita, en forðast skal að push-a því inn á master. Til þess að slökkva á eslint í heilum file má bæta við /* eslint-disable */ efst í viðkomandi file. Til þess að slökkva á eslint í .vue skrá skal þessi lína vera sett efst í <script> tag-ið. Til þess að slökkva á eslint í ákveðinni línu er hægt að bæta við // eslint-disable-line 4 aftast í línuna. Til þess að keyra ESLint á alla JavaScriptu í projectinu er einnig hægt að keyra npm run lint í skelinni í rótinni á projectinu. 5 1.5 Stílar Flestallir stílar í kerfinu eru skrifaðir í SASS með SCSS syntax. Undir src/styles möppunni má finna skránna theme.scss þar sem öll import fyrir aðra stíla skulu vera. Stílar fyrir hvern component skulu svo vera í sér skrá samhliða .vue skránni fyrir þann component. 1.5.1 BEM - Block Element Modifier Stílar í kerfinu skulu vera skrifaðir með BEM hefðinni. Hægt er að lesa um BEM á heimasíðunni þeirra http://getbem.com/. Þetta hjálpar meðal annars til við endurnýtingu á stílum. 1.5.2 StyleLint StyleLint er í notkun á projectinu til að passa upp á að format á stílum sé alltaf eins. Config-ið sem er í noktun byggir á config-i sem að kallast stylelint-config-standard https://github.com/stylelint/stylelint-config-standard, en töluverðar breytingar hafa verið gerðar á því. Við bættum einnig við plugin-i á StyleLint sem að kallast stylelint-order og passar upp á röðun á CSS property-unum, en við stilltum röðunina á property-unum sjálfir. Til þess að keyra StyleLint á alla stíla í projectinu er hægt að keyra npm run lint:scss í skelinni í rótinni á projectinu. Einnig er hægt að setja upp StyleLint plugin í mörgum editorum sem að kvartar um leið og maður brýtur einhverja reglu. 1.5.3 Gulp task Til þess að auðvelda manni að fylgja öllum þessum stylelint reglum bjuggum við til gulp task sem að lagar allar helstu villurnar fyrir mann. Einnig raðar það CSS property-unum upp í rétta röð. Til þess að geta keyrt þetta task er nauðsynlegt að hafa gulp uppsett á vélinni, en það er hægt að sækja gulp með því að keyra npm install gulp -g 6 Til þess að keyra taskið má svo keyra gulp styles í rótinni á projectinu, en þetta keyrir á alla stíla í projectinu. Einnig er hægt að senda inn færibreyturnar stylesSrc og stylesDest til þess að keyra taskið á staka file-a eða ákveðnar möppur. gulp styles --stylesSrc 'src/components/auth/*.scss' --stylesDest 'src/components/auth' 2 Bakendi Bakendinn er skrifaður í Laravel 5.4, með apiato pakkann (http://apiato.io) sem grunn. 2.1 Dependencies Hér má sjá lista yfir þau forrit og pakka sem að þurfa að vera til staðar til þess að setja upp bakendann. ● PHP 7.1 ● Composer ● Nginx eða Apache ● MySql ● Sqlite3 fyrir phpunit test Leiðbeiningar um uppsetningu á þessum tólum má finna á netinu. Einnig er hægt að nýta sér Docker með Laradock eða Vagrant með Laravel Homestead, en það eru pakkar/virtual vélar sem að koma með öllum þessum dependencies uppsettum. 2.2 Uppsetning Leiðbeiningar um uppsetningu má nálgast hér http://apiato.io/A.getting-started/installation. Þarna inni má einnig finna kafla um uppsetningu í gegnum Docker og Vagrant. Eftir að hafa sett upp öll dependencies þarf að fylgja eftirfarandi skrefum til þess að setja upp bakendann. 1.) Sækja git repository-ið. git clone https://github.com/toggi737/Lokaverkefni_hello.git 7 2.) Setja upp nauðsynleg dependencies í gegnum composer. composer install 3.) Búa til gagnagrunn fyrir kerfið í MySQL. Það er til dæmis hægt að gera með því að keyra eftirfarandi skipun í MySQL skelinni. create database dagbokin; Eða með því að keyra mysql -u root -p -e "create database dagbokin;" í skelinni. 4.) Búa til .env skrá sem að inniheldur stillingar fyrir þína vél. Gott er að byrja á því að afrita example .env skránna með því að keyra cp .env.example .env Því næst þarf að opna .env skránna og fylla út helstu stillingar. Hér fyrir neðan má sjá lista yfir helstu atriðin sem að gæti þurft að stilla til. Nafn á kerfinu ásamt url-um. Url-in geta verið mismunandi eftir uppsetningu á local umhverfi. APP_NAME="dagbokin" APP_URL=http://dagbokin.dev API_URL=http://api.dagbokin.dev (Í sumum tilfellum þarf að eiga við ‘hosts’ skránna í stýrikerfinu til þess að benda þessum URL-um yfir á localhost (127.0.0.1)). Upplýsingar um gagnagrunnstengingu. Þessar upplýsingar þurfa að vera í samræmi við MySQL gagnagrunninn á þinni vél. DB_HOST=localhost DB_PORT=3306 DB_DATABASE=dagbokin DB_USERNAME=root 8 DB_PASSWORD=root Einnig þarf APP_KEY að vera til staðar í skránni, en hann má fá með því að keyra php artisan key:generate í skelinni. 4.) Setja upp gagnagrunn. Til þess að setja upp töflur í gagnagrunninum þarf að keyra php artisan migrate Til þess að fá inn nauðsynleg gögn í gagnagrunninn, eins og til dæmis Admin userinn má keyra php artisan db:seed Ef að þú vilt fá inn demo gögn í kerfið má keyra php artisan apiato:seed-test 9 5.) Setja upp OAuth Til þess að innskráning og fleira virki rétt í kerfinu þarf að setja upp OAuth encryption keys, og clients, sem eru svo notaðir til þess að búa til access tokens. Þetta má gera með því að keyra php artisan passport:install Eftir þessi skref ætti kerfið að vera tilbúið til keyrslu. Áður en að hafist er handa að vinna í bakendanum er mjög gagnlegt að lesa í gegnum Porto hönnunarmynstrið, en það má finna hér https://github.com/Mahmoudz/Porto. Einnig má finna ýmsar upplýsingar um uppbyggingu á kerfinu og fleira hér http://apiato.io/. 2.3 Handhægar upplýsingar 2.3.1 Admin aðgangur Default admin username og password á kerfinu eftir uppsetningu er username: [email protected] password: gunnasig 2.3.2 Postman Gott er að nota Postman tólið (https://www.getpostman.com/) til þess að senda requestur á bakendann. 2.4 PHPUnit Til þess að keyra öll test fyrir bakendann má keyra vendor/bin/phpunit í rótinni á repository-inu. Einnig er hægt að filter-a test út frá nafni með því að keyra vendor/bin/phpunit --filter TestName 10 2.5 Documentation Öll skjölun um endapunkta er geymd samhliða PHP kóðanum fyrir viðeigandi endapunkt. Til þess að búa til documentation síðu út frá þeim gögnum, notum við tól sem að heitir apiDoc. Það er node pakki og má setja upp í gegnum node package manager (npm) með því að keyra npm install apidoc -g Til þess að búa svo til skjölunarsíðuna er hægt að keyra php artisan apiato:docs Þar má finna upplýsingar um alla endapunkta í kerfinu ásamt öðrum handhægum upplýsingum fyrir þá sem þurf að nota api-inn.

Load more