Z Wordpressa na Hugo! Zakładanie własnego bloga na Mikrusie

[Leoneq]

Czy w dzisiejszych czasach warto mieć bloga? Odpowiedzi tutaj mogą być różne, przecież jest już tyle serwisów społecznościowych że i tak nikt nie znajdzie naszej "małej" strony. Z drugiej strony własna strona to też wizytówka, zgromadzenie wiedzy w jednym miejscu, prywatne miejsce wolne od reklam. Uważam że warto pomyśleć o założeniu własnej strony, szczególnie że nie jest to w dzisiejszych czasach drogie - a może być nawet darmowe!

W tym poradniku postaram się opisać proces instalacji generatora stron statycznych Hugo na serwerze. Dodatkowo opiszę jeszcze proces instalacji CMSa - Content Management System - który pozwala poczuć się tak, jak by się korzystało z Wordpressa. Haczykiem jest dobra znajomość Linuxa.

Dlaczego by po prostu nie zainstalować Wordpressa?!

WP się chwali że ponad 43% Internetu jest na nim oparte (no, a przynajmniej teraz). Do działania wymaga pełnego zestawu oprogramowania (serwera www, PHP, bazy danych), co sprawia że nie jest to najlżejsze oprogramowanie. Wygląd strony albo ustalamy sami - i jest to fajne dla "zwykłych" użytkowników korzystających z edytorów WYSIWYG - jednak gdy chcemy zrobić własny motyw (theme) to już się zaczynają schody. Do tego trzeba dodać ogrom wtyczek jakie czasem musimy zainstalować... i nawet jeżeli mamy stronę statyczną, skrypty i style potrafią mieć kilka ładnych megabajtów.

Czy to dobrze czy źle? Przecież dzisiaj internet jest powszechny i szybki, 1Mb/s to już standard "lejka" w pakietach. I jest to pytanie na które każdy sam sobie musi odpowiedzieć. Jeżeli nikomu nie przeszkadza WP i jest dla niego wygodny, nie widzę problemu. Z kolei ja uznałem że gdyby większość Internetu wróciła do takich stron statycznych, ile zasobów by było zaoszczędzone! Nie mówiąc o tym że sam czasem mam kłopoty z internetem, a i też nie lubię mieć "bloatware" u siebie - tymbardziej go wspierać.

Alternatywą są strony statycznie generowane. Na serwerze mamy pewną strukturę plików, które potem są """kompilowane""" na jedną stronę statyczną, która zawiera surowego HTMLa ze stylami i skryptami. Bez dodatkowych baz danych, pehapów itd.

Wyobraźmy sobie że zamiast bazy danych, którą odpytujemy podczas ładowania strony, dane co jakiś czas "pakujemy" do chociażby pliku tekstowego, i ten mały plik pobieramy. Dla wielu stron statycznych, a nawet blogów jest to zupełnie wystarczające.

Jeżeli przekonałem do wypróbowania Hugo (bo takiego generatora będziemy używać), zapraszam do dalszego czytania.

Jak działa Hugo

Nasza strona przed wygenerowaniem to zbiór plików Markdown, oraz potrzebnych mediów (jak zdjęcia, filmy itd). Pojedynczy plik .md to pojedynczy wpis, i tam możemy pisać co chcemy.

Cytat

Często pliki "readme" są w formacie Markdown - nawet komunikatory, jak Discord używają tego do formatowania tekstu. Alternatywą dla Markdownu jest Latex (gdzie bardziej skupiamy się na strukturze logicznej dokumentu)

Kiedy uznamy że chcemy stronę opublikować, generujemy ją - a pliki w katalogu publicznym są aktualizowane, i to tyle. Generator dodaje tylko to co jest potrzebne, więc to czego nie chcemy opublikować nie zostanie dodane. Jest to bardzo dobra alternatywa względem WP dla stron statycznych - czyli wygenerowanych jednorazowo, lub aktualizowanych rzadko. I jest to też lepsza alternatywa niż pisanie HTML "z ręki", edytując pliki Markdown po prostu piszemy sprawniej niż w czystym HTMLu. Do tego strona na Hugo może być repozytorium Git - dzięki czemu aktualizowanie modułów, kopie danych itd. są dość uproszczone.

Weźmy na ten przykład stronę którą udało mi się utworzyć jako demo WP, z domyślnym motywem i bez mediów. Z kolei stronę na Hugo wybrałem jako demo motywu Papermod.

Po kliknięciu CTRL-F5 (czyli załadowaniu od nowa wszystkich plików), na dole możemy odczytać podsumowanie; strona na WP załadowała się w nieco ponad 2 sekundy, przesyłając ok. 600kB przesłanych danych. Z kolei przykładowy wpis na Hugo to pół sekundy i 75kB! Warto zauważyć mniejszą ilość plików oraz mniejszy rozmiar głównego pliku HTML i CSS względem strony na WP.

(oczywiście to porównanie nie jest do końca dobre, więc zachęcam do samodzielnego wypróbowania obu metod!)

Platforma testowa

Ponieważ swoją główną stronę już dawno postawiłem, nową będę stawiać serwerze Frog z oferty Mikrusa. Pozwolę sobie tutaj na małą reklamę, bo aż żal tego nie robić! Serwery Mikrusa to małe VPSy które zostały stworzone z myślą o małych projektach, nauce, słowem - dla hobbystów. Oferta Frog jest specjalna, bo są to serwery DARMOWE, przeznaczone do nauki. Serwer jest przypisany na czas nieokreślony, wystarczy się logować co 3 miesiące, i jest też idealny do małych projektów IoT! Oczywiście jest to bardzo mały serwer, mający tylko 256MB RAMu. Będzie to jednak idealne do postawienia bloga na Hugo - bo domenę "jakąś" mamy nawet w gratisie, a Wordpress mógłby mieć już pewne problemy z tak małą ilością RAMu. Myślę że jednak wielu Czytelników spojrzy na ten serwer ze strony zastosowania go w branży IoT.

Oczywiście nikt nie zabrania podłączyć własnej domeny, płatnej kilkadziesiąt złotych rocznie, do darmowego Froga, i mieć prawie darmową, profesjonalną stronę. Zabrania się za to hakowania  

Instalacja LEMP

LEMP to modyfikacja pakietu LAMP (Linux Apache MySQL PHP), gdzie Apache zostało zmienione na Nginx. Jest to moja preferencja, więc jeżeli wolisz Apacza (i się na nim znasz) to oczywiście instalujemy to co umiemy i lubimy. Jest to taki pakiet podstawowy do obsługi sieci, nawet jeżeli nie będziemy korzystać z PHP ani MySQL - warto od razu na wstępie mieć je przygotowane, aby w przyszłości z nich po prostu skorzystać. W końcu nasza strona to nie musi być sam blog, to może być też galeria zdjęć, baza rzeczy w warsztacie, czy prywatne Trello - wszystko co tylko chcemy, i pozwala nam na to serwer!

Oczywiście, jeżeli na pewno chcemy tylko stronę, możemy zainstalować tylko Nginxa/Apache. Po zalogowaniu się na serwer, wita nas MOTD:

Zachęceni, przechodzimy do katalogu ze skryptami, i uruchamiamy skrypt instalujący Nginxa. Na początku wpisałem też "sudo su" aby za każdym razem nie być pytany o hasło.

Jeżeli instalacja przebiegła pomyślnie, powinniśmy zobaczyć coś takiego:

Ponieważ skupię się na tym jak konkretnie serwer Frog uruchomić z Hugo, nie będę opisywał procesu podpinania domeny - skorzystamy z tej domyślnej. W MOTD dostaliśmy przydzielone porty, całe trzy. Wybieramy dowolny, i edytujemy plik /etc/nginx/http.d/default.conf tak, aby port 80 podmienić na ten nasz. Na końcu, zmieniamy jeszcze katalog root (wskazuje on gdzie jest nasza strona); dodajemy podkatalog /public.

Sprawdzamy czy wszystko jest dobrze wpisane, a następnie przeładowujemy Nginxa.

nginx -t
rc-service nginx restart

Trzeba podkreślić tutaj, że Mikrus działa na Alpine Linuxie; na zwykłym Debianie zamiast rc-service byśmy mieli systemctl.

Jeżeli stworzymy plik index.html w folderze /var/www/html/public, będziemy mogli go otworzyć wchodząc na naszą stronę (frogNR-port.wykr.es), jednak my od razu przejdziemy do instalacji Hugo.

Cytat

Cała dokumentacja i poradniki do Mikrusów jest tutaj! https://wiki.mikr.us/

Instalowanie Hugo

Aby zainstalować Hugo, najlepiej przejść tutaj i zrobić to zgodnie z poradnikiem. Ponieważ mamy Alpine, użyłem poniższej komendy:

apk add --no-cache --repository=https://dl-cdn.alpinelinux.org/alpine/edge/community hugo
cd /var/www # poprzednie pliki w katalogu html możemy usunąć lub zignorować
hugo new site html
cd html

Jak już wcześniej wspomniałem, nasza strona to tak naprawdę repozytorium Gita. Nie jest to obowiązkowe, lecz zalecane więc tak też zrobimy. Zainstalujemy od razu motyw Papermod - ten sam, który jest używany w dokumentacji Mikrusa!

git init
git submodule add https://github.com/adityatelange/hugo-PaperMod themes/papermod

Jest szansa że Git zapyta się o permisje. Jeżeli tak będzie, wystarczy dodać wyjątek _{(lub naprawić permisje, jeżeli sie nie jest leniwym).}

Następnie musimy edytować plik hugo.toml; zmieniamy adres na ten jaki dostaliśmy, oraz ustawiamy motyw. Opcjonalnie możemy zmienić język oraz nazwę strony.

Pozostało już tylko wygenerować stronę! Wpisujemy komendę "hugo", i jeżeli wszystko się udało - powinniśmy dostać ładną tabelkę:

A po wejściu na stronę, nasz blog!

Cieszymy się niezmiernie z naszego nowego bloga, ale jak do niego dodawać wpisy?! Musimy wygenerować plik Markdown, a następnie go edytować:

Strukturę naszego bloga w katalogu content/ określamy sami. Zachęcam tutaj do zapoznania się z dokumentacją Hugo.

Pamiętajmy o zmianie "draft" na false, aby strona została opublikowana! Dodałem na potrzeby prezentacji nagłówek (#), tekst oraz `kod`. Po zapisaniu pliku, ponownie wpisujemy hugo i odświeżamy stronę:

Cytat

Jeżeli strona nie chce się odświeżyć, spróbujmy to robić skrótem CTRL-F5. Jest to spowodowane tym, że przeglądarki takie statyczne elementy lubią zapisywać "na później", nie zawsze je odświeżając.

I tutaj poradnik mógłbym zakończyć - udało nam się postawić ładnego bloga na darmowym serwerze, jednak podejrzewam że nie każdy lubi korzystać z vima jako edytor wpisów na blogu, a za każdym razem aby coś edytować logować się poprzez SSH.

Do strony możemy bowiem dodać CMS - Content Management System - który jest swego rodzaju "frontendem" do Hugo. Dzięki temu wpisy możemy edytować bezpośrednio z przeglądarki, w ładnym edytorze WYSIWYG. Niestety tracimy już tutaj na niezależności, gdyż zaczniemy opierać się o usługi Githuba/Gitlaba oraz Cloudflare. Decyzja zatem ponownie należy do Czytelnika.

Instalacja Sveltii

Moim ulubionym CMSem jest Sveltia, będącym leciutkim i ładnym edytorem który jest bardzo aktywnie rozwijany przez twórcę.

Alternatywą jest Decap CMS, więc ponownie mamy wybór.

Polecam teraz zapiąć pasy, ponieważ proces instalacji tego jest dość skomplikowany. Jeżeli nie czujemy się na siłach, możemy spróbować skorzystać z gotowej usługi oferowanej przez Netlify, która ma ten proces znacznie uprościć. Postanowiłem jednak na Sveltię właśnie z tego względu że nasza strona jest u nas, i w razie czego - po prostu stracimy do niej dostęp z przeglądarki (w razie awarii Cloudflare, chociaż jest to mało prawdopodobne).

Zacznijmy od podpięcia naszej strony do repozytorium. Skonfigurujmy w systemie nazwę użytkownika oraz mail:

Na stronie naszego Gita zakładamy nowe, puste repozytorium. Kopiujemy adres, następnie:

git remote add origin https://adres.naszego.repo.pl
git add .
git commit -m "Pierwszy commit"
git push -u origin master

Zostaniemy poproszeni o nazwę użytkownika oraz hasło.

Cytat

UWAGA! Do Githuba nie można się już logować hasłem. Musimy wejść w Ustawienia -> Ustawienia deweloperskie -> Personal access tokens -> Tokens (classic) i stworzyć nowy token. Trzeba go wklejać kiedy zostaniemy poproszeni o hasło.

Jeżeli wszystko się udało, na stronie naszego repozytorium powinniśmy zobaczyć naszą stronę. Następnie tworzymy nowy folder oraz dwa pliki: stronę oraz konfigurację.

mkdir static/admin
nano static/admin/index.html
nano static/admin/config.yml

Pierwszy plik to prosta strona która ładuje skrypt CMSa.

<!doctype html>
<html>
<head>
    <meta charset="utf-8" />
    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
    <meta name="robots" content="noindex" />
    <title>Content Manager</title>
</head>

<body>
    <script src="https://unpkg.com/@sveltia/cms/dist/sveltia-cms.js"></script>
</body>
</html>

Drugi plik to konfiguracja naszego CMSa.

• name zmieniamy na github lub gitlab
• repo zmieniamy na np. uzytkownik/moje_repozytorium
• branch najlepiej zostawić jak jest.

Pozostałe dane to zaproponowana przeze mnie konfiguracja, oczywiście można ją zmienić po zapoznaniu się z dokumentacją Sveltii/Decapa. W skrócie, skonfigurowałem aby posty były w katalogu content/blog, oraz dane które możemy wpisać podczas edycji wpisu.

backend:
  name: github
  repo: uzytkownik/repozytorium
  branch: master # opcjonalnie, i tak domyslnie jest master
media_folder: static/media
public_folder: media
collections:
  - name: 'blog'
    label: 'Blog'
    folder: 'content/blog'
    create: true
    #slug: '{{slug}}'
    path: '{{slug}}/index'
    editor:
      preview: false
    media_folder: ''
    public_folder: ''
    #--------------------------
    fields:
      - { label: 'Title', name: 'title', widget: 'string' }
      - { label: 'Draft', name: 'draft', widget: 'boolean' }
      - { label: 'Publish Date', name: 'date', widget: 'datetime', format: 'YYYY-MM-DDTHH:mm:ssZ' }
      - { label: 'Description', name: 'description', widget: 'string' }
      - { label: "Featured Image", name: "image", widget: "image" }
      - { label: "Tags", name: "tags", widget: "list" }
      - { label: "Categories", name: "categories", widget: "list" }
      - { label: 'Body', name: 'body', widget: 'markdown' }

Dodatkowo możemy też usunąć plik hugo.toml z głównego katalogu, i stworzyć hugo.yaml z moją przykładową konfiguracją:

baseURL: "https://frogNR-port.wykr.es"
languageCode: pl-pl
title: "testowy blog"
theme: "papermod"
enableEmoji: true

params:
  headless_cms:
    engine: "sveltia"
    site_url: "https://frogNR-port.wykr.es"
    backend:
      name: "github"
      repo: "org/repo"

collections:
  - label: "post"
    name: "post"
    folder: "post"
    create: true
    sort_by: "date"
    sort_ascending: false
    fields:
      - {label: "Title", name: "title", widget: "string"}
      - {label: "Publish Date", name: "date", widget: "datetime"}
      - {label: "Featured Image", name: "thumbnail", widget: "image"}
      - {label: "Body", name: "body", widget: "markdown"}

Po zapisaniu i przeładowaniu dzięki hugo, po przejściu na naszą stronę i dodaniu /admin powinniśmy zobaczyć coś w tym stylu:

Cytat

Wskazówki jeżeli coś jest nie tak:

• za każdym razem przeładowywać przez CTRL-F5
• upewnić się że nazwa repozytorium jest poprawnie wpisana
• strona Froga którą dostaliśmy powinna być powyższego formatu (nie z portem po dwukropku! Ta nie ma certyfikatu SSL)
• potencjalnie coś może być z permisjami, wówczas trzeba już szukać pomocy we własnym zakresie

Jeżeli spróbujemy się zalogować, niestety zostaniemy jedynie zaskoczeni okienkiem z napisem "File not found". I tutaj pojawia się problem: aby uwierzytelnianie było wiarygodne, musi być zatwierdzone przez Githuba lub Gitlaba. Niestety, jeżeli twórca Sveltii by hostował skrypt do zatwierdzania to mógłby się narazić na problemy prawne (przechowywanie danych, RODO itd.) więc jest to obecnie robione za pośrednictwem Cloudflare. Więcej szczegółów jest opisane tutaj. Wchodzimy w tą stronę, i klikamy "Deploy with Workers". Jest opcja użycia Github Pages i innych usług - jednak skoncentrujemy się na tej zalecanej opcji.

Zgadzamy się na autoryzację. Następnie logujemy się lub rejestrujemy. Do wpisania są ID użytkownika oraz token. ID użytkownika będzie napisane po prawej stronie w głównym panelu; token wygenerujemy klikając w link "My profile", oraz tworząc nowy token z szablonu "Edit Cloudflare Workers". W przypadku problemów, zapraszam do skorzystania z pomocy w Internecie. Tak uzyskany token wpisujemy w pole, i zatwierdzamy.

Zgadzamy się na wszystko, aktywujemy Github Actions. Po kliknięciu Deploy przechodzimy do dashboarda, i wybieramy nowo utworzonego Workera. Tam klikamy "View version", aż w końcu ukaże się adres strony pomocniczej! Kopiujemy go, bo przyda się później.

Wracamy do Githuba/Laba. Rejestrujemy nową aplikację:

• nazwa dowolna (np. Sveltia CMS Authenticator)
• strona dowolna (np. https://github.com/sveltia/sveltia-cms-auth)
• opis dowolny lub pusty
• callback URL: strona którą zapisaliśmy, z dopiskiem /callback

Kopiujemy ID klienta oraz Sekret. Wracamy do naszej aplikacji sveltia-cms-auth na Cloudflare. Przechodzimy do Compute (Workers) -> Workers & Pages -> sveltia-cms-auth -> Settings -> Variables and Secrets. Klikamy Add, wklajamy nasze ID oraz sekret. Ważne aby nazwy zmiennych (GITHUB_CLIENT_ID oraz GITHUB_CLIENT_SECRET) się zgadzały!!

Klikamy Deploy. Ostatnim krokiem jest powrót na sam początek - edytujemy plik static/admin/config.yml. Dodajemy poniższą linijkę:

backend:
  ...
  base_url: https://strona.do.workers.dev

Wpisujemy hugo, klikamy CTRL+F5, i tym razem po próbie zalogowania powinniśmy dostać przepiękne okienko:

I po zalogowaniu się, panel główny.

Tak wygląda edytor WYSIWYG; wszystkie te formatowania zostały wyklikane z górnej belki:

Po kliknięciu w górnym prawym rogu na ikonkę M, będziemy mogli edytować artykuł w surowym Markdownie. Po kliknięciu Save jednak nic się nie stało! Możemy albo manualnie aktualizować stronę wywołując Hugo, lub trochę leniwa ale działająca opcja - małego crontaba który to robi za nas np. co minutę. Tutaj już pozostawiam to do wyboru Czytelnikowi. Oczywiście przed zbudowaniem strony trzeba "zassać" zmiany z repozytorium - wykonując polecenie git pull.

Zdjęcia możemy wybierać z naszej własnej biblioteki, bezpośrednio z linku, lub z biblioteki stockowych zdjęć. Polecam Pixabay!

I po wszystkim udało nam się stworzyć ładnego bloga, przypominającego Wordpressa, ale za to o wiele czystszego. Proces instalacji nie jest przyjemny, ale na pewno satysfakcjonujący. Oczywiście jeżeli potrzebujemy stronę "wizytówkę" - ściągamy gotowy motyw do Hugo, wpisujemy to co chcemy, polecenie hugo i gotowe.

Poradnik ten napisałem, bo w Internecie jest dość mało informacji o instalacji Decapa/Sveltii bez Netlify, a rozgryzanie tego samemu zajęło mi tydzień. Jeżeli ktoś chciałby motyw do bloga z "prawdziwego zdarzenia", bardzo polecam zobaczyć demo motywu Stack. Zatem udało nam się zainstalować wspólnie generator stron, wraz z ładnym edytorem, a to wszystko dlatego że lubimy lekkie rozwiązania opensource. Jestem świadomy że poradnik nie pokazuje najprostszej drogi, więc ponownie zachęcam do spróbowania z Netlify!

Pozostaje mi życzyć powodzenia i przyjemnego pisania stron!

Edytowano Luty 9, 2025 przez Leoneq

[Leoneq]

Mały dodatek: swojego bloga można bardzo łatwo prowadzić w dwóch językach (np. po polsku i angielsku) za pomocą i18n. Wystarczą zmiany w dwóch plikach (i ewentualnie nazwy już napisanych postów), proponuję poniższą strukturę:

content/blog/
├── secondpost
│   └── index.en.md
│   └── index.pl.md
├── firstpost
│   ├── image.jpg
│   └── index.en.md
│   └── index.pl.md

Zaczynamy od hugo.yaml:

languageCode: en-us
defaultContentLanguage: en
defaultContentLanguageInSubdir: false
disableDefaultLanguageRedirect: false

languages:
  pl:
    weight: 2
    languageName: Polski
    title: Nazwa blogu po polsku
  en:
    weight: 1
    languageName: English

Nazwy "English" i "Polski" są wykorzystywane w menu wyboru języka na stronie, o ile nasz motyw wspiera wiele języków. Dodatkowo nazwa bloga (tak jak i inne nazwy) mogą zostać przetłumaczone.

Kolejnym krokiem jest zmiana w configu CMSa (static/admin/config.yml):

i18n:
    structure: multiple_files
    locales: [en, pl]
    default_locale: en
slug:
    encoding: ascii
#    clean_accents: true # zapisze np. umlauty jako dwuznaki

...

collections:
  - name: 'blog'
    ...
    slug: '{{title | localize}}'
    path: '{{slug}}/index'
    i18n: true
    # do kazdego fielda trzeba dodac linijke "i18n: true" jezeli ma byc zmieniona tresc
    fields:
      - { label: 'Title', name: 'title', widget: 'string', i18n: true }
      - { label: 'Draft', name: 'draft', widget: 'boolean', i18n: true }
      - itd...

I to wszystko! Tak wygląda efekt dla Sveltii:

Dodatkowo powyższy config zapewni tłumaczenie linków (co można wyłączyć poprzez usunięcie " | localize" z configu CMSa).