Add Nextcloud Playground preview with ready-to-use demo by erseco · Pull Request #45 · devnoname120/epubviewer

erseco · 2026-07-12T16:11:28Z

About this PR — Nextcloud Playground

Nextcloud Playground runs a full Nextcloud in the browser (PHP + SQLite compiled to WebAssembly), provisioned from a declarative blueprint.json. This PR wires the epubviewer app into it so anyone can try the EPUB/PDF/CBR/CBZ viewer — and reviewers can test any future PR — in a live Nextcloud instance with zero local setup.

Summary

blueprint.json (repo root): boots a fresh Nextcloud, installs epubviewer (the installApp URL points at the canonical parent devnoname120/epubviewer so the rewrite logic works from forks), seeds a few sample EPUB files under Files, and lands on the Files view.
.github/workflows/playground-preview.yml: on push to master keeps a rolling playground release asset; on every PR builds the app (with Vite bundles), publishes a per-PR playground-pr-N asset through the CORS proxy, rewrites the blueprint to target the PR's zip, and posts a "Preview this PR in the Nextcloud Playground" button as a comment.
README.md: adds the Playground badge at the top and a "Try in Nextcloud Playground" section.

All static references deliberately target the parent repository (devnoname120/epubviewer) because the end goal is a clean contribution upstream.

The implementation follows the exact pattern used for the Moodle equivalent and the approach already shipping in nextcloud-exelearning.

Test plan

Once merged, every PR against this repo will automatically get a preview comment with a working button.
Opening the preview boots a Nextcloud + the epubviewer app (log in admin / admin).
Sample EPUBs appear in Files. Clicking them exercises the reader (search, night mode, keyboard nav, thumbnails, etc.).

ℹ️ Live PR-preview demo: see the same change applied on my fork at erseco/epubviewer#1 — the workflow has already run there and posted the real "Preview this PR in the Nextcloud Playground" button.

The preview workflow requires pull-requests: write and only runs for same-repo pull requests, so it does not execute on this cross-fork PR to the parent repo. That's why the fork PR above shows the end-to-end result.

Manual example of the button (as it appears in the fork PR)

Copy-pasted directly from the live comment on my fork PR:

This is exactly the button + link that the workflow will post on every future PR once this is merged.

Add `blueprint.json`, a GitHub workflow, and README section so the EPUB Viewer can be tried instantly in the browser via Nextcloud Playground (https://ateeducacion.github.io/nextcloud-playground/). - blueprint.json: installs `epubviewer` (pointing at canonical devnoname120/epubviewer for rewrite compatibility from forks), seeds a couple of sample EPUBs under Files, and lands on the Files view. - .github/workflows/playground-preview.yml: on push to master keeps a rolling `playground` release asset; on PRs builds the app, publishes a per-PR preview asset, rewrites the blueprint to target the PR zip via the CORS proxy, and posts a sticky "Preview this PR in the Nextcloud Playground" comment with a one-click link. Mirrors the pattern used in nextcloud-exelearning and the Moodle equivalent. - README.md: adds top badge + "Try in Nextcloud Playground" section documenting the zero-setup path and automatic PR previews. The static blueprint always targets the parent repository (devnoname120/epubviewer) so the URL-rewrite logic in the workflow (and future shared action) works correctly from forks and when this is later proposed upstream. See erseco/moodle-mod_questionnaire#1 for the equivalent Moodle change.

devnoname120

Maybe the solution would be to only have the button in the README.md and only run on the actual releases. There are barely any pull requests ever and no contributors basically, so it’s not very useful to have it run on PRs, etc.

Cool project either way!

devnoname120 · 2026-07-12T19:59:37Z

+          cp build/artifacts/epubviewer.zip epubviewer.zip
+
+      - name: Publish epubviewer.zip to the preview release
+        uses: softprops/action-gh-release@v2


You should pin the hash of all the actions

+ I don’t want to clutter my releases which pretty much vetoes the PR for me

devnoname120 · 2026-07-12T20:04:39Z

+            Automated Nextcloud Playground preview build (not a real release).
+            Installed in the browser via the blueprint `installApp` step.
+        env:
+          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}


I don’t want to have my GITHUB_TOKEN accessible anywhere in actions that run in PRs

devnoname120 · 2026-07-12T20:05:40Z

+
+      - name: Upsert PR comment
+        if: github.event_name == 'pull_request'
+        uses: actions/github-script@v7


devnoname120 · 2026-07-12T20:47:06Z

+    if: >-
+      github.event_name == 'push' ||
+      (github.event.action != 'closed' &&
+       github.event.pull_request.head.repo.full_name == github.repository)


That means that it will actually only run on my own PRs, which reduces the usefulness immensely.

devnoname120 · 2026-07-12T20:48:35Z

+permissions:
+  contents: write
+  pull-requests: write


It’s scary to give the whole workflow (including the build, etc.) these permissions

erseco · 2026-07-12T20:56:32Z

Thanks for the feedback — you’re right.

A workflow triggered from a fork would not have access to the repository’s secrets or its GITHUB_TOKEN, which is why I limited the preview job to same-repository PRs. Still, I understand the concern about granting write permissions to the workflow, especially when the repository receives very few pull requests. In that context, the extra complexity and the release clutter are probably not worth it.

Please feel free to close/discard this PR. A simple Playground link or badge in the README is likely the better fit here.

I’m a happy user of your excellent plugin and thought the Playground could be useful for people who want to try it without setting up Nextcloud locally. Thanks for taking the time to review the idea!

devnoname120 · 2026-07-12T21:06:42Z

@erseco Any ideas why the app doesn’t appear to be installed?

https://ateeducacion.github.io/nextcloud-playground/?blueprint-url=https://raw.githubusercontent.com/devnoname120/epubviewer/refs/heads/master/blueprint.json

erseco · 2026-07-12T22:18:24Z

Hi @devnoname120, I found the problem: In my tests I referenced my tests playground release that I built as epubviewer.zip asset, while the real releases are published as versioned .tar.gz files.

Nextcloud Playground now supports .tar.gz, and I have updated github-proxy.exelearning.dev to resolve the latest release and select the matching asset:

{
  "step": "installApp",
  "appId": "epubviewer",
  "url": "https://github-proxy.exelearning.dev/?repo=devnoname120/epubviewer&release=latest&asset-pattern=epubviewer-*.tar.gz"
}

github-proxy.exelearning.dev is a small open-source CORS proxy deployed as a Cloudflare Worker. Its code is available here:

https://github.com/ateeducacion/nextcloud-playground/blob/main/scripts/zip-proxy-worker.js

I use the same approach in other playground projects I maintain, including Moodle Playground, because browser-based playgrounds cannot reliably fetch GitHub release assets directly due to CORS restrictions. (all of these playgrounds are just to test the eXeLearning plugins, project from I'm contributor)

WordPress Playground previously used the same kind of GitHub proxy approach, although they have since moved towards a different git-over-CORS solution.

The only remaining change is updating blueprint.json with the URL above. Feel free to make the change directly, or I can open a small follow-up PR.

devnoname120 · 2026-07-13T23:19:22Z

@erseco I did the update. It works great now, thank you!
Btw you might also be interested in this: https://github.com/devnoname120/nextcloud-file-viewer

erseco mentioned this pull request Jul 12, 2026

Add Nextcloud Playground preview for EPUB Viewer erseco/epubviewer#1

Closed

erseco changed the title ~~Add Nextcloud Playground preview with ready-to-use demo by erseco~~ Add Nextcloud Playground preview with ready-to-use demo Jul 12, 2026

Declutter the README

64749bc

devnoname120 reviewed Jul 12, 2026

View reviewed changes

Delete .github/workflows/playground-preview.yml

6f3ae5a

devnoname120 merged commit 0e70bcf into devnoname120:master Jul 12, 2026

erseco mentioned this pull request Jul 12, 2026

Support gzip-compressed tar (.tar.gz) in installApp/unzip steps ateeducacion/nextcloud-playground#42

Merged

3 tasks

erseco mentioned this pull request Jul 14, 2026

Add Moodle Playground demo (blueprint + README badge) marcusgreen/moodle-qtype_gapfill#134

Merged

3 tasks

erseco deleted the feature/nextcloud-playground-preview branch July 14, 2026 21:28

erseco mentioned this pull request Jul 14, 2026

Add Nextcloud Playground demo devnoname120/nextcloud-file-viewer#1

Merged

Navigation Menu

Add Nextcloud Playground preview with ready-to-use demo - #45

Add Nextcloud Playground preview with ready-to-use demo#45
devnoname120 merged 3 commits into
devnoname120:masterfrom
erseco:feature/nextcloud-playground-preview

erseco commented Jul 12, 2026

Uh oh!

devnoname120 left a comment

Uh oh!

devnoname120 Jul 12, 2026

Uh oh!

devnoname120 Jul 12, 2026

Uh oh!

devnoname120 Jul 12, 2026

Uh oh!

devnoname120 Jul 12, 2026

Uh oh!

devnoname120 Jul 12, 2026

Uh oh!

devnoname120 Jul 12, 2026

Uh oh!

erseco commented Jul 12, 2026

Uh oh!

devnoname120 commented Jul 12, 2026

Uh oh!

erseco commented Jul 12, 2026

Uh oh!

devnoname120 commented Jul 13, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

Conversation

erseco commented Jul 12, 2026

About this PR — Nextcloud Playground

Summary

Test plan

Manual example of the button (as it appears in the fork PR)

Uh oh!

devnoname120 left a comment

Choose a reason for hiding this comment

Uh oh!

devnoname120 Jul 12, 2026

Choose a reason for hiding this comment

Uh oh!

devnoname120 Jul 12, 2026

Choose a reason for hiding this comment

Uh oh!

devnoname120 Jul 12, 2026

Choose a reason for hiding this comment

Uh oh!

devnoname120 Jul 12, 2026

Choose a reason for hiding this comment

Uh oh!

devnoname120 Jul 12, 2026

Choose a reason for hiding this comment

Uh oh!

devnoname120 Jul 12, 2026

Choose a reason for hiding this comment

Uh oh!

erseco commented Jul 12, 2026

Uh oh!

devnoname120 commented Jul 12, 2026

Uh oh!

erseco commented Jul 12, 2026

Uh oh!

devnoname120 commented Jul 13, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants