From 531c337d190c7bfe254980c06fedc978844d4e5d Mon Sep 17 00:00:00 2001 From: David Montero Crespo Date: Mon, 4 May 2026 00:04:11 -0300 Subject: [PATCH] fix(install): unblock self-hosting + drop forced wokwi clones MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Resolves several install pain points reported by users (#108, #120) and removes the obligatory upstream-clone step that confused contributors and slowed down every Docker build. Install fixes: - nginx: server_name → catch-all default_server, drop Debian's stock site so reverse-proxied users no longer get the "Welcome to nginx" page. - entrypoint: auto-generate SECRET_KEY at first boot, persisted under data/.secret_key. backend/.env is now optional in docker-compose.yml. - backend: add greenlet>=3.0.0 (SQLAlchemy async dep that was missing on some Python builds — caused uvicorn startup failures on WSL). Wokwi libs come from npm: - @wokwi/elements 1.9.2, avr8js 0.21.0, rp2040js 1.3.2 are pinned in frontend/package.json. Vite aliases removed. - Dockerfile.standalone no longer clones avr8js / rp2040js / wokwi-elements / wokwi-boards. Frontend stage is just COPY + npm install + build:docker. - Board SVGs vendored under frontend/public/boards/ (10 deduped against existing files, 2 truly new). third-party/wokwi-* clones become reference- only credits — generate-component-metadata.ts skips gracefully when absent. Production config split out: - docker-compose.prod.yml, deploy/nginx.prod.conf, nginx-host-velxio*.conf, update-third-party.bat removed. Production deployment lives in its own repo: https://github.com/velxio/velxio-prod (host nginx + HTTPS + backups + pinned upstream commit). Verified locally: 1161 frontend tests pass, build:docker completes clean. Co-Authored-By: Claude Opus 4.7 (1M context) --- .dockerignore | 9 +- .github/workflows/frontend-tests.yml | 38 +- CLAUDE.md | 65 +- Dockerfile.standalone | 32 +- README.md | 75 +- backend/requirements.txt | 4 + deploy/entrypoint.sh | 13 + deploy/nginx.conf | 6 +- deploy/nginx.prod.conf | 57 - docker-compose.prod.yml | 29 - docker-compose.yml | 7 +- docs/wiki/docker-infrastructure.md | 14 +- frontend/Dockerfile | 28 +- frontend/package-lock.json | 1691 +---------------- frontend/package.json | 5 +- frontend/public/boards/esp32-devkit-v1.svg | 121 ++ frontend/public/boards/wemos-lolin32-lite.svg | 1218 ++++++++++++ frontend/public/sitemap.xml | 334 ++-- .../velxio-components/Esp32Element.ts | 27 +- .../velxio-components/PiPicoWElement.ts | 3 +- frontend/src/pages/DocsPage.tsx | 79 +- frontend/src/pages/Esp32C3SimulatorPage.tsx | 2 +- frontend/src/pages/Esp32S3SimulatorPage.tsx | 2 +- frontend/src/pages/Esp32SimulatorPage.tsx | 2 +- .../pages/RaspberryPiPicoSimulatorPage.tsx | 2 +- frontend/vite.config.ts | 12 +- nginx-host-velxio-temp.conf | 19 - nginx-host-velxio.conf | 56 - scripts/generate-component-metadata.ts | 16 +- scripts/generate-component-svgs.cjs | 20 +- update-third-party.bat | 42 - 31 files changed, 1813 insertions(+), 2215 deletions(-) delete mode 100644 deploy/nginx.prod.conf delete mode 100644 docker-compose.prod.yml create mode 100644 frontend/public/boards/esp32-devkit-v1.svg create mode 100644 frontend/public/boards/wemos-lolin32-lite.svg delete mode 100644 nginx-host-velxio-temp.conf delete mode 100644 nginx-host-velxio.conf delete mode 100644 update-third-party.bat diff --git a/.dockerignore b/.dockerignore index d8a6948c..83304843 100644 --- a/.dockerignore +++ b/.dockerignore @@ -12,8 +12,13 @@ env/ # Build outputs (will be built inside Docker) frontend/dist/ frontend/.vite/ -third-party/avr8js/dist/ -third-party/wokwi-elements/dist/ + +# Reference-only third-party clones — Velxio resolves these from npm at +# build time, so the Docker image doesn't need the upstream sources. +third-party/avr8js/ +third-party/rp2040js/ +third-party/wokwi-elements/ +third-party/wokwi-boards/ # QEMU source & Windows builds (only prebuilt/qemu/ .so files are needed) third-party/qemu-lcgamboa/ diff --git a/.github/workflows/frontend-tests.yml b/.github/workflows/frontend-tests.yml index 54e38282..d1fd4566 100644 --- a/.github/workflows/frontend-tests.yml +++ b/.github/workflows/frontend-tests.yml @@ -13,55 +13,26 @@ jobs: steps: - name: Checkout repository uses: actions/checkout@v4 - # Do NOT use submodules: recursive — the submodule pointers in this repo - # are stale and predate package.json. We clone the libs fresh below. - name: Setup Node.js 22 uses: actions/setup-node@v4 with: node-version: '22' - # Clone third-party fresh (stale submodule pointers can't be used) - - name: Clone third-party - run: | - git clone --depth=1 https://github.com/wokwi/avr8js.git third-party/avr8js - git clone --depth=1 https://github.com/wokwi/rp2040js.git third-party/rp2040js - git clone --depth=1 https://github.com/wokwi/wokwi-elements.git third-party/wokwi-elements + # The metadata generator scans wokwi-elements/src/, which only ships in + # the upstream repo (not on npm). Clone it once for the freshness check. + - name: Clone wokwi-elements (for metadata regeneration only) + run: git clone --depth=1 https://github.com/wokwi/wokwi-elements.git third-party/wokwi-elements - # Cache third-party node_modules to speed up repeated runs - - name: Cache third-party node_modules - uses: actions/cache@v4 - with: - path: | - third-party/avr8js/node_modules - third-party/rp2040js/node_modules - third-party/wokwi-elements/node_modules - key: third-party-${{ hashFiles('third-party/avr8js/package-lock.json', 'third-party/rp2040js/package-lock.json', 'third-party/wokwi-elements/package-lock.json') }} - - # Cache frontend node_modules - name: Cache frontend node_modules uses: actions/cache@v4 with: path: frontend/node_modules key: frontend-${{ hashFiles('frontend/package-lock.json') }} - # Build avr8js (referenced as file: dep in frontend/package.json) - - name: Build avr8js - run: cd third-party/avr8js && npm install && npm run build - - # Build rp2040js (referenced via vite alias to dist/esm) - - name: Build rp2040js - run: cd third-party/rp2040js && npm install && npm run build - - # Build wokwi-elements (referenced as file: dep in frontend/package.json) - - name: Build wokwi-elements - run: cd third-party/wokwi-elements && npm install && npm run build - - # Install frontend deps (picks up file: references to avr8js and wokwi-elements) - name: Install frontend dependencies run: cd frontend && npm ci - # Install root deps (typescript, tsx) so the metadata generator runs - name: Install root dev dependencies run: npm ci @@ -78,6 +49,5 @@ jobs: exit 1 fi - # Run all vitest tests - name: Run tests run: cd frontend && npm test diff --git a/CLAUDE.md b/CLAUDE.md index 01fd6b26..2a58e931 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -72,25 +72,25 @@ npm run lint **Access:** - App: http://localhost:5173 -### Wokwi Libraries (Local Repositories) +### Wokwi Libraries (npm) -The project uses local clones of Wokwi repositories in `third-party/`: -- `wokwi-elements/` - Web Components for electronic parts -- `avr8js/` - AVR8 CPU emulator -- `rp2040js/` - RP2040 emulator +`@wokwi/elements`, `avr8js` and `rp2040js` are pulled directly from the npm +registry — see version pins in `frontend/package.json`. No clone or local +build is required for the Docker image, manual install, or CI. -**Update libraries:** -```bash -update-third-party.bat -``` +The folders under `third-party/` are reference-only (credits / offline +hacking). The one exception is `qemu-lcgamboa` (real source dependency for +ESP32 emulation when rebuilding QEMU). -Or manually: -```bash -cd third-party/wokwi-elements -git pull origin main -npm install -npm run build -``` +**Bump a wokwi lib version:** edit the version string in +`frontend/package.json` and run `npm install` in `frontend/`. + +**Adding new components to wokwi-elements:** the metadata generator +(`scripts/generate-component-metadata.ts`) scans the upstream `src/`, +which the npm package doesn't ship. Clone wokwi-elements once into +`third-party/wokwi-elements/` and run `npm run generate:metadata`. The +script gracefully skips when the clone is absent — `components-metadata.json` +is committed. ### External Dependencies @@ -116,17 +116,11 @@ arduino-cli core install arduino:avr ### Critical Architecture Patterns -**1. Vite Aliases for Local Wokwi Libs** +**1. Wokwi libs come from npm** -The `frontend/vite.config.ts` uses path aliases to import from local repositories: -```typescript -resolve: { - alias: { - 'avr8js': path.resolve(__dirname, '../third-party/avr8js/dist/esm'), - '@wokwi/elements': path.resolve(__dirname, '../third-party/wokwi-elements/dist/esm'), - }, -} -``` +`@wokwi/elements`, `avr8js` and `rp2040js` are listed as regular +dependencies in `frontend/package.json`. Vite resolves them from +`node_modules` like any other package — no aliases, no `file:` references. **2. Multi-File Workspace (useEditorStore)** @@ -404,15 +398,14 @@ There are known pre-existing TS errors that do NOT block the app from running: ### 8. Docker Build — third-party -The git submodule pointers for `rp2040js` and `wokwi-elements` in this repo are stale (point to very old commits that predate `package.json`). The `Dockerfile.standalone` works around this by **cloning the libs fresh from GitHub** at build time instead of COPYing from the build context: +`Dockerfile.standalone` does NOT clone any wokwi-* repos. The frontend stage +just does `COPY frontend/ scripts/` then `npm install && npm run build:docker`, +which pulls `@wokwi/elements`, `avr8js`, `rp2040js` from npm. Board SVGs live +in `frontend/public/boards/`, component SVGs in `frontend/public/component-svgs/`, +and `components-metadata.json` is committed. -```dockerfile -RUN git clone --depth=1 https://github.com/wokwi/avr8js.git third-party/avr8js \ - && git clone --depth=1 https://github.com/wokwi/rp2040js.git third-party/rp2040js \ - && git clone --depth=1 https://github.com/wokwi/wokwi-elements.git third-party/wokwi-elements -``` - -The GitHub Actions workflow does NOT use `submodules: recursive` for this reason. +The frontend-tests CI workflow only clones `wokwi-elements` (for the +metadata staleness check), not the other two. ### 9. Backend Gotchas @@ -445,7 +438,9 @@ npm test ### Adding a New Electronic Component -1. Check if wokwi-elements has the component (see `third-party/wokwi-elements/src/`) +1. Check if wokwi-elements has the component — either browse + https://github.com/wokwi/wokwi-elements or `ls third-party/wokwi-elements/src/` + if the optional clone is present 2. Create React wrapper in `frontend/src/components/components-wokwi/` 3. Add component type to `useSimulatorStore` interface 4. Update SimulatorCanvas to render the component diff --git a/Dockerfile.standalone b/Dockerfile.standalone index e3a75d1c..44ff416f 100644 --- a/Dockerfile.standalone +++ b/Dockerfile.standalone @@ -69,29 +69,10 @@ FROM node:20 AS frontend-builder WORKDIR /app -# Clone third-party fresh from upstream to avoid stale submodule pointers. -# git is pre-installed in the node:20 Debian image. -RUN git clone --depth=1 https://github.com/wokwi/avr8js.git third-party/avr8js \ - && git clone --depth=1 https://github.com/wokwi/rp2040js.git third-party/rp2040js \ - && git clone --depth=1 https://github.com/wokwi/wokwi-elements.git third-party/wokwi-elements \ - && git clone --depth=1 https://github.com/wokwi/wokwi-boards.git third-party/wokwi-boards - -# Build avr8js -WORKDIR /app/third-party/avr8js -RUN npm install && npm run build --if-present - -# Build rp2040js (may have no build script on some commits) -WORKDIR /app/third-party/rp2040js -RUN npm install && npm run build --if-present - -# Build wokwi-elements -WORKDIR /app/third-party/wokwi-elements -RUN npm install && npm run build --if-present - -# Build frontend -# components-metadata.json is already committed; skip generate:metadata -# (it requires wokwi-elements/src which isn't needed at runtime) -WORKDIR /app +# avr8js, rp2040js and @wokwi/elements are pulled directly from the npm +# registry (see frontend/package.json) — no upstream git clones needed. +# Board SVGs live in frontend/public/boards/, component SVGs in +# frontend/public/component-svgs/, and components-metadata.json is committed. COPY frontend/ frontend/ COPY scripts/ scripts/ WORKDIR /app/frontend @@ -144,7 +125,10 @@ COPY backend/app/ ./app/ # run with: docker exec velxio-app python /app/scripts/