docs(demo): one-command demo setup guide - #1371
Merged
piotrswierzy merged 1 commit intoJul 6, 2026
Merged
Conversation
Detailed walkthrough for the #1352/#1365 Docker demo: prerequisites, example .env (required OPENLINKER_CREDENTIALS_ENCRYPTION_KEY), boot, service URLs, manual PrestaShop + Allegro connection wiring, end-to-end verification, and a troubleshooting table. Linked from the README demo section. Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com> Signed-off-by: norbert-kulus-blockydevs <norbert.kulus@blockydevs.com>
piotrswierzy
pushed a commit
that referenced
this pull request
Jul 7, 2026
…staShop) (#1365) * feat(demo): one-command Docker demo environment (API/Web/Worker + PrestaShop) Add a dedicated demo overlay that boots the full OpenLinker stack in Docker with a single command, on top of the existing infra services. - Dockerfile: new worker build target; also fixes a pre-existing blocker where the ksef/infakt workspace manifests + dist were never copied, so the image build failed outright (unnoticed because CI does not build the image). - apps/web/Dockerfile + nginx.conf: static SPA build served by nginx with SPA-fallback routing; VITE_API_BASE_URL baked at build time. - package.json: demo:up / demo:down / demo:logs scripts. - README.md: demo section (URLs, credentials, manual PS<->OL connection). Closes #1352 Signed-off-by: jakubret <jakub.retajczyk@blockydevs.com> * feat(demo): one-command Docker demo environment (API/Web/Worker + PrestaShop) Add a dedicated demo overlay that boots the full OpenLinker stack in Docker with a single command, on top of the existing infra services. - Dockerfile: new worker build target + apk add bash in base (migrate uses the repo migration:run script, which invokes typeorm via bash); also fixes a pre-existing blocker where the ksef/infakt workspace manifests + dist were never copied, so the image build failed outright (unnoticed because CI does not build the image). - apps/web/Dockerfile + nginx.conf: static SPA build served by nginx with SPA-fallback routing; VITE_API_BASE_URL baked at build time. - package.json: demo:up / demo:down / demo:logs scripts (demo:up includes phpmyadmin). - README.md: demo section (URLs incl. phpMyAdmin, credentials, manual PS<->OL connection). Closes #1352 Signed-off-by: jakubret <jakub.retajczyk@blockydevs.com> * fix(demo): unblock one-command Docker demo boot + PrestaShop networking (#1368) (#1369) Clean-checkout boot of the one-command demo (#1352, PR #1365) surfaced several infra/docs gaps. This is infra + docs only, no domain code. - A2: add start_period (180s) to the mysql healthcheck so first-boot init is not counted against the retry window on slower hosts. - A3: set OL_CORS_ORIGIN=http://localhost:8090 on the demo api service so the web UI (published on :8090) logs in without a CORS NetworkError. - A1: source OPENLINKER_CREDENTIALS_ENCRYPTION_KEY from the environment on migrate/api/worker with a required-var (:?) guard that fails the boot with a clear message; add a root .env.example and README pre-step documenting it (generate with openssl rand -base64 32). - B1: add a PrestaShop post-install step (40-configure-container-network) that registers a prestashop-domain ps_shop_url row and disables the canonical redirect, so the app-tier containers can reach the shop by its compose service name; also document the container-reachable Shop URL. - B2: document the container-reachable Storefront URL requirement for server-side offer image upload, with the browser-thumbnail trade-off noted as a tracked follow-up. - Docs: correct the PrestaShop admin path (/admin -> /admin-dev) and add a louder warning about the demo sharing Compose project + volumes with dev:stack:up. Closes #1368 Signed-off-by: norbert-kulus-blockydevs <norbert.kulus@blockydevs.com> Co-authored-by: Claude Sonnet 5 <noreply@anthropic.com> * docs(demo): add one-command demo setup guide (#1371) Detailed walkthrough for the #1352/#1365 Docker demo: prerequisites, example .env (required OPENLINKER_CREDENTIALS_ENCRYPTION_KEY), boot, service URLs, manual PrestaShop + Allegro connection wiring, end-to-end verification, and a troubleshooting table. Linked from the README demo section. Signed-off-by: norbert-kulus-blockydevs <norbert.kulus@blockydevs.com> Co-authored-by: Claude Sonnet 5 <noreply@anthropic.com> * fix(demo): fix PrestaShop container-network post-install fatal on PS 9 (#1372) * fix(demo): fix PrestaShop container-network post-install fatal on PS 9 Live re-test of #1369 on a fresh PrestaShop 9.0.2 install surfaced two bugs in 40-configure-container-network.php that broke the container's boot (set -e in the wrapper turned the PHP fatal into a hard container exit): 1. ShopUrl::getShopUrls() returns ShopUrl objects under PS 9, not arrays — $row['domain'] threw "Cannot use object of type ShopUrl as array", aborting post-install and exiting the prestashop container (255). Replaced with a direct Db::getInstance()->getValue() existence check (matches the ObjectModel/legacy-bootstrap style already used in this script and its 20-set-default-currency.php sibling). 2. Db::getValue() appends its own trailing `LIMIT 1` internally (via getRow()); the query's own explicit `LIMIT 1` doubled it into `... LIMIT 1 LIMIT 1`, a SQL syntax error (exit 255 again). Verified end-to-end on a from-scratch PrestaShop 9.0.2 install (fresh volume + fresh database): post-install now logs "ShopUrl added for domain 'prestashop'", ps_shop_url carries both the main localhost row and the new non-main 'prestashop' row, PS_CANONICAL_REDIRECT=0, the container stays up (exit 0), and the API container's webservice probe to http://prestashop/api/ returns 401 (reached, no redirect) instead of the prior 301/302 to the canonical localhost domain. Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com> Signed-off-by: norbert-kulus-blockydevs <norbert.kulus@blockydevs.com> * docs(demo): fix .env key recipe (duplicate line, sed portability) The documented .env recipe (README + the setup guide) did `cp .env.example .env` then `echo "KEY=..." >> .env`. .env.example already ships an empty `OPENLINKER_CREDENTIALS_ENCRYPTION_KEY=` line, so appending leaves TWO lines with the same key — harmless (env-file parsing is last-wins) but confusing to anyone editing .env by hand, and flagged in the #1369 review. The guide's proposed fix (sed -i '...') introduced a second problem: GNU sed and BSD sed (macOS) have incompatible -i syntax (BSD requires -i '' <script>), so the documented command would fail outright on macOS. Replaced both with a portable, dependency-free two-liner that drops the example's empty key line and appends the generated one: grep -v '^OPENLINKER_CREDENTIALS_ENCRYPTION_KEY=' .env.example > .env echo "OPENLINKER_CREDENTIALS_ENCRYPTION_KEY=$(openssl rand -base64 32)" >> .env Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com> Signed-off-by: norbert-kulus-blockydevs <norbert.kulus@blockydevs.com> * fix(demo): use ShopUrl object property access instead of raw SQL Addresses PR #1372 review suggestions: revert the idempotency check to ShopUrl::getShopUrls() with property access ($row->domain) instead of a hand-built Db::getInstance()->getValue() raw SQL string. Same idempotency semantics, no manual SQL/pSQL() escaping, and stays consistent with the sibling script's ObjectModel-only convention (also sidesteps the flagged double-quoted SQL string literal / ANSI_QUOTES portability risk, since there's no raw SQL left in this block at all). Signed-off-by: norbert-kulus-blockydevs <norbert.kulus@blockydevs.com> --------- Signed-off-by: norbert-kulus-blockydevs <norbert.kulus@blockydevs.com> Co-authored-by: Claude Sonnet 5 <noreply@anthropic.com> * fix(demo): address PR #1365 review findings Addresses every /pr-review finding from @piotrswierzy, including suggestions: commit .dockerignore (was gitignored, so a fresh clone built with no ignore rules at all — this also uncovered and fixed a real tsc -b failure from a stray host tsconfig.tsbuildinfo leaking into the build context), a CI docker-build smoke job guarding the Dockerfile's per-package COPY lists, loopback-bound demo ports for api/web (default admin/admin ships with no redaction), nginx gzip/cache/security headers, and comments tying the enumerated COPY lists to their source of truth. Signed-off-by: norbert-kulus-blockydevs <norbert.kulus@blockydevs.com> * feat(demo): parameterize domain/secret env vars via .env (#1375) Wires OL_CORS_ORIGIN, VITE_API_BASE_URL, PS_DOMAIN, OL_BOOTSTRAP_ADMIN_PASSWORD, JWT_SECRET, JWT_EXPIRES_IN, and OL_PII_HASH_SALT through ${VAR:-default} interpolation instead of hardcoded literals, so a devops team can point the demo at a real public domain (reverse proxy + TLS) and rotate the throwaway dev secrets purely via .env, without editing the compose files. Unlike OPENLINKER_CREDENTIALS_ENCRYPTION_KEY (${VAR:?required} — no safe default exists for a credentials-encryption key), every variable here defaults to today's exact literal value, so a plain `pnpm demo:up` / `pnpm dev:stack:up` with no .env changes needs no behaviour change. VITE_API_BASE_URL is a Vite build-time arg — .env.example calls out that overriding it only takes effect on the next --build, not a plain restart. PS_DOMAIN is documented as the PUBLIC browser-facing domain only; it does not affect how api/worker reach PrestaShop internally (always the compose service name, http://prestashop). .env.example gains a clearly-separated OPTIONAL section (commented out by default) documenting each variable's purpose and default. Signed-off-by: norbert-kulus-blockydevs <norbert.kulus@blockydevs.com> Co-authored-by: Claude Sonnet 5 <noreply@anthropic.com> --------- Signed-off-by: jakubret <jakub.retajczyk@blockydevs.com> Signed-off-by: norbert-kulus-blockydevs <norbert.kulus@blockydevs.com> Co-authored-by: norbert-kulus-blockydevs <norbert.kulus@blockydevs.com> Co-authored-by: Claude Sonnet 5 <noreply@anthropic.com>
norbert-kulus-blockydevs
added a commit
that referenced
this pull request
Jul 22, 2026
…staShop) (#1365) * feat(demo): one-command Docker demo environment (API/Web/Worker + PrestaShop) Add a dedicated demo overlay that boots the full OpenLinker stack in Docker with a single command, on top of the existing infra services. - Dockerfile: new worker build target; also fixes a pre-existing blocker where the ksef/infakt workspace manifests + dist were never copied, so the image build failed outright (unnoticed because CI does not build the image). - apps/web/Dockerfile + nginx.conf: static SPA build served by nginx with SPA-fallback routing; VITE_API_BASE_URL baked at build time. - package.json: demo:up / demo:down / demo:logs scripts. - README.md: demo section (URLs, credentials, manual PS<->OL connection). Closes #1352 Signed-off-by: jakubret <jakub.retajczyk@blockydevs.com> * feat(demo): one-command Docker demo environment (API/Web/Worker + PrestaShop) Add a dedicated demo overlay that boots the full OpenLinker stack in Docker with a single command, on top of the existing infra services. - Dockerfile: new worker build target + apk add bash in base (migrate uses the repo migration:run script, which invokes typeorm via bash); also fixes a pre-existing blocker where the ksef/infakt workspace manifests + dist were never copied, so the image build failed outright (unnoticed because CI does not build the image). - apps/web/Dockerfile + nginx.conf: static SPA build served by nginx with SPA-fallback routing; VITE_API_BASE_URL baked at build time. - package.json: demo:up / demo:down / demo:logs scripts (demo:up includes phpmyadmin). - README.md: demo section (URLs incl. phpMyAdmin, credentials, manual PS<->OL connection). Closes #1352 Signed-off-by: jakubret <jakub.retajczyk@blockydevs.com> * fix(demo): unblock one-command Docker demo boot + PrestaShop networking (#1368) (#1369) Clean-checkout boot of the one-command demo (#1352, PR #1365) surfaced several infra/docs gaps. This is infra + docs only, no domain code. - A2: add start_period (180s) to the mysql healthcheck so first-boot init is not counted against the retry window on slower hosts. - A3: set OL_CORS_ORIGIN=http://localhost:8090 on the demo api service so the web UI (published on :8090) logs in without a CORS NetworkError. - A1: source OPENLINKER_CREDENTIALS_ENCRYPTION_KEY from the environment on migrate/api/worker with a required-var (:?) guard that fails the boot with a clear message; add a root .env.example and README pre-step documenting it (generate with openssl rand -base64 32). - B1: add a PrestaShop post-install step (40-configure-container-network) that registers a prestashop-domain ps_shop_url row and disables the canonical redirect, so the app-tier containers can reach the shop by its compose service name; also document the container-reachable Shop URL. - B2: document the container-reachable Storefront URL requirement for server-side offer image upload, with the browser-thumbnail trade-off noted as a tracked follow-up. - Docs: correct the PrestaShop admin path (/admin -> /admin-dev) and add a louder warning about the demo sharing Compose project + volumes with dev:stack:up. Closes #1368 Signed-off-by: norbert-kulus-blockydevs <norbert.kulus@blockydevs.com> Co-authored-by: Claude Sonnet 5 <noreply@anthropic.com> * docs(demo): add one-command demo setup guide (#1371) Detailed walkthrough for the #1352/#1365 Docker demo: prerequisites, example .env (required OPENLINKER_CREDENTIALS_ENCRYPTION_KEY), boot, service URLs, manual PrestaShop + Allegro connection wiring, end-to-end verification, and a troubleshooting table. Linked from the README demo section. Signed-off-by: norbert-kulus-blockydevs <norbert.kulus@blockydevs.com> Co-authored-by: Claude Sonnet 5 <noreply@anthropic.com> * fix(demo): fix PrestaShop container-network post-install fatal on PS 9 (#1372) * fix(demo): fix PrestaShop container-network post-install fatal on PS 9 Live re-test of #1369 on a fresh PrestaShop 9.0.2 install surfaced two bugs in 40-configure-container-network.php that broke the container's boot (set -e in the wrapper turned the PHP fatal into a hard container exit): 1. ShopUrl::getShopUrls() returns ShopUrl objects under PS 9, not arrays — $row['domain'] threw "Cannot use object of type ShopUrl as array", aborting post-install and exiting the prestashop container (255). Replaced with a direct Db::getInstance()->getValue() existence check (matches the ObjectModel/legacy-bootstrap style already used in this script and its 20-set-default-currency.php sibling). 2. Db::getValue() appends its own trailing `LIMIT 1` internally (via getRow()); the query's own explicit `LIMIT 1` doubled it into `... LIMIT 1 LIMIT 1`, a SQL syntax error (exit 255 again). Verified end-to-end on a from-scratch PrestaShop 9.0.2 install (fresh volume + fresh database): post-install now logs "ShopUrl added for domain 'prestashop'", ps_shop_url carries both the main localhost row and the new non-main 'prestashop' row, PS_CANONICAL_REDIRECT=0, the container stays up (exit 0), and the API container's webservice probe to http://prestashop/api/ returns 401 (reached, no redirect) instead of the prior 301/302 to the canonical localhost domain. Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com> Signed-off-by: norbert-kulus-blockydevs <norbert.kulus@blockydevs.com> * docs(demo): fix .env key recipe (duplicate line, sed portability) The documented .env recipe (README + the setup guide) did `cp .env.example .env` then `echo "KEY=..." >> .env`. .env.example already ships an empty `OPENLINKER_CREDENTIALS_ENCRYPTION_KEY=` line, so appending leaves TWO lines with the same key — harmless (env-file parsing is last-wins) but confusing to anyone editing .env by hand, and flagged in the #1369 review. The guide's proposed fix (sed -i '...') introduced a second problem: GNU sed and BSD sed (macOS) have incompatible -i syntax (BSD requires -i '' <script>), so the documented command would fail outright on macOS. Replaced both with a portable, dependency-free two-liner that drops the example's empty key line and appends the generated one: grep -v '^OPENLINKER_CREDENTIALS_ENCRYPTION_KEY=' .env.example > .env echo "OPENLINKER_CREDENTIALS_ENCRYPTION_KEY=$(openssl rand -base64 32)" >> .env Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com> Signed-off-by: norbert-kulus-blockydevs <norbert.kulus@blockydevs.com> * fix(demo): use ShopUrl object property access instead of raw SQL Addresses PR #1372 review suggestions: revert the idempotency check to ShopUrl::getShopUrls() with property access ($row->domain) instead of a hand-built Db::getInstance()->getValue() raw SQL string. Same idempotency semantics, no manual SQL/pSQL() escaping, and stays consistent with the sibling script's ObjectModel-only convention (also sidesteps the flagged double-quoted SQL string literal / ANSI_QUOTES portability risk, since there's no raw SQL left in this block at all). Signed-off-by: norbert-kulus-blockydevs <norbert.kulus@blockydevs.com> --------- Signed-off-by: norbert-kulus-blockydevs <norbert.kulus@blockydevs.com> Co-authored-by: Claude Sonnet 5 <noreply@anthropic.com> * fix(demo): address PR #1365 review findings Addresses every /pr-review finding from @piotrswierzy, including suggestions: commit .dockerignore (was gitignored, so a fresh clone built with no ignore rules at all — this also uncovered and fixed a real tsc -b failure from a stray host tsconfig.tsbuildinfo leaking into the build context), a CI docker-build smoke job guarding the Dockerfile's per-package COPY lists, loopback-bound demo ports for api/web (default admin/admin ships with no redaction), nginx gzip/cache/security headers, and comments tying the enumerated COPY lists to their source of truth. Signed-off-by: norbert-kulus-blockydevs <norbert.kulus@blockydevs.com> * feat(demo): parameterize domain/secret env vars via .env (#1375) Wires OL_CORS_ORIGIN, VITE_API_BASE_URL, PS_DOMAIN, OL_BOOTSTRAP_ADMIN_PASSWORD, JWT_SECRET, JWT_EXPIRES_IN, and OL_PII_HASH_SALT through ${VAR:-default} interpolation instead of hardcoded literals, so a devops team can point the demo at a real public domain (reverse proxy + TLS) and rotate the throwaway dev secrets purely via .env, without editing the compose files. Unlike OPENLINKER_CREDENTIALS_ENCRYPTION_KEY (${VAR:?required} — no safe default exists for a credentials-encryption key), every variable here defaults to today's exact literal value, so a plain `pnpm demo:up` / `pnpm dev:stack:up` with no .env changes needs no behaviour change. VITE_API_BASE_URL is a Vite build-time arg — .env.example calls out that overriding it only takes effect on the next --build, not a plain restart. PS_DOMAIN is documented as the PUBLIC browser-facing domain only; it does not affect how api/worker reach PrestaShop internally (always the compose service name, http://prestashop). .env.example gains a clearly-separated OPTIONAL section (commented out by default) documenting each variable's purpose and default. Signed-off-by: norbert-kulus-blockydevs <norbert.kulus@blockydevs.com> Co-authored-by: Claude Sonnet 5 <noreply@anthropic.com> --------- Signed-off-by: jakubret <jakub.retajczyk@blockydevs.com> Signed-off-by: norbert-kulus-blockydevs <norbert.kulus@blockydevs.com> Co-authored-by: norbert-kulus-blockydevs <norbert.kulus@blockydevs.com> Co-authored-by: Claude Sonnet 5 <noreply@anthropic.com>
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
2 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
Adds a detailed setup guide for the one-command Docker demo (#1352 / #1365) at
docs/one-command-demo-setup-guide.md, linked from the README demo section.Covers, step by step:
OPENLINKER_CREDENTIALS_ENCRYPTION_KEY) with an example.envand how to generate it, plus a table of the compose-baked defaults (OL_CORS_ORIGIN,VITE_API_BASE_URL, etc.) so readers know what's in play.pnpm demo:up/logs/down) + boot-order explanation./admin-devpath).http://prestashopfor Shop/Storefront URL and why).Stanparameter, single vs bulk note referencing [BUG] Frontend — bulk offer wizard hides category-parameter step for Allegro (required "Stan" unsettable) #1367/fix(allegro,web): advertise OfferManager sub-capabilities so bulk wizard shows Allegro category params #1370).IMAGE_DOWNLOAD_FAILED,SELLER_DEFAULTS_NOT_CONFIGURED,PARAMETER_REQUIRED) to its fix.Docs only — no code changes. Stacks on #1365 (targets the
1352-docker-demo-environmentbranch), and complements the boot/networking fixes from #1369.Test plan
docker-compose.demo.yml(web8090,OL_CORS_ORIGIN=http://localhost:8090,VITE_API_BASE_URL=http://localhost:3000) and the post-install networking config from fix(demo): unblock one-command Docker demo boot + PrestaShop networking (#1368) #1369.🤖 Generated with Claude Code