Developer's environment setup - iiuni/projektzapisy Wiki

Wstęp

System Zapisów jest napisaną w Pythonie aplikacją serwerową. Na serwerze produkcyjnym (czyli w realu) uruchamiamy go za pomocą serwera Gunicorn ukrytego za Nginx'em. Stanem aplikacji zarządza serwer Postgresql.

Maszyna dla developera jest skonfigurowana tak, by nie różnić się zanadto od serwera produkcyjnego, ale jednocześnie być łatwą w użyciu i wygodną dla programisty. Nie wymaga od programisty żadnego konfigurowania ani wydawania wielu komend.

Uruchamianie

Instalacja oprogramowania

Na swoim komputerze musimy mieć zainstalowany Virtualbox, który pozwala nam uruchamiać maszyny wirtualne, oraz Vagrant, który potrafi tymi maszynami zarządzać i je łatwo konfigurować. W naszym projekcie mamy taką konfigurację, w pliku Vagrantfile. Oba programy da się zainstalować na każdym sensownym systemie operacyjnym — w Ubuntu można skorzystać z wersji w repozytorium:

[email protected]:~$ sudo apt install virtualbox vagrant

Uruchamianie developerskiej wersji Systemu Zapisów

Klonujemy niniejsze repozytorium na swój komputer. Następnie otwieramy terminal w jego głównym katalogu (albo którymkolwiek podkatalogu) i wydajemy polecenie:

[email protected]:projektzapisy$ vagrant up

Vagrant ściągnie z internetu świeży obraz maszyny wirtualnej z systemem Ubuntu, a następnie uruchomi proces instalacji (prawie) wszystkiego, co jest potrzebne by System Zapisów działał. Ten proces nazywa się provisioning i został przez nas zaprogramowany w playbooku Ansible.

Gdy provisioning się zakończy i powyższe kroki zostaną wykonane, należy wydać w konsoli polecenie:

[email protected]:projektzapisy$ vagrant reload

Gdy proces się zakończy, należy chwilkę odczekać, a następnie wejść (z komputera-hosta) na adres http://0.0.0.0:8000, gdzie nasłuchuje serwer testowy naszej aplikacji (uruchomiony w maszynie wirtualnej).

Ładowanie obrazu bazy

Przed uruchomieniem maszyny warto ściągnąć obraz bazy danych (link można znaleźć na Slacku, na kanale #db_backups), rozpakować go i umieścić (plik ii_zapisy_dump_dev.sql) w głównym katalogu projektzapisy/. Provisioner instalujący oprogramowanie wychwyci ten plik i załaduje go do maszyny wirtualnej.

Obraz bazy jest zanonimizowany. Zamazane są w nim nazwiska, adresy email i inne „wrażliwe” dane. Hasła wszystkich użytkowników są zamienione na pass. Użytkownikami z uprawnieniami administratora są np. mbiernacka, asm.

Wyłączanie maszyny, ponowna instalacja

Maszynę wirtualną można wyłączyć poleceniem vagrant halt lub nawet zniszczyć, poleceniem vagrant destroy. Odpalenie polecenia vagrant provision gdy maszyna jest uruchomiona spowoduje powtórzenie procesu instalacji — można to zrobić, gdy nasz playbook uległ zmianie, albo gdy chcemy załadować od nowa bazę danych.

Co jest w tej konfiguracji?

W konfiguracji Vagranta katalog projektu (czyli projektzapisy/) na naszym komputerze jest zmapowany do /vagrant/ w maszynie wirtualnej. W maszynie wirtualnej uruchomione są dwie istotne dla nas usługi systemowe:

  1. Serwer testowy naszej aplikacji zapisy, uruchomiony za pomocą polecenia python manage.py runserver z katalogu /vagrant/zapisy/. Serwer ten jest zdecydowanie mniej wydajny niż ten produkcyjny, ale za to przeładowuje aplikację zawsze, gdy zmieni się jej kod. Dzięki temu możemy programować (na maszynie hosta) i na żywo widzieć efekty.
  2. Kompilator assetów (Javascript/Typescript/Vue/style) obserwujący zmiany w plikach. Uruchomiony za pomocą polecenia yarnpkg dev:watch. Dzięki temu możemy programować we front-endzie i na żywo widzieć efekty (więcej informacji: Praca nad front-endem).

Inne porady

  • Live-kompilator assetów nie poradzi sobie, gdy dodajemy nowy bundle (w pliku asset-defs.js) lub jakieś zależności (do pliku package.json). Musimy wtedy zrestartować maszynę wirtualną (poleceniem vagrant reload).

  • Gdy dodajemy jakąś zależność Pythonową (do plików requirements.*.txt), musimy przeprowadzić jeszcze raz provisioning.

  • Jeśli chcemy, by Django wygenerowało nam migracje po zmianach w strukturze bazy danych, musimy zalogować się do maszyny wirtualnej:

    [email protected]:projektzapisy$ vagrant ssh 

    wewnątrz maszyny wirtualnej wchodzimy do katalogu /vagrant/zapisy i odpalamy polecenie:

    (env3) [email protected]:/vagrant/zapisy$ python manage.py makemigrations
  • Jeśli maszyna wirtualna zacina się podczas provisioningu (na przykład na kroku Gathering facts), warto go przerwać (Ctrl+C) i uruchomić od nowa (vagrant provision).

  • Łączenie się z deweloperską bazą danych zostało opisane na osobnej stronie wiki: Łączenie się z serwerem bazy danych środowiska deweloperskiego

  • Użytkownicy Windowsa napotykają często na bardzo trudne do zdiagnozowania kłopoty związane z kodowaniem końca linii. W Windowsie koniec linii koduje się za pomocą \r\n (CRLF — carriage return, line feeed), zaś w Uniksie/Linuksie tylko za pomocą \n (LF). Nasz kod jest uruchamiany na Linuksie, więc w naszym projekcie trzymamy się standardu uniksowego. Git na Windowsie próbuje być jednak mądrzejszy i przy klonowaniu repozytorium zamienia \n na \r\n — co prowadzi do problemów z maszyną wirtualną. By upewnić się, że:

    • Klonujemy pliki bez konwertowania, oraz;
    • Nie wrzucamy do repozytorium plików z windowsowymi końcami linii;

    Należy ustawienie Git-a core.autocrlf ustawić na input.

Podziękowania

Pierwszy set-up z użyciem Vagranta wprowadził do naszego projektu @florczakraf. Obecne rozwiązanie z użyciem Ansible (i nie wymagające logowania się do maszyny wirtualnej) stworzyli @barnij i @receek (#888).

⚠️ **GitHub.com Fallback** ⚠️