Tässä oppaassa kerrotaan kuinka saadaan määritettyä ketju, jonka avulla Github-actionsia käyttäen voidaan kotikoneelta ylläpitää Webhotellissa toimivaa Laravel-sivustoa.

Oppaassa hahmotellaan yleisperiaate, ei niinkään täydellinen malliratkaisu.

Opas jakaantuu seuraaviin vaiheisiin:

• käydään läpi lähtöoletukset
• tehdään alustavat toimenpiteen Web-palvelimella
• avataan uusi GitHub repository
• luodaan kotikoneelle uusi Laravel-projekti
• varmistetaan, että tiedostot saadaan siirrettyä GitHub:iin
• Laravelin asennus palvelimella
• tietokannan asennus palvelimella
• tietokannan asennus omalle koneelle
• tietokanta-asetusten viimeistely palvelimella
• loppusanat

Jokainen toimintaympäristö on erilainen, joten todennäköisesti jossain vaiheessa törmäät ongelmaan, jota oppaan esimerkissä ei käsitelty.

Esimerkiksi itse jouduin loppuvaiheessa, kun palvelimella otetaan käyttöön tietokanta, tekemään muutoksen konfigurointietoihin, mutta en käy tätä muutosta läpi oppaassa, sillä samaa ongelma tuskin koskee kaikkia.

Virheilmoituksen ja Stack Overflow:n avulla ongelma ratkesi sangen nopeasti.

Lähtöoletukset

Oppaan suorittaminen edellyttää, että:

• käytössäsi on cPanelia tukeva Webhotelli
• sinulla on GitHub-tili

Ja, että koneellesin on asennettu:

• Git-versionhallintaohjelmisto
• PHP:tä ja mySql:ää tukeva webpalvelin, esim. Xampp
• PHP:n versionhallintaohjelmisto Composer

Opimaalista olisi, jos kotikoneella ja webpalvelimella on käytössä sama PHP-versio, tällöin molemmille koneille asentuu automaattisesti sama Laravel-versio.

Työn edetessä kannattaa kirjata ylös tietoja, joita tulemme myöhemmissä vaiheissa tarvitsemaan. Muistiinpanot-linkin avulla saat näkyville, mitä tietoja kussakin vaiheessa pitää olla selvillä. Aukeavassa ikkunassa näytetään mallina arvot, joita minä käytin tätä opasta tehdessäni. Sinulla arvot tietekin ovat oman tehtäväsi mukaiset.

Mikäli edellytykset ovat kunnossa, lähdetään liikkeelle suorittamalla cPanel:ssa tarvittavat ennakkovalmistelut.

Takaisin sivun alkuun

cPanel

Luodaan tätä projektia varten kaksi subdomainia.

Toiseen sijoitetaan Laravel-projektin tiedostot. Emme kuitenkaan paljasta tätä domainia kaiken kansan nähtäville, sillä samalla avautuisi yleiseen tietoon myös salaiseksi tarkoitettu .env -tiedosto.

Joten luodaan varsinaiselle julkaisulle oma subdomain, johon luomme myöhemmässä vaiheessa symbolisen linkin esitettävään sisältöön.

Luon projektia varten seuraavat subdomainit:

• graafeja [Julkaisua varten]
• graafitBackend [Laravel:in asennusta varten]

cPanelin pääsivun DOMAINS-välilehdeltä löytyy Subdomains-painike.

Painike avaa Subdomains näkymän, joka sisältää lomakkeen, jonka avulla alidomaineja voidaan lisätä.

Kun subdomainit on lisätty, näkyvät ne Subdomains-sivun alalaidan listalla. (Minulla on jo entuudestaan pari muutakin subdomainia)

Kun lisätään alidomain, niin tässä yhteydessä sille avataan oma hakemisto.

cPanelin etusivun Files-välilehden kautta pääsee tiedostonhallintaan. Käydään varmistamassa, että alidomaineja vastaavat hakemistot ovat olemassa.

public_html hakemistoon on lisätty subdomaineille omat kansionsa.

GitHub actionsin avulla tapahtuvaa päivittämistä varten tarvitaan FTP-tunnus. Luodaan se seuraavaksi. Tallennetaan samalla käyttäjätunnus ja salasana myöhempää käyttöä varten!

Hakemistoksi asetetaan polku Laravel-asennusta varten luotuun subdomainiin!

Kun käyttäjä on luotu, ilmestyy nimi sivun alalaidassa esitettävään FTP-käyttäjien listaan.

Kirjaa ylös lisäämäsi käyttäjätunnus ja salasana! [Muistiinpanot]

Siirrytään alkuvalmisteluissa seuraavaksi Githubin pariin.

Takaisin sivun alkuun

Github

Luodaan tyhjä repository. Huom! Tässä vaiheessa ei lisätä README.md tiedostoa.

Kun repository on luotu, aukeaa näkymä, jossa listataan tyypillisiä vaihtoehtoja, joita tässä vaiheessa tehdään. Kopioidaan talteen seuraava kohta:

…or push an existing repository from the command line
git remote add origin https://github.com/RaimoHaikari/graafeja.git
git branch -M main
git push -u origin main

Huom! Sinulla ensimmäisellä rivillä oleva sanan origin jälkeen lukeva osuus vastaa tietenkin sinun luomasi repositoryn nimeä.

Talletetaan seuraavaksi webhotellin päivittämisen edellyttämät FTP-tiedot. Tämä tapahtuu Actions secrets-asetusten avulla. Pääsemme syöttämään ne kun valitsemme päävalikosta kohdan Settings, jonka jälkeen aukeavan sivun vasemman laidan valikosta valitaan ensin kohta Secrets ja tämän jälkeen alavalinta Actions.

Talletetaan kolme salaisuutta. Muistiinpanot.

• ftp_server (Muistiinpanojen FTP -osoite)
• ftp_username (Muistiinpanojen Käyttäjä)
• ftp_password (Muistiinpanojen Salasana)

Salaisuudet syötetään yksi kerrallaan.

Kun salaisuudet on syötetty, näkyvät ne sivun alalaidan listassa:

GitHub käyttää salaisuuksien nimissä isoja kirjaimia, mutta palvelinta päivittäessämme käytämme tallentamisen yhteydessä käytettyä muotoa.

Takaisin sivun alkuun

Kotikone

Käynnistetään omalla koneella toimiva webpalvelin. Laravelin asennus ei edellytä, että palvelin on päällä, mutta pian sitä tarvitaan.

Laravel-projektin asentaminen edellyttää Composerin käyttöä, joten jos Composer ei ole jo asennettuna, voit ladata sen täältä.

Luodaan uusi Laravel projekti. Nimeksi valitaan edellisessä vaiheessa luodun Github repositoryn nimi.

composer create-project laravel/laravel graafeja

Siirrytään luotuun hakemistoon ja tehdään siitä git-repository

git init

Lisätään tässä vaiheessa kaksi hakemistoa: ensiksi .github ja tämän hakemiston sisään: workflows

workflows hakemiston sisään luodaan actions.yml niminen tiedosto. Tässä tiedostossa määritellään toimenpiteet, jotka GitHub:in halutaan suorittavan.

Projektin juuresta käsi hakemistolistauksen pitäisi näyttää suurin piirtein seuraavalta:

actions.yml tiedoston sisällöksi kopioidaan seuraava json -koodi:

on: 
  push:
    branches: main
name: 🚀 Deploy website on push
jobs:
  web-deploy:
    name: 🎉 Deploy
    runs-on: ubuntu-latest
    steps:
    - name: 🚚 Get latest code
      uses: actions/checkout@v2
    
    - name: 📂 Sync files
      uses: SamKirkland/FTP-Deploy-Action@4.3.1
      with:
        server: ${{ secrets.ftp_server }}
        username: ${{ secrets.ftp_username }}
        password: ${{ secrets.ftp_password }}

Koodi on peräisin osoitteesta: https://github.com/marketplace/actions/ftp-deploy.

Kyseisellä sivulla esitellään automaattista, FTP:n avulla suoritettavaa päivitystä ja listataan tyypillisten käyttötilanteiden malleja.

Huomiota kannattaa kiinnittää koodinpätkän kolmeen viimeiseen riviin:

• secrets.ftp_server
• secrets.ftp_username
• secrets.ftp_password

Ne vastaavat GitHub-repositoryn luomisen yhteydessä tallennettuja salaisuuksia.

Varmistetaan, että Laravelin asennus onnistui. Eli käynnistään kehityspalvelin ja todetaan selaimesta, että projektin oletussivu aukeaa selaimeen:

php artisan serve

Jonkan jälkeen selaimella osoitteesta http://localhost:8000/ pitäisi löytyä uuden Laravel-projektin avausikkuna.

Kaiken pitäisi olla kotikoneella nyt kunnossa ja olemme valmiita tallettamaan tehdyt muutokset GitHub-repositoryyn.

Lisätään tehdyt muutokset committiin:

git add .
git commit -m 'Projektin avaus'

Yhdistetään projekti GitHub repositoryyn:

git remote add origin https://github.com/RaimoHaikari/graafeja.git

Sinulla originin jälkeen tulevan osuuden pitää vastaa omaa repositoryasi!

Pushataan tehdyt muutokset GitHub:iin:

git branch -M main
git push -u origin main

Takaisin sivun alkuun

Github

Ensimmäisen päivityksen jälkeen projektin pääsivulle on ilmestynyt kopio projektin tiedostoista.

Jos kaikki meni hyvin, niin tovin kuluttua Actions -välilehdelle ilmestyy merkintä onnistuneesta ajosta.

Vilkaistaan seuraavaksi miltä cPanelin puolella näyttää.

Takaisin sivun alkuun

cPanel

Jos vilkaisemme cPanelin tiedostolistausta, niin Laravel-tiedostoille varattuun hakemistoon on ilmestynyt koko joukko tiedostoja.

Tämä ei tarkoita vielä sitä, että Laravel-projekti olisi nyt nähtävissä. Vaikka tiedostot ovat jo paikalla, täytyy projekti erikseen asentaa vielä Webpalvelimella.

Se puolestaan edellyttää komentokehotteella tapahtuvaa työskentelyä.

Minulla cPanel:sta löytyy terminal ja aion käyttää sitä seuraavissa toimenpiteissä. Jos cPanel-versio ei sisällä terminaalia, niin samat tehtävät voi hoitaa esim. Putty:n avulla.

Luodaan saman tien symbolinen linkki, jonka kautta Laravel-projekti on tarkoitus tarjota suuren yleisön nähtäville.

Oppaan tapauksessa siirrytään graafeja-hakemistoon ja ajetaan seuraava käskyt:

cd public_html
cd graafeja
cp --symbolic-link ../graafitBackend/public/* .
cp --symbolic-link ../graafitBackend/public/.htaccess .

Kun hakemistossa tämän jälkeen tulostaa laajennetun tiedostolistauksen, pitäisi sen näyttää suunnilleen seuraavalta:

Erinomaisen tärkeää on, että .htaccess -tiedosto näkyy listalla!

Siirrytään seuraavaksi projektikansioon ja ajetaan Composerin asennuskomento.

cd ..
cd graafitBackend
composer install

Kun asennus on valmis, pitää luoda .env -tiedosto. Käytetään apuna asennuksen mukana tulevaa .env.example -tiedostoa:

cp .env.example .env

Luodaan "key":

php artisan key:generate

Jos kaikki on sujunut tähän asti mallikkaasti, niin Laravel-projekti on nyt nähtävissä julkiseksi tarkoitetun subdomainin kautta.

Oppaan tapauksessa projekti on löytyy, kun selaimella menee osoitteeseen: http://graafeja.tahtisadetta.fi

Takaisin sivun alkuun

Tietokanta

On vielä yksi tärkeä tehtävä jäljellä, tietokantaan yhdistäminen. Suoritetaan aluksi Webhotellin päässä tarvittavat alkuvalmistelut.

cPanelin Databases-välilehdeltä pääsee luomaan tietokantoja.

Luodaan projektia varten uusi tietokanta.

Luomisen jälkeen tietokanta ilmestyy sivun alalaidassa esitettävään listaan. (Minulla oli entuudestaan jo pari tietokantaa.)

Luodaan kantaa varten myös uusi käyttäjä.

Kytketään lisätty käyttäjä projektin tietokantaan.

Aukeavassa näkymässä annetaan käyttäjälle täydet oikeudet tietokantaan.

Kirjaa ylös juuri määrittämäsi tiedot. Muistiinpanot

Seuraavaksi tietokantayhteyttä koskevat tiedot on tallennettava .env -tiedostoon.

Minä käytän cPanelin tiedostonhallinnan edit-toimintoa. Tehtävä voidaan hoitaa myös esim. vi-editorilla.

Etsitään tiedostosta tietokantayhteyttä koskeva kohta ja talletetaan luotua tietokantaa ja käyttäjää koskevat tiedot.Muistiinpanot

cPanelin Databases välilehdeltä voi avata phpMyAdmin -ikkunan. Lisätty tietokanta näkyy ikkunassa (toistaiseksi) tyhjänä tietokantana.

Takaisin sivun alkuun

Tietokanta omalla koneella

Palataan omalle koneelle ja luodaan myös sinne tietokanta. Vaiheet ovat samanlaiset kuin juuri äsken tehtiin palvelimella. Kotikoneella ei todennäköisesti ole cPanelia, mutta jos käytössä on Xampp, niin avaamalla selaimeen uusi välilehti ja kirjoittamalla osoitteeksi:

http://localhost/dashboard/

Aukeaa Xampp:in porttaalisivu, jonka oikeassa ylälaidassa on linkki phpMyAdmin.

Linkin takaa aukeaa tuttu SQL-hallintapaneeli.

Tietokanta saadaan luotua esim. klikkaamalla SQL-välilehteä. Ja syöttämällä SQL-komennoille varattuun tilaan:

CREATE DATABASE tahti885_db_graafeja;

ja painamalla GO-painiketta.

Tällä kertaa luon omalle koneelle samanlaisilla asetuksilla tietokannan käyttäjineen kuin edellisessä vaiheessa tein palvelimelle.

Mutta sinänsä omalla koneella ja palvelimella olevien tietokanta-asetusten ei tarvitse olla identtisiä, sillä Laravel-instanssin käyttämän .env -tiedoston sisältö ratkaisee kulloinkin voimassa olevat tietokanta-asetukset.

Sen jälkeen kun myös kotikoneen .env -tiedostoa on muokattu, kannattaa Laravel-prosessi käynnistää uudelleen.

Eli painetaan CTRL + c

Jonka jälkeen ajetaan komento:

php artisan serve

Laravel asennuksen mukana tulee harjoittelua varten valmius luoda yksinkertainen käyttäjätietokanta. Se saadaan käyttöö kirjoittamalla seuraava komento:

php artisan migrate

Kun tehtävä on suoritettu ja phpMyAdmin-ikkunassa valitaan juuri äsken luotu tietokanta, niin sen sisälle on ilmestynyt joukko tietokantatauluja:

Luodaan yksi käyttäjä. Se voidaan tehdä esim. seuraavilla komennoilla:

php artisan tinker

Tämä avaa Psy Shell:in. Syötetään siihen seuraava koodinpätkä:

User::factory()->create()

Psy Shellin saa suljettua kirjoittamalla komentokehotteeseen exit.

Jos nyt avaa phpMyAdminissa users-taulun, niin siellä pitäisi olla yksi käyttäjä!

Muokataan hieman Laravel:in web.php-tiedostoa. Se löytyy kansiosta: routes.

Lisätään uusi route, joka tulostaa tietokantaan talletettujen käyttäjien määrän:

Route::get('/users', function () {

    $users = App\Models\User::all();
    return "<p>Käyttäjiä on yhteensä: ".count($users)." kpl</p>";

});

Tiedoston pitäisi siis näyttää seuraavalta:

Kun selaimella mennään osoitteeseen: http://localhost:8000/users, niin aukeava sivu kertoo, että tietokannassa on yksi käyttäjä.

Kotikoneella tietokantayhteys on nyt saatu toimimaan.

Talletetaan päivitykset Github-repositoryyn. Kun käytössä on Github-actions, niin samalla päivittyy myös Webhotellin puolella ajettava Laravel-instanssi.

Komento sanan toistuva käyttö alkaa ärsyttämään, vaihdetaan lähestymistapaa ja esitetään versionhallinnalle seuraavat toivomukset:

git add .
git commit -m "Tietokanta otettu käyttöön"
git push

Takaisin sivun alkuun

Loppuhuipentuma

Jos nyt vilkaistaan miltä Github-repositoryn Actions välilehdellä näyttää, niin kohtaan All workflows on ilmestynyt uusi merkintä.

Nyt ollaan jo melkein maalissa.

Jotta tietokanta tulisi alustetuksi myös Webhotellin puolella, pitää terminaalissa ajaa samat komennot, kuin omalla koneella suoritettiin tietokantaa alustettaessa, eli:

php artisan migrate

...mutta luodaankin palvelimelle 10 käyttäjää:

php artisan tinker

Ja Psy -editorissa:

User::factory()->count(10)->create()
Exit

Kun tämän jälkeen avaamme käyttäjien määrän ilmoittavan sivun, niin näemme viestin, joka kertoo tietokantaan lisättyjen käyttäjien määrän.

Takaisin sivun alkuun

Loppusanat

Vaikka tämä opas päästiin nyt loppuun, niin matka on vasta alussa. Seuraavaksi voi tutustua vaikka Actions skriptien tarjoamiin mahdollisuuksiin. Skriptiä hiomalla on mahdollista vähentää tarvittavaa terminaali työskentelyä. Vinkkejä löytyy esimerkiksi täältä.

Takaisin sivun alkuun