Przejdź do głównej zawartości

Pierwsze kroki

Dwa polecenia wystarczą, żeby na Twoim komputerze działało Endora Commerce: API, panel administracyjny i sklep. Ta strona opisuje te dwa polecenia w całości — o co pyta instalator, co zapisuje, jak uruchomić wynik i gdzie się zalogować — a także ten sam instalator użyty do rozdzielenia tych trzech części na osobne maszyny. Krótka wersja jest w pliku README.md repozytorium.

Czego potrzebujesz​

  • Node.js ≥ 22.18 — package.json instancji deklaruje ten sam zakres, a instalator odmawia startu na starszym Node, zamiast zapisać drzewo, które jego własny manifest odrzuca.
  • pnpm — zapewnia go corepack enable. Bez niego instalator i tak działa: uruchamia przez corepack wersję pnpm przypiętą w tym wydaniu, a każde kolejne polecenie wypisuje w postaci, która wymaga tylko Node i npm — drugie polecenie to wtedy npx --yes pnpm@<wersja> run dev:all. Uruchom to, co wypisze. Jeśli w PATH nie ma ani pnpm, ani corepack, instalator odmawia i mówi dlaczego.
  • Docker z Compose v2 — dla usług deweloperskich (PostgreSQL, Redis, Meilisearch i Mailpit, który przechwytuje pocztę). Niepotrzebny z --no-services, gdy te usługi uruchamiasz samodzielnie.

Dwa polecenia​

npx create-endora-commerce@latest my-shop
cd my-shop && pnpm run dev:all

create-endora-commerce to tylko drzwi wejściowe: przekazuje każdy argument bez zmian do endora install z pakietu @endora-commerce/cli. npx @endora-commerce/cli install my-shop to to samo polecenie, a --help w każdej z tych form wypisuje wszystkie flagi. Nic na tej stronie nie różni się między tymi dwoma zapisami.

Co robi pierwsze polecenie​

W tej kolejności, wypisując każde polecenie przed jego uruchomieniem:

  1. Pobiera pakiety, z których czyta. Gdy obok katalogu docelowego nie ma zainstalowanego nic z Endora Commerce — co pod npx jest normą — najpierw instaluje pakiety tego wydania do katalogu tymczasowego, bo zestaw modułów odczytuje z ich manifestów. Katalog tymczasowy jest usuwany, gdy tylko instancja zostanie zapisana; jeśli to się nie uda, zostaje, a instalator wypisuje jego ścieżkę. Ten krok wykonuje się, zanim cokolwiek trafi do Twojego katalogu, więc błąd w nim zostawia katalog docelowy nietknięty.
  2. Sprawdza maszynę — porty i nazwę projektu Compose, których zamierza użyć — i zmienia to, co jest już zajęte. Zobacz Gdy port albo nazwa są już zajęte.
  3. Zapisuje instancję — zwykły workspace pnpm, który należy do Ciebie. Platforma, powłoka panelu i każdy moduł przychodzą jako zależności; żaden plik platformy nie jest kopiowany do Twojego drzewa.
  4. Zapisuje sklep jako osobne repozytorium obok instancji. Jego pliki przychodzą razem z instalatorem: to kopia sklepu referencyjnego, już przygotowana do samodzielnego działania — zobacz Sklep.
  5. Instaluje zależności instancji i uruchamia usługi deweloperskie przez docker compose, zapisując ich adresy w pliku .env instancji.
  6. Generuje, buduje i migruje, instaluje każdy moduł i tworzy Twojego administratora.
  7. Wgrywa dane demonstracyjne, jeśli o nie poprosisz. Błąd w tym kroku nie przerywa instalacji.
  8. Instaluje zależności sklepu.
  9. Wypisuje, co uruchomić dalej, w tym każdą odpowiedź przyjętą jako rekomendacja i sposób jej odwrócenia.

Krok, który się nie powiedzie, kończy instalację własnym kodem wyjścia, a instalator wypisuje, co zostało do zrobienia, zaczynając od tego właśnie kroku — możesz więc dokończyć ręcznie. Hasło administratora nigdy nie jest wypisywane: tam, gdzie polecenie go wymaga, lista pokazuje <password>, a Ty wpisujesz w to miejsce swoje.

Co dostajesz​

Dwa katalogi obok siebie, oba Twoje:

KatalogCo to jest
my-shop/Instancja: package.json (lista modułów; każdy pakiet wydania dokładnie w wersji, którą instalujesz), backend/ (punkty wejścia API i workera), admin/, docs/, apps/my-shop/ (Twoje własne moduły — zobacz Utwórz swój pierwszy moduł), deploy/ (przykładowe pliki produkcyjne), compose.dev.yml i .env.
my-shop-storefront/Sklep — aplikacja Next.js z własnym plikiem .env.

Po pnpm run dev:all:

CoAdres
Sklephttp://localhost:3000
APIhttp://localhost:3001opis API jest w panelu administracyjnym w System → Opis API
Panel administracyjnyhttp://localhost:3002zaloguj się adresem e-mail administratora i hasłem podanym podczas instalacji
Mailpithttp://localhost:8025każda wiadomość e-mail wysłana przez instancję w trybie deweloperskim

To wartości domyślne. Jeśli instalator zmienił któryś port, podsumowanie na końcu wypisuje wybrany adres — i to ten należy otworzyć.

Jakie moduły instaluje​

Bez --module instalator instaluje każdy moduł zestawu open source, każdy włączony. Podaje przy tym, ile ich jest i dlaczego. Wszystko, czego nie używasz, możesz wyłączyć w panelu na ekranie Modules (/platform/modules): wyłączony moduł zachowuje się tak, jakby nie był zainstalowany, zachowuje swoje dane i wraca w tym samym stanie, gdy włączysz go ponownie. Niektórych modułów nie da się wyłączyć, bo platforma bez nich nie działa; ekran Modules pokazuje, których.

Lista modułów nie jest tu powtarzana — to sekcja Moduły tej witryny, generowana z samych modułów.

--module <id> (wielokrotnie lub po przecinku) instaluje zamiast tego jawnie wskazany zestaw. Zestaw jest uzupełniany o zależności wskazanych modułów i zostaje odrzucony, jeśli pomija moduł, bez którego platforma nie działa. Większość osób tego nie potrzebuje: wyłączenie modułu to jedno kliknięcie, a dodanie modułu, którego nie zainstalowano, to edycja manifestu, instalacja i migracja.

O co pyta​

W terminalu instalator pyta o to, na co nie odpowiedziały Twoje flagi — to siedem pytań, gdy instaluje wszystkie części. Pytanie, na które odpowiedziała flaga, nie pada; instalator raz, przed pierwszym pytaniem, mówi, które odpowiedzi wziął z flag. Enter przyjmuje rekomendację tam, gdzie ona jest, a podsumowanie na końcu wymienia każdą rekomendację przyjętą w ten sposób.

PytanieRekomendacja (Enter)Flaga, która na nie odpowiada
W którym katalogu zapisać./endora-commerceargument <dir>
Które części działają na tej maszyniewszystkie--only <component>, --without <member>, --no-storefront, --storefront-dir <path>
Czy uruchomić usługi deweloperskietak--no-services
Czy wgrać dane demonstracyjnebrak — musisz odpowiedzieć--demo lub --no-demo
E-mail administratorabrak--admin-email <address>
Hasło administratora, co najmniej 12 znakówbrak--admin-password <secret>
Imię i nazwisko administratorabrak--admin-first-name <text>, --admin-last-name <text>

Części to lista do zaznaczenia: trzy komponenty, które instalator może przygotować — api, admin i storefront — oraz docs, witryna dokumentacji Twojej instancji. Między wierszami przechodzisz strzałkami, Spacja zaznacza lub odznacza wiersz, Enter zatwierdza. (Terminal, który nie potrafi przerysować listy — TERM=dumb — pokazuje ją z numerami: wpisz numer wiersza, żeby go przełączyć.) O hasło krótsze niż 12 znaków instalator pyta od razu ponownie, a podane przez --admin-password odrzuca, zanim cokolwiek zapisze. Pozostawienie wszystkich wierszy zaznaczonych to instalacja opisana dotąd na tej stronie. Odznaczenie komponentu jest tym samym, co wskazanie pozostałych przez --only: instalator pomija wtedy pytania, które przestały mieć sens, a zamiast nich pyta, gdzie są pozostałe komponenty — zobacz Komponenty na osobnych maszynach. docs pomija się przez --without docs. Sklep jest zapisywany w katalogu obok instancji, domyślnie <dir>-storefront — nigdy wewnątrz niej, gdzie wchłonąłby go workspace instancji.

Dane demonstracyjne celowo nie mają rekomendacji. Sklep, który oceniasz, potrzebuje katalogu, klientów i zamówień, zanim zobaczysz pierwszy ekran; sklep, w którym będziesz sprzedawać, nie potrzebuje żadnych. Pusta odpowiedź powoduje ponowne pytanie. --demo dodaje też do listy modułów jeden pakiet, @endora-commerce/demo-composition: to on łączy przykładowe dane modułów w jeden sklep — produkty demonstracyjne sprzedawane w domyślnym kanale, administratorów demonstracyjnych z przypisanymi rolami. Jeśli zmienisz zdanie, pnpm add -w @endora-commerce/demo-composition, a potem pnpm run cli demo seed dodają dane demonstracyjne, a pnpm run cli demo reset je wycofuje, nie ruszając Twoich własnych danych. Reset usuwa też to, co powstało podczas korzystania z demo w ramach organizacji demonstracyjnej — zamówienia złożone przez jej kupującego, zapisane adresy, koszyki, zapytania ofertowe i podobne dane — bo organizacja, do której należą, jest usuwana razem z nimi. Dane innych organizacji nigdy nie są ruszane, podobnie jak wiersze nienależące do żadnej organizacji, na przykład koszyk gościa.

Dotyczy to także tekstu innej organizacji, który wskazuje dokument demonstracyjny. Gdy jedna z Twoich szans sprzedaży lub jeden z Twoich projektów wspomina w opisie, notatce lub wiadomości zamówienie albo zapytanie ofertowe z demo, odwołanie zostaje w tekście po resecie i jest pokazywane jako Zamówienie niedostępne lub Zapytanie ofertowe niedostępne, bez numeru i bez linku: reset nigdy nie edytuje danych innej organizacji, więc nie przepisuje też tego tekstu. Jeśli chcesz usunąć wzmiankę, zmień tekst.

Cały reset to jedna transakcja: albo kończy się w całości, albo niczego nie zmienia. Gdy zostaje odrzucony, sklep nadal działa, a komunikat mówi, co go odrzuciło.

Reset odmawia, gdy organizacja demonstracyjna ma zapisy finansowe, i podaje, ile których znalazł. Liczy się:

  • płatność w statusie paid, refunded lub partially_refunded;
  • faktura rodzaju invoice lub correction — albo dowolnego rodzaju, jeśli ma numer referencyjny KSeF lub zewnętrzną referencję dokumentu, albo została wysłana do systemu księgowego;
  • każdy zapis systemu księgowego (invoice_ledger_*);
  • zwrot środków, także rozliczony z limitem kupieckim.

Zamówienia złożone i nieopłacone się nie liczą: płatność otwierana przy złożeniu zamówienia (awaiting_payment, a przy limicie kupieckim deferred) i jego faktura pro forma są wycofywane razem z zamówieniem, podobnie jak płatności nieudane i dokumenty WZ. Jeśli dane instancji są jednorazowe, usuń zapisy finansowe razem z resztą:

pnpm run cli demo reset --force-delete-financial-records

Flaga jest odczytywana wyłącznie z tego wiersza poleceń — nie ma dla niej zmiennej środowiskowej ani ustawienia — i nie pomija żadnego innego sprawdzenia.

Administrator nigdy nie jest generowany. Hasło to jedyna wartość, którą musisz zapamiętać, więc nic nie wymyśla go za Ciebie i nic innego nie tworzy konta. Hasło nie jest widoczne podczas wpisywania i żaden krok go nie wypisuje.

Bez pytań​

Z --non-interactive, z --dry-run, w CI albo bez podłączonego terminala instalator o nic nie pyta: każda odpowiedź to flaga. Jeśli którejś brakuje, instalator kończy się jedną odmową wymieniającą wszystkie brakujące flagi, zamiast zatrzymać się na pierwszej.

npx create-endora-commerce@latest my-shop --non-interactive --no-demo \
--admin-email you@example.com --admin-password "$ADMIN_PASSWORD" \
--admin-first-name Ada --admin-last-name Lovelace

--dry-run wypisuje każdy plik i każdy krok, nic nie zapisuje w Twoim katalogu i niczego nie uruchamia. Jeśli potrzebuje pakietów wydania, nadal instaluje je do katalogu tymczasowego (bez tego nie da się ustalić zestawu modułów), usuwa go i o tym informuje.

Gdy port albo nazwa są już zajęte​

Komputer, na którym działa już jakiś PostgreSQL, inny sklep albo druga instancja, to zwykła sytuacja, dlatego instalator sprawdza to, zanim cokolwiek zapisze.

  • Usługi deweloperskie. Jeśli port, który publikuje któraś z nich, jest zajęty — na przykład przez inny PostgreSQL na 5432 — instalator wybiera wolny, zapisuje go w .env instancji w zmiennej, którą czyta Compose (POSTGRES_PORT, REDIS_PORT, MEILISEARCH_PORT, MAILPIT_SMTP_PORT, MAILPIT_UI_PORT), wyprowadza z niego adres usługi i o tym informuje. Portu, który samodzielnie ustawisz w .env, nigdy nie zmienia: jeśli jest zajęty, instalator zatrzymuje się, niczego nie zapisując.
  • API, panel i sklep (3001, 3002, 3000). Zajęty port domyślny zostaje zastąpiony wolnym — pierwszym wolnym, licząc od domyślnego plus 10000, czyli 13001 — i zapisany jako PORT tam, skąd dana warstwa go czyta: w .env instancji, w admin/.env, w .env sklepu. Wszystko, co wskazuje ten adres, zmienia się razem z nim: panel jest budowany pod nowy adres API, wskazują go oba adresy backendu w sklepie, a CORS_ALLOWED_ORIGINS w API wpuszcza przeniesiony panel i sklep. Publicznego adresu podanego flagą instalator nigdy nie przepisuje: z --api-url albo --public-url zmienia się tylko PORT, a panel i sklep nadal są budowane pod adres podany flagą. PORT, który ustawisz samodzielnie, jest używany bez zmian; jeśli port API jest zajęty, mówi o tym podsumowanie na końcu.
  • Projekt Compose. Compose nazywa projekt tak jak jego katalog, więc dwie instancje o nazwie shop dzieliłyby jeden zestaw kontenerów i jedną bazę danych. Jeśli projekt o tej nazwie ma już na tej maszynie kontenery albo wolumeny, usługi deweloperskie dostają własną nazwę (<dir>-<sześć znaków>), zapisaną w .env jako COMPOSE_PROJECT_NAME i podaną w wyniku instalatora. pnpm run dev:services i dev:services:down jej używają, bo Compose czyta ten plik. Wartości COMPOSE_PROJECT_NAME, którą ustawisz samodzielnie, instalator nigdy nie zastępuje: jeśli jest zajęta, odmawia.

Komponenty na osobnych maszynach​

W większej instalacji API, panel administracyjny i sklep działają każde na własnym serwerze. Taką instalację opisują dwie rzeczy i obie podaje się instalatorowi flagami: które komponenty to uruchomienie instaluje na tej maszynie (--only) oraz pod jakimi adresami przeglądarka znajduje wszystkie trzy — każdy pod własną nazwą albo wszystkie na jednym hoście, pod różnymi ścieżkami.

Które komponenty instaluje to uruchomienie​

--only wskazuje komponenty, które to uruchomienie instaluje na tej maszynie. O tym, gdzie są pozostałe, instalator dowiaduje się z ich adresów (origin) — schemat i host, opcjonalnie port, bez ścieżki (https://api.example.com).

# on the API server
npx create-endora-commerce@latest api --only api --no-demo \
--api-url https://api.example.com \
--admin-url https://admin.example.com --storefront-url https://shop.example.com \
--admin-email you@example.com --admin-password "$ADMIN_PASSWORD" \
--admin-first-name Ada --admin-last-name Lovelace

# on the admin server — no database, no service, no administrator
npx create-endora-commerce@latest admin --only admin --api-url https://api.example.com

# on the storefront server — no instance at all
npx create-endora-commerce@latest shop --only storefront \
--api-url https://api.example.com --storefront-url https://shop.example.com \
--revalidate-secret "$REVALIDATE_SECRET"
--onlyZapisane w <dir>SklepCo uruchamiaWymagane poza <dir>
(brak) albo wszystkie trzyinstancjaobok niejwszystko z tej stronyadministrator, --demo albo --no-demo
apiinstancja, bez projektu adminbrakinstalacja, usługi, setup, administrator, dane demonstracyjne na życzenieadministrator, --demo albo --no-demo
api,admininstancjabrakjak apijak api
api,storefrontinstancja, bez projektu adminobok niejjak api, potem instalacja sklepujak api
admininstancja, z projektem backendbrakpnpm install, pnpm run build:admin--api-url
storefrontsam sklep — bez instancjiw <dir>pnpm install sklepu--api-url, --storefront-url, --revalidate-secret
admin,storefrontinstancja, z projektem backendobok niejpnpm install, pnpm run build:admin, instalacja sklepuoba wiersze powyżej

Bez api instalator nie dotyka żadnej bazy danych. Nie uruchamia żadnej usługi, niczego nie migruje, nie tworzy administratora i nie wgrywa danych — a flagi, które mają sens tylko z API (--demo, --no-demo, --admin-email i pozostałe flagi administratora, --no-services), odrzuca, zamiast je ignorować. Gdy instalator nie zapisuje instancji, z tego samego powodu odrzuca --without, --module, --deployment i --topology.

Sam panel to wciąż to samo drzewo instancji. Ekrany panelu pochodzą z pakietów modułów zainstalowanych w instancji, więc panel budowany osobno nadal potrzebuje tej listy: instalator zapisuje całe drzewo, razem z projektem backend, wykonuje pnpm install i buduje z niego jedną rzecz — admin/dist. Adres API trafia do admin/.env jako VITE_API_BASE_URL. Katalog admin/dist możesz serwować przez pnpm run preview:admin albo dowolnym serwerem plików statycznych, który na nieznane ścieżki odpowiada plikiem index.html.

Sam sklep dostaje sekret — nigdy nowy. REVALIDATE_SECRET to jedna wartość przechowywana na dwóch maszynach. Instalacja, której --only wymienia api, a nie storefront, generuje ją raz (albo zapisuje tę, którą podasz), umieszcza w .env instancji, mówi, w którym pliku, i jej nie wypisuje. Instalacja całej instancji z --no-storefront nie generuje jej wcale — zobacz Dodanie sklepu później. Skopiuj ją stamtąd do --revalidate-secret na maszynie sklepu. --sales-channel <code> wskazuje kanał sprzedaży, w którym sprzedaje sklep; pominięta oznacza default — kod, z którym platforma tworzy swój domyślny kanał.

W terminalu te same wybory są pytaniami. Odznacz komponent na liście części, a instalator zapyta, pod jakimi adresami dostępne są wszystkie trzy — każdy pod własnym albo wszystkie pod jednym, ze ścieżkami — a potem o adresy, których ten układ wymaga. Bez API pyta o adres API, a w przypadku sklepu także o adres samego sklepu, kod kanału sprzedaży i REVALIDATE_SECRET (niewidoczny podczas wpisywania). Z API proponuje trzy adresy z wartościami deweloperskimi, a Enter zostawia każdy z nich bez zmian.

Gdy podany adres jest adresem localhost z portem — --storefront-url http://localhost:4000 — jest to zarazem port, na którym ten komponent działa na tej maszynie: instalator zapisuje go jako PORT tam, skąd komponent go czyta. Wyjątkiem jest adres localhost podany jako --public-url: jego port należy do reverse proxy, więc żaden komponent go nie zajmuje.

Pod jakimi adresami są dostępne​

Obsługiwane są dwa układy. W obu wszystkie trzy komponenty pozostają w jednej witrynie (same-site), czego wymagają ciasteczka sesji.

Każdy pod własną nazwą​

api.example.com, admin.example.com, shop.example.com. To właśnie opisują --api-url, --admin-url i --storefront-url, jak w przykładzie powyżej. Trzy nazwy muszą należeć do jednej rejestrowalnej domeny.

Jeden host, ze ścieżkami​

Sklep pod /, panel pod /admin, API pod /api:

npx create-endora-commerce@latest my-shop --public-url https://example.com

--public-url to trzy adresy w jednej fladze — --api-url https://example.com, --storefront-url https://example.com i --admin-url https://example.com/admin — i podana obok którejkolwiek z tych trzech jest odrzucana. Działa zarówno z --only, na każdej maszynie po kolei, jak i bez niej — gdy wszystkie trzy komponenty stoją na jednej maszynie za jednym reverse proxy.

Trzy rzeczy są w tym układzie inne:

  • Adresem API jest sam host, a nie https://example.com/api. Ścieżki API i tak zaczynają się od /api/v1, więc to, co odpowiada na hoście, przekazuje /api/ dalej bez zmian. --api-url ze ścieżką jest odrzucana — z takim właśnie wyjaśnieniem.
  • Panel jest budowany pod swoją ścieżkę. Instalator zapisuje ADMIN_BASE_PATH=/admin/ w admin/.env; adresy zasobów panelu i adresy jego ekranów zaczynają się właśnie tam. Podobnie jak adres API, ta wartość jest ustalana w chwili budowania panelu. --admin-url przyjmuje dowolną ścieżkę bazową (https://example.com/back-office), nie tylko /admin.
  • Coś musi kierować ruch według ścieżki, a podsumowanie na końcu wymienia trasy: /api/ i /assets/file/ do API; dokładnie /api/revalidate do sklepu (to jedyna trasa pod /api należąca do sklepu); /admin/ do panelu, z plikiem index.html dla każdej ścieżki, której panel nie ma; wszystko pozostałe do sklepu. Plik deploy/nginx.paths.example.conf w instancji to te same trasy zapisane dla nginx.

W tym układzie żądania przeglądarki są same-origin, więc CORS_ALLOWED_ORIGINS — które instalator nadal zapisuje, z tym jednym adresem — ma znaczenie tylko dla klienta spod innego adresu. Strona sklepu pod /admin albo /api nigdy nie będzie osiągalna, więc zarezerwuj oba słowa w ustawieniu zarezerwowanych segmentów modułu cms.

Co maszyny muszą o sobie wiedzieć​

Podsumowanie instalacji, która obejmuje tylko część komponentów, wypisuje poniższe punkty. Żadnego z nich nie da się sprawdzić z jednej maszyny, bo druga strona każdego jest gdzie indziej.

  1. API wpuszcza przeglądarkę według adresu (origin). CORS_ALLOWED_ORIGINS w .env API musi zawierać publiczne adresy panelu i sklepu dokładnie tak, jak wysyła je przeglądarka: schemat, host, port, bez końcowego ukośnika. Zapisują to --admin-url i --storefront-url podane przy instalacji API; adres, którego nie podasz, zostaje przy wartości deweloperskiej (http://localhost:3002, http://localhost:3000).
  2. Adres API jest ustalany w chwili budowania panelu i sklepu. VITE_API_BASE_URL i NEXT_PUBLIC_API_BASE_URL trafiają do zbudowanych plików, więc zmiana adresu API oznacza ponowne zbudowanie obu, a nie restart.
  3. Trzy publiczne adresy muszą być same-site — w jednej rejestrowalnej domenie albo na jednym hoście ze ścieżkami. Ciasteczka sesji mają SameSite=Lax, więc przeglądarka nie wysyła ich ze strony w innej witrynie. Nic tego za Ciebie nie sprawdza.
  4. Panel pokazuje ekrany modułów zainstalowanych w jego własnym drzewie. Zbuduj go z tego samego wydania co API i z tą samą listą --module, jeśli API ją dostało.
  5. API i sklep mają jeden REVALIDATE_SECRET, a STOREFRONT_BASE_URL w API to adres sklepu: ta para pozwala API poprosić sklep o odświeżenie strony z cache. Przy dwóch różnych wartościach sklep odrzuca każde odświeżenie, a API zapisuje każdą odmowę w logu jako ostrzeżenie — zobacz Dodanie sklepu później.

Wszystkie flagi​

FlagaCo robi
<dir>Gdzie trafia instancja — albo sklep, z --only storefront. Katalog musi być pusty albo zawierać wyłącznie umieszczony przez Ciebie plik .env.
--only <component>Które z api, admin, storefront to uruchomienie instaluje na tej maszynie. Wielokrotnie albo po przecinku. Brak: wszystkie trzy.
--public-url <origin>Jeden host ze ścieżkami: sklep pod /, panel pod /admin, API pod /api. Zastępuje trzy poniższe flagi adresów; podana obok którejkolwiek z nich jest odrzucana.
--api-url <origin>Publiczny adres API. Wymagana, gdy w --only nie ma api; z api — adres, który API dostaje jako własny publiczny.
--admin-url <origin>[/<path>]Gdzie dostępny jest panel. Z api: jego wpis w CORS_ALLOWED_ORIGINS i ADMIN_BASE_URL. Z admin: ścieżka bazowa, pod którą budowany jest panel, jeśli adres ją zawiera.
--storefront-url <origin>Gdzie dostępny jest sklep. Wymagana dla sklepu bez api; z api — wpis na liście adresów dozwolonych przez API i STOREFRONT_BASE_URL.
--sales-channel <code>Kanał sprzedaży, w którym sprzedaje sklep instalowany bez api. Domyślnie default.
--revalidate-secret <secret>Sekret wspólny dla API i sklepu. Wymagana dla sklepu bez api; w pozostałych przypadkach, gdy jej nie podasz, sekret jest generowany raz, zapisywany i nigdy nie wypisywany.
--admin-email, --admin-password, --admin-first-name, --admin-last-nameAdministrator, jako który się logujesz. Wymagane są wszystkie cztery, gdy instalowane jest API.
--demo / --no-demoWgrać przykładowe dane każdego zainstalowanego modułu albo nie. Wymagana, gdy instalowane jest API; bez wartości domyślnej.
--no-servicesNie uruchamiaj PostgreSQL, Redis, Meilisearch ani Mailpit i nie zapisuj ich adresów w .env.
--without <member>Nie zapisuj admin lub docs. Wielokrotnie.
--no-storefrontZapisz samą instancję, bez sklepu obok niej.
--storefront-dir <path>Gdzie trafia sklep. Domyślnie <dir>-storefront; nie może leżeć wewnątrz instancji.
--module <id>Zainstaluj jawnie wskazany zestaw modułów zamiast zestawu open source. Wielokrotnie.
--deployment <name>Katalog w apps/ na Twoje moduły nakładkowe i wartość DEPLOYMENT w .env. Domyślnie: nazwa workspace'u.
--registry <url>Instaluj @endora-commerce/* z tego rejestru — w instancji i w sklepie. W każdym z nich zapisuje .npmrc, który odwołuje się do tokenu przez zmienną środowiskową, nigdy przez wartość.
--topology single-host / three-hostKtóry układ maszyn opisują przykładowe pliki wdrożeniowe w deploy/. Wybiera pliki; nic jej później nie odczytuje.
--non-interactiveNie pytaj o nic, nawet w terminalu.
--dry-runWypisz każdy plik i każdy krok; nic nie zapisuj w katalogu i niczego nie uruchamiaj.

Drugie polecenie: pnpm run dev:all​

Uruchom je w katalogu głównym instancji. W jednym terminalu, z każdą linią oznaczoną nazwą warstwy, startuje:

  • API pod http://localhost:3001 albo na porcie PORT ustawionym w pliku .env instancji;
  • panel — zbudowany podczas instalacji, serwowany na własnym porcie: 3002 albo PORT z admin/.env;
  • sklep, jeśli jest obok instancji w <dir>-storefront — w trybie deweloperskim, na 3000 albo na PORT z jego własnego .env. Sklep w innym miejscu wskazujesz przez pnpm run dev:all --storefront-dir <path>.

Ctrl-C zatrzymuje wszystkie, a jeśli któraś warstwa się zakończy, pozostałe są zatrzymywane i polecenie mówi, która to była. Każda warstwa zachowuje własne polecenie — pnpm run start dla API, pnpm run preview:admin dla panelu, własne pnpm run dev sklepu — i każdą buduje się oraz wdraża niezależnie; dev:all żadnego z nich nie zmienia. pnpm run dev uruchamia samo API i restartuje je, gdy edytujesz własne moduły.

Poczta wysyłana przez instancję w trybie deweloperskim trafia do Mailpit, którego adres wypisuje pierwsze polecenie, i nigdy nie opuszcza Twojego komputera. pnpm run dev:services:down zatrzymuje usługi deweloperskie, zachowując ich dane; pnpm run dev:services uruchamia je ponownie.

Tworzenie administratora​

Instalator tworzy administratora, jako który się logujesz. Każde kolejne konto — dla współpracownika albo w miejsce utraconego — tworzy się z wiersza poleceń i właśnie dlatego ekran logowania panelu odsyła tutaj. Polecenie jest wszędzie to samo; sposób jego wywołania zależy od tego, gdzie działa platforma:

GdziePolecenie
Instancja na Twoim komputerze (z jej katalogu głównego)pnpm run admin:create -- --email=… --password=… --first-name=… --last-name=…
Obraz produkcyjnynode dist/cli.js admin_users create --email=… --password=… --first-name=… --last-name=…, uruchamiane w kontenerze backendu — zobacz D1 listy kontrolnej pierwszego wdrożenia
Klon repozytorium Endora Commercepnpm --filter backend run admin:create -- --email=… --password=… --first-name=… --last-name=…

--password-stdin zamiast --password=… odczytuje hasło ze standardowego wejścia, dzięki czemu nie trafia ono na listę procesów, do polecenia wypisywanego przez menedżer pakietów ani do historii powłoki — instalator tworzy Twojego administratora właśnie w ten sposób.

Konto otrzymuje rolę platform_admin — wszystkie uprawnienia — chyba że przekażesz --role=<code> z kodem istniejącej już roli; sama rola powstaje przy pierwszym uruchomieniu. Ponowne uruchomienie polecenia dla istniejącego adresu e-mail ustawia na nowo hasło, imię i nazwisko oraz rolę tego konta — w ten sposób odzyskuje się też utracone hasło. Jeśli nie masz dostępu do powłoki na maszynie, na której działa platforma, poproś o utworzenie konta osobę, która nią zarządza.

Sklep​

Instalator zapisuje sklep obok instancji, chyba że odznaczysz go w pytaniu o części albo podasz --no-storefront. To kopia sklepu referencyjnego dostarczana razem z instalatorem, więc nie wymaga klonu repozytorium Endora Commerce: każdy plik jest już przepisany tak, by działał samodzielnie, a pakiety @endora-commerce/*, od których zależy, są w wersjach z wydania, które instalujesz. Od tej chwili to Twoje repozytorium i nic nie wysyła żadnych informacji z powrotem. Aktualizowane są tylko jego pakiety @endora-commerce/* — przez pnpm run upgrade w instancji; zobacz Aktualizacja instancji.

W tej kopii pominięto jedną rzecz, a instalator ją wymienia: wzorcowe zrzuty ekranu sklepu referencyjnego, używane w jego testach wizualnych. To obrazy sklepu referencyjnego z maszyny, na której je zapisano; pnpm exec playwright test --update-snapshots zapisuje Twoje własne. Wewnątrz klonu repozytorium sklep jest kopiowany z klonu, razem ze zrzutami.

pnpm run dev:all uruchamia sklep w trybie deweloperskim razem z pozostałymi warstwami. Żeby serwować go tak jak na produkcji, zbuduj go i uruchom w katalogu sklepu:

pnpm run build && pnpm run start

start serwuje to, co zbudowało build, na porcie PORT z pliku .env sklepu; jeśli sklep nie został zbudowany, mówi, żeby uruchomić pnpm run build.

Dodanie sklepu później. Sklep i instancja muszą mieć jeden wspólny sekret, REVALIDATE_SECRET — klucz, którym backend prosi sklep o odświeżenie strony z cache. Gdy instalator zapisuje oba drzewa, generuje tę wartość raz i zapisuje ją w obu. Instalacja z --no-storefront nie generuje jej wcale, zostawia REVALIDATE_SECRET w .env instancji pusty, a jej tekst końcowy mówi o tym i wypisuje poniższe polecenie. Gdy sklep dochodzi później, nic nie uzgodni tej wartości za Ciebie:

  1. Wybierz jedną wartość (na przykład openssl rand -hex 32).

  2. Ustaw ją jako REVALIDATE_SECRET w pliku .env instancji, ustaw tam STOREFRONT_BASE_URL na adres sklepu i uruchom API ponownie.

  3. Zapisz sklep z tą samą wartością — z katalogu instancji, żeby był z tego samego wydania:

    pnpm exec endora install ../my-shop-storefront --only storefront \
    --api-url http://localhost:3001 --storefront-url http://localhost:3000 \
    --revalidate-secret "$REVALIDATE_SECRET"

    Bez --revalidate-secret polecenie odmawia zapisania sklepu. endora new storefront <dir> --revalidate-secret <value> to alternatywa niższego poziomu: kopiuje sklep i rozwiązuje jego dane wejściowe, ale go nie instaluje.

Bez kroku 2 backend po prostu nie prosi sklepu o odświeżanie, a strony zmieniają się dopiero po wygaśnięciu cache. Przy dwóch różnych wartościach sklep odrzuca każde odświeżenie, a API zapisuje w logu ostrzeżenie [storefront-revalidate] refused: REVALIDATE_SECRET differs between the backend and the storefront ze statusem 401 — sama wartość nigdy nie trafia do logu. Sklep, do którego nie da się dotrzeć, jest zapisywany tak samo, jako [storefront-revalidate] failed. Każde ostrzeżenie trafia do logu najwyżej raz na minutę dla danego sklepu i statusu; następne niesie licznik suppressed powtórzeń wstrzymanych w międzyczasie.

Z Twojego komputera na produkcję​

Wszystko powyżej to środowisko deweloperskie: usługi działają w Dockerze na Twoim komputerze, a sklep w trybie deweloperskim. To, czego potrzebujesz do następnego kroku, instancja ma we własnym katalogu deploy/, a każdy plik w nim jest przykładem — nic go nie stosuje i nic go później nie odczytuje. Skopiuj to, czego potrzebujesz, na swoje maszyny i od tej chwili utrzymuj samodzielnie.

  • deploy/README.md — kolejność uruchamiania całości i to, co maszyny muszą o sobie wiedzieć.
  • deploy/Dockerfile.backend i deploy/Dockerfile.admin — przykładowe obrazy dla API (i jego konsumentów kolejek) oraz dla zbudowanego panelu. Budują się z katalogu głównego instancji; polecenia i każdy --build-arg są w nagłówku każdego z plików. Argument DEPLOYMENT obrazu backendu ma domyślnie wartość wdrożenia tej instancji, więc obraz zbudowany bez niego i tak składa Twoje moduły nakładkowe; pusta wartość buduje samą platformę.
  • Przykładowy plik Compose i .env.example dla układu maszyn wybranego przez --topology: single-host (domyślny) umieszcza wszystkie warstwy na jednej maszynie; three-host zapisuje po jednym pliku Compose i jednym .env.example na maszynę — dla backendu, sklepu i panelu.
  • deploy/nginx.example.conf — blok reverse proxy dla każdej publicznej nazwy — oraz deploy/nginx.paths.example.conf, jego odpowiednik dla układu jeden host ze ścieżkami. Użyj jednego albo drugiego.

Zanim instancja przyjmie prawdziwe zamówienia, przejdź listę kontrolną pierwszego wdrożenia produkcyjnego: sekrety do wygenerowania, ustawienia, które możesz wybrać tylko Ty, i dane startowe, których nie wolno wgrać.

Co dalej​