===== How to Rails ======
Starten met een Rails-project kan wat verwarrend zijn als je dit nog nooit eerder gedaan hebt. Dit artikel bevat een overzicht tot de benodigde software en de stappen waarin je deze best installeert.


===== 1. Ruby =====

==== Mac & Linux ====
Rails is een Ruby web framework en vereist dan ook een Ruby installatie. Omdat verschillende projecten verschillende Ruby versies kunnen gebruiken is het handig meerdere Ruby versies naast elkaar te kunnen draaien. Wij raden [[https://github.com/sstephenson/rbenv|rbenv]] aan aangezien het een stuk eenvoudiger (en probleemlozer werkt) dan rvm. Rbenv installeer je op de volgende manier:

  * Mac OSX: Via brew: [[https://github.com/sstephenson/rbenv#homebrew-on-mac-os-x|handleiding]]
  * Linux: Via je favoriete package manager (rbenv) of via rechtstreeks via Github (zie [[https://github.com/sstephenson/rbenv#basic-github-checkout|rbenv#basic-github-checkout]])

Op beide platformen moet rbenv worden opgestart bij het openen van de shell, dit kan op de volgende manier (vervang ''.bash_profile'' door je favoriete shell zijn profile of rc):
<code>echo 'eval "$(rbenv init -)"' >> ~/.bash_profile</code>

Na installatie en herladen van de shell zou ''type rbenv'' ''rbenv is a function'' of iets dergelijks moeten geven.

Het installeren van een nieuwe Ruby versie kan aan de hand van ''rbenv install [versie]'' (bv. ''rbenv install 2.2.2''). De volledige lijst van mogelijke versies kan bekomen worden aan de hand van het commando ''rbenv install -l''.

Rbenv zal normaal de globaal ingestelde Ruby versie gebruiken, tenzij de gebruiker (of het project) een andere versie specifieert door middel van een ''.ruby-version'' bestand met daarin het versienummer. Dit laatste kan door ''rbenv shell [versie]'' worden overschreven voor de huidige shell sessie. De globale Ruby versie kan worden aangepast door ''rbenv global [version]''.

Sommige Ruby versions kunnen bij het builden beginnen klagen over het niet gedefinieerd zijn van `SSLv3_method`. De fix hiervoor kan men vinden op de [[https://wiki.archlinux.org/index.php/Rbenv#Troubleshooting |Arch wiki]].

==== Windows ====
Rbenv op Windows wordt niet gedaan, de installatie van Ruby kan via [[http://rubyinstaller.org/|RubyInstaller for Windows]].

===== 2. Bundler =====
Net zoals rbenv de versie van je Rails project beheert, beheert Bundler per project de verschillende versies van dependencies en gems. Wanneer bijvoorbeeld twee verschillende projecten twee verschillende versies van dezelfde gem gebruiken, zorgt Bundler dat deze netjes naast elkaar kunnen gebruikt worden.

Installatie van Bundler is zo simpel als ''gem instal --user-install bundler''. Houd er rekening mee dat geïnstalleerde gems afhankelijk zijn van de door rbenv geactiveerde Ruby, het kan dus zijn dat je dit commando opnieuw moet uitvoeren na het installeren van een nieuwe Ruby versie.

Gems worden per project gespecifieerd in de ''Gemfile''. Meer informatie over deze Gemfile kan [[http://bundler.io/v1.5/gemfile.html|hier]] worden verkregen.

===== 3. Projecten =====
Wanneer je een werkende rbenv en bundler setup hebt kan je beginnen aan een project:

  - Clone hiervoor eerst de repository van Git,
  - Controleer of de versie gespecifieerd in ''.ruby-version'' lokaal geïnstalleerd is,
  - Installeer die versie wanneer dit niet het geval is,
  - Installeer via ''bundle install --without production'' de benodigde dependencies uit de Gemfile,
  - Voer ''bundle exec rake db:setup'' uit om het databankschema en de seeds in te laden,
  - Start de Rails server in development op via ''rails s'',
  - Nagiveer in je browser naar ''localhost:3000''.

Wanneer bij stap 4 fouten optreden is dit waarschijnlijk omdat de gem een system library nodig heeft, vaak voorkomende zijn:

^ Gem ^ System dependency ^
| Nokogiri | zlib1g-dev |
| Rmagick | imagemagick |

===== 4. Deployment =====
Wanneer wijzigingen zijn gemaakt wil je die natuurlijk ook op de server zetten. Hiervoor gebruiken we [[https://github.com/capistrano/capistrano|Capistrano]]. Capistrano is een deployment tool die alle commando's vanaf je computer via SSH op de server uitvoert. Dit zorgt ervoor dat je niet op de server zelf moet inloggen om nieuwe wijzigingen online te zetten en verlaagt de kans op fouten. Deployen kan simpelweg via het commando ''cap production deploy''. Na het deployen worden nodige services herstart, zodat de wijzigingen meteen live staan.

Capistrano zet de applicatie in ''production/current''. Oude releases zijn beschikbaar in submappen onder ''production''. Mocht er een bug optreden in een nieuwe release kan je via Capistrano gemakkelijk terug naar een oude versie van de code via het commando ''cap production deploy:rollback''.

Als de delayed-job queue (onder andere gebruikt in FK-enrolment) stilvalt, dan kan deze herstart worden met ''cap production delayed_job:restart''.

Aangezien alle commando's via ssh worden uitgevoerd dien je toegang te hebben tot de server. Hiervoor werken we via ssh-keys. Als je toegang wil om een bepaalde applicatie te deployen kan je terecht bij admin@zeus.ugent.be met de naam van de applicatie, waarom je toegang wil en je public key.

===== 5. Debugging =====
Vaak gaat het eens mis, en dan is het belangrijk dat je live op de server kan debuggen. Rails biedt hier enkele handige tools voor aan, zoals de [[http://guides.rubyonrails.org/command_line.html#rails-console|Rails console]]. De Rails console laat je toe om met je Rails applicatie om te gaan vanaf de command line. Het is mogelijk om modellen en variabelen op te vragen, methodes op objecten uit te voeren, etc. Dit zorgt ervoor dat je (normaalgezien) nooit rechtstreeks met de databank moet prutsen om data terug in orde te krijgen en verlaagt de kans op fouten en inconsistenties. De Rails console kan je openen op de server via het commando ''bundle exec rails c production'' in de ''production/current'' folder. 

Logbestanden van de webserver zijn terug te vinden in de ''log/access.log'' en ''log/error.log'' bestanden. De Rails log staat in ''production/current/log/production.log''.

===== Optioneel =====

==== CAS-integratie ===
Enkele applicaties zoals FK-Enrolment en Gandalf steunen op CAS-integratie. Aangezien DICT de toelating voor ''localhost:3000'' gedisablet heeft is wat meer werk nodig om deze lokaal werkend te krijgen. Kort gezegd moet het adres van de applicatie overeenkomen met wat in DICT hun databank staat. Om te kunnen integreren met CAS moet je voor deze applicaties de volgende stappen volgen:

  - Voeg in ''/etc/hosts'' de volgende lijn toe: ''127.0.0.1 [url]'' waarbij [url] het bijhorende URL bevat in onderstaande tabel,
  - Wanneer dit niet het geval is, start de Rails server op ''127.0.0.1'' via ''rails s -b 127.0.0.1'' (sommige Rails webservers starten de applicatie op ''localhost'' ipv ''127.0.0.1'' wat niet zal werken),
  - Surf naar ''[url]:3000''.

Je browser zal nu het url opzoeken en in je ''/etc/hosts'' file zien dat dit hoort bij localhost, zodat je op je lokale Rails server terecht komt. Aangezien onderstaande URLs geregistreerd zijn bij DICT zullen die ook worden toegelaten en kan je zo de CAS-integratie gebruiken.

^ Project ^ CAS-url ^
| Gandalf | dev.event.fkgent.be |
| FK-Enrolment | dev.registratie.fkgent.be |