vm_installation_and_usage_pl

(Brief instruction in English can be found here: here

---

Instalacja

Ten dokument jest przeznaczony dla programistów. Zakładamy, że znasz podstawy Linuksa, Apache i PHP. Zawiera kroki i wskazówki które pozwolą Ci skonfigurować sobie lokalne środowisko developerskie do pracy z kodem OCPL bazujące na udostępnionej przez nas maszynie wirt. Taki sposób działania polecamy, ale oczywiście możesz sam skonfigurować sobie własny serwer z kodem OCPL - wtedy ten dokument może być przydatny

Krok 1.

Przygotuj wymagane rzeczy:

• Ściągnij i zainstaluj VirtualBox (lub inny podobny np. VMware Player),
• Pobierz najnowszą wersję przygotowanego przez nas obrazu dysku serwera:
  • OCPL-DEVEL Virtual Machine, version 8 (7zip, ~1,1GB, md5: b4437982e0dfbb3267e5aa25c9385dcb),
• Rozpakuj pobrany plik np. przy pomocy 7-zip
• W VirtualBox-ie utwórz maszynę wirt. (Linux/Ubuntu/32-bit/1GB RAM) i jako dysk twardy wskaż rozpakowany plik ocpl-devel(...).vmdk. Moim zdaniem najlepiej stworzyć także 2 interfejsy sieciowe:
  • Host-only - stabilne, niezależne lokalne połączenie do maszyny VM
  • Bridged-adapter - na interfejsie, na którym masz dostęp do internetu - dostęp z VM do Internetu.

Krok 2.

Pierwszy login

Otwórz utworzoną maszynę wirtualną w VirtualBoxie. Zaloguj się jako user, hasło: ubuntu.

Konfiguracja połaczenia sieciowego

Na początek sprawdź czy masz połączenie z Internetem - możesz zrobić to np. przy użyciu komendy ping wydaj komendę ping wp.pl, której rezultat powinien wyglądać podobnie do tego:

user@ocpl-devel:~$ ping wp.pl
PING wp.pl (212.77.98.9) 56(84) bytes of data.
64 bytes from www.wp.pl (212.77.98.9): icmp_seq=1 ttl=59 time=6.44 ms
64 bytes from www.wp.pl (212.77.98.9): icmp_seq=2 ttl=59 time=6.84 ms
64 bytes from www.wp.pl (212.77.98.9): icmp_seq=3 ttl=59 time=7.07 ms
64 bytes from www.wp.pl (212.77.98.9): icmp_seq=4 ttl=59 time=8.72 ms
64 bytes from www.wp.pl (212.77.98.9): icmp_seq=5 ttl=59 time=7.13 ms
--- wp.pl ping statistics ---
5 packets transmitted, 5 received, 0% packet loss, time 4007ms
rtt min/avg/max/mdev = 6.445/7.245/8.728/0.783 ms

Jeśli "ping" nie działa prawdopodobnie będzie konieczne skonfigurowanie interfejsów sieciowych w twojej maszynie wirtualnej - jeśli nie masz doświadczenia z Linkusem możesz spróbować poszukać wskazówek w internecie (można zacząć np. od: https://help.ubuntu.com/lts/serverguide/network-configuration.html).

Plik hosts

Jeśli z twojej maszyny wirt. można już pingować świat możesz działać dalej: trzeba ustalić pod jakim adresem IP dostępna jest dla Ciebie Twoja maszyna wirt.

Jeśli nie wiesz jak to zrobić odpal komendę ifconfig i zwróć uwagę na adres przy inet addr.
U każdego pojawia się inny adres (najczęściej ma formę np. 192.168.56.x - wtedy to ten interfejs "host-only").

Ten adres trzeba dodać do pliku hosts na Twoim komputerze hoście następująco:

192.168.x.x local.opencaching.pl
192.168.x.x local.m.opencaching.pl

Oczywiście edycja pliku hosts będzie wymagała uprawnień administratora etc.

Na koniec warto sprawdzić czy wszystko gra i czy Twój komputer "host" ma kontakt z maszyną wirtualną. można to zrobić wydając polecenie ping local.opencaching.pl (na windowsie także jest polecenie ping w linii poleceń).

Jeśli pingi działają można także sprawdzić połączenie SSH - przez ssh jest o wiele łatwiej działać na maszynie wirt. niż w małym okienku VirtualBox-a.

Krok 3.

Wersja OC, którą widzisz, może być stara (tak stara jak wirtualna maszyna, którą pobrałeś). Żeby ją zaktualizować do najnowszej wersji:

• Wejdź z konsoli do katalogu /srv/ocpl.
• Zaktualizuj kod źródłowy komendą: git pull.
• (TYMCZASOWO KONIECZNE - musimy przygotować nową wersję maszyny wirt.)
  • Zaktualizuj wersję php do 7.2 => wymaga dosintalowania repo: https://launchpad.net/~ondrej/+archive/ubuntu/php/
  • Zaktualizuje plik ustawień /srv/ocpl/lib/settings.inc.php dodając komentarz do linii 406:

    // disable moving caches as decided by RR on 03.10.2014, 14:54:20
    //$config['forbidenCacheTypes'][] = cache::TYPE_MOVING;

• Aktualizacja OKAPI: wejdź w przeglądarce na stronę http://local.opencaching.pl/okapi/update.
• Przejrzyj także stronę http://local.opencaching.pl/okapi/devel/dbstruct?compare_to=https://opencaching.pl/okapi/devel/dbstruct i zaaplikuj odpowiednie ALTERy na swojej bazie (możesz zrobić to z poziomu phpmyadmina). Warto mieć na uwadze, że automatycznie wygenerowane poprawki mogą czasem nie zadziałać od razu i być może należy coś poprawić. W razie wątpliwości, napisz do RT. Jeśli wersja maszyny wirtualnej jest dość stara, a pewnie jest, ta operacja może być trudna - różnic w strukturze bazy danych będzie bardzo wiele - wtedy poproś kogoś z RT o wystawienie Ci świeżego, kompletnego obrazu bazy danych (wskazówki co dalej robić z takim obrazem w rozdziale Praca z bazą danych).
• Powyższe kroki warto powtarzać w przyszłości co jakiś czas by zawsze mieć aktualną wersję kodu i struktury bazy danych.

W razie problemów, napisz do nas (rt at opencaching.pl).

Nazwy i hasła

• Twój login: user, hasło: ubuntu. Użyj sudo jeśli potrzebujesz wykonać komendę jako root.
• Hasło użytkownika root na MySQL to toor (do użycia np. w phpmyadmin).
• Hasło użytkownika user na MySQL to ubuntu (do użycia np. w phpmyadmin).
• Aby zalogować się na stronie lokalnej wersji OC jako dowolny użytkownik (np. jako Ty), wpisz login i hasło: haslo (bez Ł). Listę użytkowników możesz przeglądać w tabeli user przez phpmyadmin.

Praca z konsolą

• W wielu przypadkach praca z konsolą nie jest potrzebna. Jeśli nie przepadasz za Linuksem, to praktycznie każdą czynność możesz wykonać zdalnie z Windowsa, a ten dział możesz pominąć.

• Jeśli łączysz się z Windowsa, użyj [PuTTy] (http://www.chiark.greenend.org.uk/~sgtatham/putty/download.html). W polu "Host Name" wpisz adres IP maszyny. Skocz do zakładki "Translation", w polu "Remote character set" wybierz "UTF-8". Wróć do zakładki "Session", w polu pod "Saved Sessions" wpisz "ocpl-devel" i kliknij "Save". Potem możesz już szybko łączyć się klikając dwukrotnie "ocpl-devel".

• W PuTTy użyj środkowego klawisza myszy do kopiowania zaznaczonego tekstu, prawego do wklejania.

Praca z bazą danych

• Z bazy zostało usuniętych sporo danych m.in. prywatne dane użytkowników, ale nie powinno to przeszkadzać w pracy z kodem OCPL.

• Baza bazuje na dumpie danych z pewnego momentu, więc nazwy użytkowników (oraz wszelkie inne pozostałe dane) mogą być nieaktualne. Nie dziw się więc, że w bazie nie ma któregoś Twojego kesza itp. To są dane tylko i wyłącznie testowe. Większość treści wpisów do logów skrzynek zostało skróconych do 'TFTC' dla zaoszczędzenie miejsca a dysku.

• Możesz uzyskać bardziej aktualną wersję bazy kontaktując się z RT.

• Maszyna posiada zainstalowanego phpmyadmin-a (http://local.opencaching.pl/phpmyadmin/). Logowanie, jak wyżej (root/toor).

• Jak zaaplikować pełny obraz bazy danych OCPL:

  • aktualnie pełny obraz bazy danych RT udostępnia na życzenie
  • taki obraz zwykle jest dosyć duży (aktualnie spakowany ma ~280MB)
  • spakowany dump przegrywamy na maszynę wirtualną (np. przez sftp - na windowsie użyj WinSCP na linuxie np. polecenia scp)
  • na maszynie wirt. wchodzimy do katalogu, w którym się znajduje się przegrany obraz
  • używamy polecenia: zcat <spakowany-obraz-bazy-danych.sql.gz> | mysql -u root --password=toor ocpl -vvv
  • powyższe polecenie prawdopodobnie będzie działać dłuuuugo (np. kilkadziesiąt minut?), ale przynajmniej widać co aktualnie jest wpuszczane do bazy
  • ostatnim niezbędnym krokiem jest regeneracja kafelków mapy - z konsoli wydać należy polecenie: wget "http://localhost/lib/mapper_okapi.php?userid=1&z=0&x=0&y=0" i poczekać na wynik (regeneracja kafelków jest procesem dość długotrwałym - w zależności od wydajności maszyny kilka-kilkanaście min.)

Praca z kodem PHP

• Kod OC leży w /srv/ocpl. Możesz go edytować przez konsolę lub zdalnie, z poziomu hosta). Zobacz też Sposoby edycji zdalnej z Windowsa.

• Sprawdzaj co jakiś czas maile wysyłane do użytkownika user. Pojawiają się w nich komunikaty i informacje o błędach. Wpisz alpine aby uruchomić klienta poczty.

• Jeśli dostajesz "Error 500", to zajrzyj do logów Apache (np. komendą tail /var/log/apache2/error.log). Ostatnia linia w tym logu powie Ci co źle robisz.

Znane problemy (do załatania w następnej edycji VM-ki)

Samba nie jest skonfigurowana

jeśli chcesz używać samby trzeba zrobić wpis w pliku /etc/samba/smb.conf:

[ocpl]
path=/srv/
valid users = user
read only = no
write list = user`

później oczywiście restart samby: sudo service samba restart i pod sharem: [\local.opencaching.pl](\local.opencaching.pl) powinien być widoczny katalog z kodem OC

Cookie nie jest zapisywane przez przeglądarkę (nie mozna się zalogować do lokalnego OC)

problem wynika z faktu, że chrome (i może nie tylko) banuje strony bez ssl-a (nie po https) włączenie ssl-a lokalnie jest nieco skomplikowane, ale możliwe (co przećwiczyłem) - w skrócie trzeba wygeenerować lokalny certyfikat, skonfigurować apache-a i dodać certyfikat w chrome i śmiga

przydatne linki:

• https://www.akadia.com/services/ssh_test_certificate.html
• https://certificatetools.com/newui/

Czegoś brakuje?

Jeśli czegoś Ci brakuje na naszej wirtualnej maszynie, napisz nam o tym. Być może w następnej wersji dodamy. Aktualna lista rzeczy do dodania.