Instalacja CMS Open .NET Core 3.1 — instrukcja krok po kroku

Postawienie własnego CMS-a brzmi jak wyzwanie, ale przy CMS Open cała procedura sprowadza się do kilku jasno rozpisanych kroków. W tym wpisie przeprowadzę Cię przez instalację systemu napisanego w .NET Core 3.1 — od sklonowania repozytorium, przez konfigurację pliku secrets.json, aż po pierwsze zalogowanie się do panelu admina. Kod źródłowy oraz dokumentację znajdziesz na stronie cmsopen.net.

Wymagania wstępne

Zanim zaczniesz, upewnij się, że Twoje lokalne środowisko ma wszystko, czego potrzebuje CMS Open. Lista nie jest długa, ale każdy element jest niezbędny — pominięcie któregokolwiek z nich sprawi, że na którymś z kolejnych etapów utkniesz na błędzie, którego przyczyna nie będzie oczywista.

Potrzebujesz:

• .NET Core 3.1 SDK — to runtime, na którym postawiony jest cały system.
• MySQL Server + MySQL Workbench — baza danych oraz wygodne narzędzie do zarządzania nią. Workbench pobierzesz z oficjalnej strony MySQL.
• Git — do sklonowania repozytorium na swój dysk.
• Visual Studio 2019 (lub nowsze) albo JetBrains Rider — cokolwiek, czym wygodnie odpalisz projekt .NET Core.
• Konta w zewnętrznych usługach: Cloudinary (hosting zdjęć), Sendinblue (email marketing) oraz Slack (powiadomienia). Wszystkie mają darmowe plany, które spokojnie wystarczą do rozwoju.

Jeśli nie potrzebujesz którejś integracji, nie musisz z niej korzystać — w pliku secrets.json możesz po prostu pozostawić puste wartości, a konkretna funkcjonalność zostanie wyłączona.

Pobranie i deployment repozytorium

Otwórz stronę repozytorium CMS Open na GitHubie i wykonaj fork — dzięki temu otrzymasz własną kopię kodu, na której możesz pracować bez wpływu na oryginał. Fork przypisze projekt do Twojego konta GitHub, co ma znaczenie, gdy będziesz chciał później commitować własne zmiany albo aktualizować wersje.

Po sforkowaniu repozytorium skopiuj link z zielonego przycisku Code. Następnie otwórz terminal w katalogu, w którym chcesz mieć projekt, i wykonaj:

git clone https://github.com/<twoja-nazwa>/CMS.git
cd CMS

Polecenie pobierze wszystkie pliki źródłowe na Twój lokalny dysk. Gdy proces się zakończy, otwórz solucję (.sln) w Visual Studio lub Riderze — zobaczysz strukturę projektu z warstwą domeny, danych i prezentacji.

Plik secrets.json i konfiguracja integracji

To najważniejszy krok całej instalacji. Bez pliku secrets.json w głównym katalogu projektu aplikacja po prostu się nie uruchomi — zgłosi wyjątek przy starcie, ponieważ nie znajdzie wymaganych kluczy konfiguracyjnych.

W katalogu src (lub odpowiadającym mu w Twojej strukturze projektu) kliknij prawym przyciskiem myszy i dodaj nowy plik JSON o nazwie dokładnie secrets.json. Zwróć uwagę na pisownię — literówka oznacza, że aplikacja nie załaduje konfiguracji. Szablon zawartości znajdziesz w README repozytorium.

Kolejno uzupełnij sekcje:

1. Cloudinary — po zalogowaniu w panelu Cloudinary skopiuj Cloud Name, API Key oraz API Secret. Te trzy wartości trafiają do sekcji CloudinarySettings.
2. Slack — wejdź w dokumentację Slacka i utwórz Incoming Webhook dla kanału, na który mają przychodzić powiadomienia. URL webhooka wklej do sekcji SlackSettings.
3. Sendinblue — zaloguj się, przejdź do zakładki z kluczami API, wygeneruj klucz i wklej go do sekcji SendinblueSettings.
4. Connection string do MySQL — podaj użytkownika, hasło, host i nazwę bazy, którą wcześniej utworzyłeś w Workbenchu. Przykładowy format: Server=localhost;Database=cmsopen;User=root;Password=twoje-haslo;.

Plik secrets.json jest zawsze na .gitignore — nigdy nie commituj go do repozytorium, bo razem z kluczami API trafi do publicznej historii GitHub.

Pierwsze uruchomienie i panel admina

Gdy secrets.json jest wypełniony, a baza MySQL gotowa, możesz odpalić aplikację. W Visual Studio wystarczy klawisz Ctrl+F5 (uruchomienie bez debuggera), w Riderze — Shift+F10.

Przy pierwszym starcie Entity Framework Core wykona automatycznie wszystkie migracje i zbuduje strukturę tabel w Twojej bazie. To właśnie dlatego connection string musi być poprawny — jeśli aplikacja nie połączy się z MySQL, migracje się nie wykonają i system nie wystartuje. Po chwili w przeglądarce powinna pojawić się strona startowa — to znak, że instalacja przebiegła poprawnie.

Żeby zalogować się do panelu administracyjnego, w adresie URL dopisz /admin/default:

https://localhost:5001/admin/default

Pierwsze logowanie wykonasz domyślnymi danymi, które są zaszyte w seedzie bazy:

• Login: admin
• Hasło: adminhouse

Po zalogowaniu zobaczysz pełną wersję panelu — możesz zarządzać treścią, użytkownikami, zdjęciami (które trafią do Cloudinary) i konfiguracją kanałów komunikacji. Od razu po pierwszym logowaniu zmień hasło admina na własne — domyślne dane są publicznie znane, więc pozostawienie ich to otwarta furtka do Twojej instalacji.

Jeśli coś nie działa — najczęstsze powody to literówka w nazwie secrets.json, brak uprawnień użytkownika MySQL do tworzenia tabel albo zablokowany port 3306 przez firewall. W takich sytuacjach zacznij od przejrzenia logów w konsoli IDE — .NET Core wypisuje tam bardzo konkretne komunikaty, które od razu prowadzą do przyczyny.

Zobacz więcej

CMS Open to projekt open source, który rozwijam od 2020 roku na licencji MIT — kod znajdziesz na GitHubie, a wszystkie aktualizacje, dokumentację i zmiany w API na stronie cmsopen.net. Jeśli masz pytania lub potrzebujesz pomocy przy wdrożeniu — napisz na [email protected] albo użyj formularza kontaktowego na mojej stronie. Każdy pull request i zgłoszenie issue jest mile widziane.