Wstęp

Powyższy dokument ma pełnić funkcję dokumentacji aplikacji wykorzystywanych w firmie OEX Cursor.

Rozwijanie dokumentu

Dokument jest generowany poprzez generator stron statycznych MdBook na podstawie plików markdown ułożonych w określonej hierarchi. Wszelakie informacje dotyczące sposobu rozwijania dokumentu są dostępne na stronie projektu.

Start

Aplikację należy pobrać z dedykowanego jej repozytorium na GitHub:

• Instacja git oraz pobranie projektu

Aplikacje można uruchomić za pomocą następujących sposobów:

• Start zautymatyzowany
• Start manualny

Zalecane jest korzystanie z startu zautomatyzowanego jeżeli jednak występują jakieś problemy np. niekompatybilność systemu plików należy to do nas zgłosić i jeżeli to możliwe postąpić do tego momentu odpowiednio alternatywnie do startu manualnego.

Pobranie aplikacji

Wygenerowanie klucza na GitHub

Aby sklonować repozytorium trzeba najpierw wygenerować klucz (token), który zostanie użyty do uwierzytelnienia

• Po zalogowaniu się na Github, należy rozsunąć panel z prawej strony i kliknąć Settings

  

• W ustawieniach, w panelu z lewej strony wybrać Developer settings

  

• Następnie rozwinąć zakładkę Personal access tokens

  

• Wybrać Tokens (classic) i kliknąć Generate token

  

Instalacja Git i pobranie projektu

Windows

• Należy pobrać Git Bash for Windows z oficjalnej strony i zainstalować
• W wybranym folderze kliknąć prawy przycisk myszy i wybrać z menu kontekstowego Git Bash

• Sklonować repozytorium komendą

git clone https://github.com/DataScience360/Cursor.git

• Gdy pojawi się ekran logowania jako login trzeba podać email powiązany z kontem GitHub, a jako hasło użyć wcześniej wygenerowanego tokenu

Linux

• Należy otworzyć terminal
• Odświerzyć lokalny indeks pakietów, aby mieć pewność, że zostanie pobrany najnowsza wersja Git:

sudo apt-get update

• Przejść w terminalu do wybranego folderu i sklonować repozytorium:

cd sciezka/do/folderu
git clone https://github.com/DataScience360/Cursor.git

• Gdy pojawi się ekran logowania jako login trzeba podać email powiązany z kontem GitHub, a jako hasło użyć wcześniej wygenerowanego tokenu

Zautomatyzowany start

Taskfile

Powyższe zadania mogą być zautomatyzowane poprzez wykorzystanie programu Taskfile.

Instalacja

Instalacja Mac OS X

brew install go-task

Instalacja Windows

winget install Task.Task

Instalacja Linux/WSL

sh -c "$(curl --location https://taskfile.dev/install.sh)" -- -d -b ~/.local/bin

Sprawdzenie poprawności instalacji

Po instalacji programu użytkownik powinien upewnić się czy program został aby na pewno poprawnie zainstalowany. Przykładowo uruchomienie terminala i wpisanie komendy task --version powinno pokazać obecną wersję programu:

❯ task --version
3.43.3

Jeżeli program nie został odnaleziony tj. wystąpiła sytuacja poniżej:

<nazwa_powloki>: command not found: task

Oznacza to, że powłoka nie jest w stanie znaleźć programu task i należy dodać go do zmiennej środowiskowej PATH.

export PATH="./local/bin/:$PATH" >> <plik_konfiguracyjny_powloki>

Gdzie plikiem konfiguracyjnym powłoki może być:

• ~/.zshrc
• ~/.bashrc

Wprowadzenie zmian umożliwi komenda

Struktura pliku Taskfile.yml

Katalog główny projektu zawiera plik Taskfile.yml, który to z kolei zawiera definicje zadań jakie mogą zostać wykonane. Przyjrzyjmy się jednemu z tych zadań:

tasks:
    default:
       cmds:
           - task: run:dev

Powyższe zadanie jest zadaniem głównym tzn. uruchamia się ono po wpisaniu komendy task składa się z innego zadania run:dev, rzućmy na nie okiem.

Upewniwszy się, że jesteśmy w katalogu głównym aplikacji lub też w dowolnym katalogu 'dziecku' projektu. Spróbujmy uruchomić główne zadanie.

❯ task
Script require root access in order to append hosts to /ect/hosts
Backup is created in same directory just in case if something bad happened!
127.0.0.1 aplikacje121.local was not found in your /etc/hosts
::1 aplikacje121.local was not found in your /etc/hosts
127.0.0.1 wysylki121.local was not found in your /etc/hosts
::1 wysylki121.local was not found in your /etc/hosts
127.0.0.1 wysylki121test.local was not found in your /etc/hosts
::1 wysylki121test.local was not found in your /etc/hosts
127.0.0.1 eventyb.local was not found in your /etc/hosts
::1 eventyb.local was not found in your /etc/hosts
127.0.0.1 filesbat.local was not found in your /etc/hosts
::1 filesbat.local was not found in your /etc/hosts
127.0.0.1 rekrutacje121.local was not found in your /etc/hosts
::1 rekrutacje121.local was not found in your /etc/hosts
127.0.0.1 rozliczeniabat.local was not found in your /etc/hosts
::1 rozliczeniabat.local was not found in your /etc/hosts
.
.
.
task: [run:dev] docker compose up -d
[+] Running 12/12
 ✔ Network cursor_default                 Created                                                                                                                     0.0s
 ✔ Container cursor-web-1                 Started                                                                                                                     0.5s
 ✔ Container cursor-rozliczenia_db-1      Started                                                                                                                     0.3s
 ✔ Container cursor-files_bat_db-1        Started                                                                                                                     0.5s
 ✔ Container cursor-magazyn_db-1          Started                                                                                                                     0.5s
 ✔ Container cursor-eventy_db-1           Started                                                                                                                     0.6s
 ✔ Container cursor-rekrutacja_db-1       Started                                                                                                                     0.3s
 ✔ Container cursor-sso_db-1              Started                                                                                                                     0.3s
 ✔ Container cursor-horeca_db-1           Started                                                                                                                     0.6s
 ✔ Container cursor-mailcrab-1            Started                                                                                                                     0.6s
 ✔ Container cursor-rekrutacja_test_db-1  Started                                                                                                                     0.5s
 ✔ Container cursor-magazyn_test_db-1     Started                                                                                                                     0.3s

Zadanie wpierw uruchamia skrypt dodający fałszywe domeny na sam koniec powinien powiadomić nas o uruchomieniu komendy.

Nazwy hostów znajdują się w pliku taskfile spróbuj udać się na jedną ze stron znajdujących się w pliku taskfile.

# Taskfile.yaml
HOSTS: [
    aplikacje121.local,
    wysylki121.local,
    wysylki121test.local,
    eventyb.local,
    filesbat.local,
    rekrutacje121.local,
    rozliczeniabat.local,
    rozliczeniatest.local,
    zamowieniabat.local,
    zamowieniabattest.local,
]

Poprzez wpisanie jednego z adresów np. http://rozliczeniabat.local

Uruchamianie aplikacji w trybie deweloperskim

definicja run:dev zawiera:

• opis zadania: Uruchamianie kontenerów dla trybu deweloperskiego
• 2 zadania configure:hosts:dev do usuwania hostów i ich dodawania
• komende docker compose uruchamiającą kontenery w trybie detached czyli kontenery nie będą pracować w głównej sesji powłoki (prościej mówiąc nie ujrzymy domyślnie ich logów).

# Definicja uruchamiania aplikacji w trybie deweloperskim
run:dev:
  desc: Runs containers for development
  aliases: [rd]
  cmds:
    - task: configure:hosts:dev:delete
    - task: configure:hosts:dev:add
    - docker compose up -d {{.CLI_ARGS}}

Trzy komendy uruchamiające aplikację w trybie deweloperskim:

task
task run:dev
task rd

Zatrzymywanie aplikacji w trybie deweloperskim

definicja stop:dev zawiera:

• opis zadania: Zatrzymywanie kontenerów pracujących w trybie deweloperskim
• zadanie configure:hosts:dev:delete do usuwania hostów
• komende docker compose down zatrzymującą kontenery

stop:dev:
    desc: Stops containers for development if they are already running
    aliases: [sd]
    vars:
      CONTAINER: 'cursor-web-1'
    preconditions:
      - docker ps --filter "name={{.CONTAINER}}" | grep {{.CONTAINER}}
    cmds:
      - task: configure:hosts:dev:delete
      - docker compose down

# Zatrzymywanie kontenerów
task stop:dev
# Można także użyć skrótu (alias)
task sd

Przebudowywanie kontenerów

Jeżeli do pliku Dockerfile naniesiono jakieś zmiany, należy dokonać przebudowy obrazu. Aby uruchomić aplikację wraz z przebudową obrazu użyj poniższej komendy:

# Forwardowanie flag do komendy '{{.CLI_ARGS}}'
task rd -- --build
# albo
task run:dev -- --build

Manualny start

Do uruchomienia aplikacji potrzebne są następujące narzędzia:

• Docker
• Docker compose
• W przypadku uruchomienia aplikacji na Windows - WSL (Windows Subsystem for Linux)

Dodatkowe kroki dla Microsoft Windows

W przypadku korzystania z Windowsa, należy zainstalować najpierw WSL. Można to zrobić na kilka sposobów:

• WinGet:
  • W najnowszych wersjach Microsoft Windows WinGet jest zainstalowany fabrycznie, jednak jeśli wersja Windows jest starsza niż 10, możliwe, że konieczne będzie zainstalowanie go samemu, można go pobrać z Microsoft Store
  • Uruchomić Windows PowerShell (najlepiej jako administrator) i wpisąć poniższą komendę:

winget install --id=Microsoft.WSL  -e

• Chocolatey:
  • Należy pobrać Chocolatey z oficjalnej strony i zainstalować
  • Uruchomić Windows PowerShell (najlepiej jako administrator) i wpisąć poniższą komendę:

choco install wsl2

• Lub pobrać WSL z Microsoft Store:

Dodanie adresów ip do pliku hosts

Windows

• Należy wejść w C:\Windows\System32\drivers\etc
• Następnie otworzyć plik hosts w dowolnym edytorze tekstu, a następnie wkleić poniższe adresy:

127.0.0.1 aplikacje121.local
::1 aplikacje121.local
127.0.0.1 wysylki121.local
::1 wysylki121.local
127.0.0.1 wysylki121test.local
::1 wysylki121test.local
127.0.0.1 eventyb.local
::1 eventyb.local
127.0.0.1 filesbat.local
::1 filesbat.local
127.0.0.1 rekrutacje121.local
::1 rekrutacje121.local
127.0.0.1 rozliczeniabat.local
::1 rozliczeniabat.local
127.0.0.1 rozliczeniatest.local
::1 rozliczeniatest.local
127.0.0.1 zamowieniabat.local
::1 zamowieniabat.local
127.0.0.1 zamowieniabattest.local
::1 zamowieniabattest.local

Linux

• Należy uruchomić terminal i otworzyć plik hosts dowolnym edytorem tekstu np nano:

sudo nano /etc/hosts

• Następnie wkleić poniższe adresy:

127.0.0.1 aplikacje121.local
::1 aplikacje121.local
127.0.0.1 wysylki121.local
::1 wysylki121.local
127.0.0.1 wysylki121test.local
::1 wysylki121test.local
127.0.0.1 eventyb.local
::1 eventyb.local
127.0.0.1 filesbat.local
::1 filesbat.local
127.0.0.1 rekrutacje121.local
::1 rekrutacje121.local
127.0.0.1 rozliczeniabat.local
::1 rozliczeniabat.local
127.0.0.1 rozliczeniatest.local
::1 rozliczeniatest.local
127.0.0.1 zamowieniabat.local
::1 zamowieniabat.local
127.0.0.1 zamowieniabattest.local
::1 zamowieniabattest.local

Dodanie pliku z backupem bazy do projektu

• Otworzyć konsolę Linuxa lub WSL na Windowsie
• Przejść do Cursora

cd sciezka/do/pliku/Cursor

• W przypadku korzystania z WSL należy na początku ścieżki dodać /mnt np:

cd /mnt/C/Users/.../Cursor

• Zainstalować narzędzie CURL

sudo apt install curl

• Z jego pomocą zainstalować task, który posłuży do dodania bazy do projektu

sh -c "$(curl --location https://taskfile.dev/install.sh)" -- -d -b ~/.local/bin

• Zainstalować zip, jeśli nie ma go na urządzeniu

sudo apt install unzip

• Rozpakować zip dumpu bazy danych
• zainstalować kompresor xz i zdekompresować plik

sudo apt install xz-utils
tar -xvf Cursor.tar.xz

• Wywołać wcześniej pobrany task

task

• Jeśli komenda nie zadziała dodać:

export PATH="~/.bin:$PATH" >> ~/.bashrc
source ~/.bashrc

Dodanie zmiennych środowiskowych

W celu wygenerowania lokalnie odszyfrowanych zmiennych środowiskowych należy użyć komendy poniższej z poziomu głównego folderu projektu (Cursor), po czym wpisać hasło do Ansible Vault przekazane przez DS360.

ansible-playbook generate_env.yml --ask-vault-pass

Po wykonaniu się task-ów w playbook-u, pliki ze zmiennymi środowiskowymi powinny znajdować się w .env_files/development

Uruchomienie aplikacji

Instalacja dockera

Przed wykonaniem dalszych kroków należy zainstalować Dockera

Windows

Plik instalacyjny dockera można pobrać z oficjalnej strony lub z Microsoft Store

Linux

• W konsoli Linuxa:

sudo apt-get update
sudo apt-get install ./docker-desktop-amd64.deb

Uruchomienie

Z poziomu katalogu w którym znajduje się plik compose.yml aplikacja może zostać uruchomiona za pomocą poniższej komendy:

docker compose up

• Jeśli komenda nie zadziała, można spróbować wcześniej uruchomić docker desktop

Poprawne uruchomienie aplikacji powinno wyświetlić następujące informacje:

[+] Running 2/2
 ✔ Network oexcursor_default  Created                                                                         0.1s
 ✔ Container oexcursor-web-1  Created                                                                         0.1s
Attaching to web-1
web-1  | [Tue Apr 22 12:22:41.212074 2025] [mpm_prefork:notice] [pid 7] AH00163: Apache/2.4.41 (Ubuntu) PHP/8.1.32 configured -- resuming normal operations

Plik /etc/hosts powinien zawierać translację ścieżek w następującej postaci:

───────┬───────────────────────────────────────────────────────────────────────
       │ File: /etc/hosts
───────┼───────────────────────────────────────────────────────────────────────
   1   │ ##
   2   │ # Host Database
   3   │ #
   4   │ # localhost is used to configure the loopback interface
   5   │ # when the system is booting.  Do not change this entry.
   6   │ ##
   7   │ 127.0.0.1       localhost
   8   │ 255.255.255.255 broadcasthost
   9   │ ::1             localhost
  10   │
  11   │
  12   │ 127.0.0.1       aplikacje121.local
  13   │ 127.0.0.1       wysylki121.local
  14   │
  15   │ ::1    aplikacje121.local
  16   │ ::1    wysylki121.local
  17   │
───────┴───────────────────────────────────────────────────────────────────────

Następnie kierując się za pomocą przeglądarki internetowej na adres np. http://aplikacje121.local. Powinniśmy zobaczyć stronę głowną tej aplikacji.

korzystanie z aplikacji

Po udanym uruchomieniu aplikacji, aby z niej skorzystać należy w przeglądarce wyszukać http://aplikacje121.local/start

Poruszanie się po aplikacji wymaga logowania, hasłem jest Admin?123

Mail Sender

W celu skorzystania z funkcjonalności MailCrab symulującej działanie skrzynki mailowej należy dostać się poprzez localhost:1080

Dane wrażliwe

Wszelakie dane wrażliwe (bądź też przekierowania) są zawierane w ukrytym pliku .env.

❯ tail .env/development/sso_app
SSO_EMAIL_MAIL_SMTP_PORT=<value>

SSO_MAIL_FROM=<value>
SSO_MAIL_FROM_NAME=<value>
SSO_MAIL_SMTP_USER=<value>
SSO_MAIL_SMTP_PASSWORD=<value>
SSO_MAIL_SMTP_HOSTNAME=<value>
SSO_MAIL_SMTP_PORT=<value>

Przy starcie kontenera wartości te są przypisywane jako zmienne środowiskowe, które można wykorzystywać już z poziomu interpretera języka PHP.

Przykłady

Poniżej znajdują się przykłady zastosowania tych zmiennych środowiskowych.

Konfiguracja bazy danych

<?php

class DATABASE_CONFIG
{
    public array $default;
    public array $db_rekrutacja;
    public array $db_rozliczenia;
    public array $db_magazyn;

    public function __construct()
    {
        $this->default['driver'] = getenv(name: "SSO_DEFAULT_DB_DRIVER", local_only: true) ?: '';
        $this->default['host'] = getenv(name: "SSO_DEFAULT_DB_HOST", local_only: true) ?: '';
        $this->default['login'] = getenv(name: "SSO_DEFAULT_DB_LOGIN", local_only: true) ?: '';
        $this->default['password'] = getenv(name: "SSO_DEFAULT_DB_PASSWORD", local_only: true) ?: '';
        $this->default['database'] = getenv(name: "SSO_DEFAULT_DB_DATABASE", local_only: true) ?: '';
        $this->default['encoding'] = getenv(name: "SSO_DEFAULT_DB_ENCODING", local_only: true) ?: '';

        $this->db_rekrutacja['driver'] = getenv(name: "SSO_REKRUTACJA_DB_DRIVER", local_only: true) ?: '';
        $this->db_rekrutacja['host'] = getenv(name: "SSO_REKRUTACJA_DB_HOST", local_only: true) ?: '';
        $this->db_rekrutacja['login'] = getenv(name: "SSO_REKRUTACJA_DB_LOGIN", local_only: true) ?: '';
        $this->db_rekrutacja['password'] = getenv(name: "SSO_REKRUTACJA_DB_PASSWORD", local_only: true) ?: '';
        $this->db_rekrutacja['database'] = getenv(name: "SSO_REKRUTACJA_DB_DATABASE", local_only: true) ?: '';
        $this->db_rekrutacja['encoding'] = getenv(name: "SSO_REKRUTACJA_DB_PASSWORD", local_only: true) ?: '';

        $this->db_rozliczenia['driver'] = getenv(name: "SSO_ROZLICZENIA_DB_DRIVER", local_only: true) ?: '';
        $this->db_rozliczenia['host'] = getenv(name: "SSO_ROZLICZENIA_DB_HOST", local_only: true) ?: '';
        $this->db_rozliczenia['login'] = getenv(name: "SSO_ROZLICZENIA_DB_LOGIN", local_only: true) ?: '';
        $this->db_rozliczenia['password'] = getenv(name: "SSO_ROZLICZENIA_DB_PASSWORD", local_only: true) ?: '';
        $this->db_rozliczenia['database'] = getenv(name: "SSO_ROZLICZENIA_DB_DATABASE", local_only: true) ?: '';
        $this->db_rozliczenia['encoding'] = getenv(name: "SSO_ROZLICZENIA_DB_PASSWORD", local_only: true) ?: '';

        $this->db_magazyn['driver'] = getenv(name: "SSO_MAGAZYN_DB_DRIVER", local_only: true) ?: '';
        $this->db_magazyn['host'] = getenv(name: "SSO_MAGAZYN_DB_HOST", local_only: true) ?: '';
        $this->db_magazyn['login'] = getenv(name: "SSO_MAGAZYN_DB_LOGIN", local_only: true) ?: '';
        $this->db_magazyn['password'] = getenv(name: "SSO_MAGAZYN_DB_PASSWORD", local_only: true) ?: '';
        $this->db_magazyn['database'] = getenv(name: "SSO_MAGAZYN_DB_DATABASE", local_only: true) ?: '';
        $this->db_magazyn['encoding'] = getenv(name: "SSO_MAGAZYN_DB_PASSWORD", local_only: true) ?: '';
    }
}

Przekierowania

Produkcyjna wersja aplikacji podczas przekierowywania czy to automatycznego czy też za pomocą hiperlinków sprawdza czy istnieje zmienna środowiskowa.

// Jeżeli istnieje deklaracja zmiennej środowiskowej SSO_WYSYLKI_URL (i nie jest ona pustym łańcuchem znakowym) to używamy jej wartości
// w.p. używamy wartości z produkcyjnej ścieżki (do uzgodnienia)
$params['wysylki_url'] = getenv(name: 'SSO_WYSYLKI_URL', local_only: true) ?: 'https://wysylki121.cursor.pl';

Następnie w szablonie pod hiperłącze podstawiana jest ta zmienna (gwarantuje to brak niepożądanego zachowania produkcyjnej wersji).

<a href="<tmpl_var wysylki_url>">

Wyświetlenie wszystkich zmiennych środowiskowych

task print_all_env_vars:dev
# lub
task penvd

Omówienie struktury

❯ ls -l # Wylistowanie wszystkich plików poza ukrytymi
drwxr-xr-x@   - rich 18 Apr 07:23 confs
drwxr-xr-x@   - rich 22 Apr 14:28 docs
drwxr-xr-x@   - rich 22 Apr 09:28 scripts
drwxr-xr-x@   - rich 17 Apr 14:25 sites
.rw-r--r--@ 519 rich 22 Apr 12:23 compose.yaml
.rw-r--r--@ 227 rich 18 Apr 07:24 Dockerfile

Git

Zmiany projektu są śledzonę za pomocą systemu kontroli wersji Git.

❯ ls -al
drwxr-xr-x@   - rich 22 Apr 09:12 .env
drwxr-xr-x@   - rich 22 Apr 14:39 .git
drwxr-xr-x@   - rich 18 Apr 07:23 confs
drwxr-xr-x@   - rich 22 Apr 14:28 docs
drwxr-xr-x@   - rich 22 Apr 09:28 scripts
drwxr-xr-x@   - rich 17 Apr 14:25 sites
.rw-r--r--@ 199 rich 22 Apr 09:28 .dockerignore
.rw-r--r--@  99 rich 22 Apr 10:10 .gitignore
.rw-r--r--@ 519 rich 22 Apr 12:23 compose.yaml
.rw-r--r--@ 227 rich 18 Apr 07:24 Dockerfile
❯ git status
On branch main
Untracked files:
  (use "git add <file>..." to include in what will be committed)
        docs/

nothing added to commit but untracked files present (use "git add" to track)

W celu zaciągania zmian w projekcie z repozytorium bez konieczności każdorazowej autenykacji można wygenerować klucz ssh

Generowanie SSH

• Należy otworzyć terminal Linuxa lub Git Bash na Windowsie i użyć poniższej komendy, jako email dodając ten powiązany z kontem GitHub:

ssh-keygen -t ed25519 -C "your_email@example.com"ssh-keygen -t ed25519 -C "your_email@example.com"

Dodanie wygenerowanego klucza ssh do ssh agent

Windows

ssh-add c:/Users/YOU/.ssh/id_ed25519

Linux

ssh-add ~/.ssh/id_ed25519

Dodanie ssh do konta GitHub

• Należy użyć poleceń

ssh -T git@github.com
cat id_rsa.pub

• Otrzymany po wykonaniu komend klucz należy skopiować i dodać do konta GitHub (settings -> SSH and GPG keys -> new SSH key)

  

Pobieranie zmian

Najnowsze wersje projektu można zaciągnąć z repozytorium przy pomocy poniższych poleceń wpisanych w terminalu Linuxa lub Git Bash

git fetch && git pull origin HEAD