cloud/ocis
1
0
Fork 0
mirror of https://github.com/owncloud/ocis.git synced 2026-10-28 12:39:37 +03:00
Code Activity
Files
test-cli-postprocessing-resume
ocis/web/docs/development/repo-structure.md
Lukas Hirt 6bad03d364 [full-ci] chore: [OCISDEV-5] merge and relicense ownCloud Web into oCIS (#12491) 
* chore: [OCISDEV-5] Merge and relicense ownCloud Web into oCIS

Consolidate the ownCloud Web frontend into this repository as a single
product with one contribution surface and one license. The web/ source
is imported as-is from the final standalone owncloud/web release
(v12.5.0 / last-agpl-release @ b16a34fdf5569d2fd63b1ff3c575c1a4ee569ad3);
the archived owncloud/web repository remains the historical record for
everything at and before that commit.

Relicensing:
- All web/ contributors have signed the ownCloud CLA, granting ownCloud
  GmbH the right to relicense their contributions.
- web/LICENSE (AGPL-3.0) removed; the repository root LICENSE
  (Apache-2.0) now governs web/ as well, matching how the rest of the
  repo is already licensed.
- All 25 web/packages/*/package.json license fields flipped to
  Apache-2.0; root NOTICE added documenting the relicensing provenance.
- Added REUSE.toml + LICENSES/ so the whole repository (including
  vendored Go dependencies) is REUSE 3.3 compliant.

CI/build:
- services/web/Makefile now builds web assets from the in-tree source
  instead of downloading a release tarball from owncloud/web; license
  checking/saving likewise runs against the in-tree source.
- ci.env and tests/acceptance/run-e2e.py no longer clone owncloud/web
  for Playwright e2e tests.
- Added the app-provider and ocm e2e suites to acceptance-tests.yml's
  matrix, closing a coverage gap where they were silently excluded;
  ported the Collabora/OnlyOffice/federated-instance orchestration
  web's old CI used to run them.
- Added web-tests.yml (typecheck/format/lint/unit-test), a
  check-licenses.yml, commit-message.yml, and release-npm-packages.yml
  for the @ownclouders/* packages, replacing web's old standalone CI.
- Removed dead CI tooling inherited from the standalone repo
  (web/tests/drone, web/tests/actions, web/.github, and an orphaned
  ci.env-dependent cache-check script).

Docs:
- Rewrote docs/services/web/releasing.md and web/docs/releasing to
  describe the in-tree build/release process.
- Updated remaining references to github.com/owncloud/web across docs,
  services/web/README.md, and the deployment example to point at the
  in-tree web/ directory.

Signed-off-by: Lukas Hirt <info@hirt.cz>

* ci: sync web/ translations via Transifex

web/ is a pnpm workspace nested inside the repo, so it isn't covered by
the existing translation-sync job (sub_path: ., no package.json at the
repo root). Add a second sync-web job invoking the same reusable
workflow with sub_path: web and package_manager: pnpm, so its l10n-read/
push/pull/write targets actually install web's dependencies instead of
silently running against an empty node_modules. Sequenced after the
existing sync job since both push to the same hardcoded
chore/translations-update branch.

* ci: fix pnpm cache setup order in web-tests and check-licenses

actions/setup-node's cache: pnpm input shells out to pnpm to resolve
the cache directory, so pnpm must already be on PATH when that step
runs. Both workflows ran `corepack enable` *after* setup-node, which
still failed: corepack writes its pnpm shim into the currently active
Node installation's bin dir, and setup-node had already swapped PATH
to the newly-installed Node version by that point, leaving the shim
behind. Use pnpm/action-setup instead, which installs a standalone
pnpm binary independent of the Node version, before setup-node runs.

Also set cache-dependency-path explicitly: the lockfile lives at
web/pnpm-lock.yaml, and cache-dependency-path resolves relative to
GITHUB_WORKSPACE regardless of the job's working-directory default
(that default only applies to run: steps, not to setup-node itself).

* fix(web): resolve 19 HIGH trivy findings in pnpm-lock.yaml

All 19 findings had fixes available upstream, so per this repo's own
.trivyignore policy (reserved for cases with no fix available), these
get fixed rather than suppressed.

vite (7.3.2 -> 7.3.5) is a direct dependency, bumped directly in every
package.json that pins it.

The other 8 (@xmldom/xmldom, flatted, form-data, immutable, js-cookie,
linkify-it, minimatch, ws) are purely transitive. Verified empirically
that `pnpm update <pkg>` silently no-ops on packages not declared in
any workspace manifest, even when a parent's semver range would allow
the fix (e.g. glob@10.5.0's `^9.0.4` covers 9.0.7) -- so pnpm.overrides
is genuinely required here, not just convenient.

minimatch is overridden with a version-range key
(minimatch@>=9.0.0 <9.0.7) rather than a blanket override, since 6
different major versions of minimatch coexist in the tree for
different consumers (3.x/5.x/10.x elsewhere); a blanket override would
have forced all of them to 9.0.7 and likely broken callers expecting a
different major's API.

* fix(web): unify @types/node resolution to stop duplicate vite types

The previous vite 7.3.2 -> 7.3.5 bump caused pnpm to resolve two
different @types/node versions (25.7.0 and 26.1.0) as vite's optional
peer across different workspace packages. vue-tsc then saw two
structurally-different copies of vite's types (e.g. Plugin, HotUpdateOptions)
and failed with TS2769 in design-system, web-client, web-pkg and
web-test-helpers' vite.config.ts files.

Force a single resolution via pnpm.overrides, pinned to 24.13.2 to
match the Node 24 runtime (engines/volta) rather than an arbitrary
newer major.

* fix(tests): fix ocm/app-provider e2e suites' oCIS orchestration

Both suites were newly wired up by the previous merge-web-repo commit
and hadn't run against real CI yet, so their setup had two latent bugs:

e2e-ocm: the federated instance's env only offset *_DEBUG_ADDR ports,
leaving the actual service ports (e.g. gateway's default
127.0.0.1:9142) unset. The federated "ocis server" process then
crashed trying to bind the same ports the primary instance already
held. run-github.py's Behat apiOcm suite already solved this with a
canonical tests/config/local/.env-federation port map (proven working,
since apiOcm passes) -- reuse it instead of the ad-hoc offset. Also
adds OCIS_ADD_RUN_SERVICES=ocm/OCIS_ENABLE_OCM, missing from the
primary instance too.

e2e-app-provider: tests/config/ci/app-registry.yaml maps its one
mimetype to "FakeOffice" (the stub used by apiCollaboration) and has
no docx entry at all, so the real Collabora/OnlyOffice containers this
suite drives never appeared in the web UI's "New file" menu. Add a
dedicated app-registry mapping both odt->Collabora and docx->OnlyOffice
with allow_creation, and use it only when COLLABORATION_NEEDED is set.

Signed-off-by: Lukas Hirt <info@hirt.cz>

* fix(tests): trust federated oCIS cert, register office templates by target_ext

e2e-ocm: the primary and federated instances each generate their own
self-signed proxy cert. Only the primary's was ever added to the
system CA trust store, so Chromium refused the federated instance's
TLS handshake ("tls: unknown certificate") once federation began.
Trust the federated cert too, and thread OCIS_BASE_DATA_PATH through
its `ocis init` call (previously only set for the running server),
since that's where the cert actually gets written.

e2e-app-provider: reproduced the suite locally (real Collabora/
OnlyOffice containers + `ocis collaboration server`) and diffed
`/app/list` before/after. allow_creation and default_app alone don't
make the web UI's "New file" menu show an entry -- it additionally
requires app_providers[].target_ext, which reva's app-provider only
stamps onto a hardcoded set of "-template" mimetypes
(vendor/github.com/owncloud/reva/v2/.../appprovider/templates.go), not
the plain document mimetypes the previous config used. Existing odt/
docx files still open fine without a static entry, since Collabora/
OnlyOffice register their full supported mimetype list dynamically via
WOPI discovery -- it's specifically file *creation* that needs this.

Signed-off-by: Lukas Hirt <info@hirt.cz>

* fix(changelog): shorten title over the 80-char lint limit

changelog/unreleased/bugfix-personal-space-fail-closed.md landed on
master (#12442) with a 97-char title, which changelog-lint rejects.
GitHub tests PRs against a merge with the current master tip, so this
started failing build-and-test on every open PR once master picked up
that commit -- unrelated to this branch's own changes. Fixing it here
since master needed to be merged in anyway.

* fix(tests): load web apps the ocm/app-provider e2e suites depend on

Both suites drive the web UI, and web only loads the web apps listed in
its UI config's "apps" array. run-e2e.py reuses
tests/config/ci/ocis-config.json, which predates the playwright suites
and lists neither app they need, so both failed deterministically while
the API-only Behat suites (apiOcm, apiCollaboration) kept passing:

e2e-ocm: the "open-cloud-mesh" app menu item can never render because
"ocm" was missing, so web-app-ocm was never loaded. Add it for the
federated suite. Behind that sat a second bug: the invite flow embeds
token@<BASE_URL_OCIS host> (127.0.0.1:9200) into invite codes, but the
federated instance authorizes providers against
tests/config/local/providers.json, which only lists localhost:9200.
Address the primary as https://localhost:9200 when federated, mirroring
run-github.py's passing apiOcm setup (the self-signed cert covers both
hosts; other suites keep 127.0.0.1).

e2e-app-provider: web-runtime only builds the per-provider Collabora/
OnlyOffice editor apps -- including their "New file" menu entries --
when web-app-external is loaded (web/packages/web-runtime/src/index.ts
gates on applicationStore.has('web-app-external')), and "external" was
missing. This also falsifies the previous target_ext theory: the
template-mimetype registry was active in the failing run and the menu
still never appeared, because the New-file menu needs only
allow_creation plus a registered provider
(web-app-external/src/index.ts). Revert the app registry to the plain
odt->Collabora / docx->OnlyOffice mimetypes web's own e2e CI proved out
(web/dev/docker/ocis/app-registry.yaml). Create-from-template still
works without static entries: reva stamps target_ext onto the -template
mimetypes the providers register via WOPI discovery.

Signed-off-by: Lukas Hirt <info@hirt.cz>
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

* ci: upload playwright traces and a11y report from e2e suites

Port the two upload-artifact steps the standalone web repo's e2e
workflow had: playwright error contexts/report output on failure, and
the a11y report on any non-cancelled run. Paths are prefixed with web/
since the web repo now lives in that subdirectory, artifact names use
the suite name instead of the job index, and the action pin matches the
one already used in this workflow.

Signed-off-by: Lukas Hirt <info@hirt.cz>
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

* fix(tests): allow office editor iframes in the e2e proxy CSP

The app-provider suite got past file creation but every office test
then timed out waiting for the editor to render: ocis's default proxy
CSP only allows frame-src 'self' (exact scheme+host+port), so the
browser refused to embed the Collabora/OnlyOffice iframes served on
other ports. The COLLABORA_DOMAIN/ONLYOFFICE_DOMAIN env vars do nothing
on their own -- they are only substituted into a custom CSP file, which
is why the pre-merge web CI always set PROXY_CSP_CONFIG_FILE_LOCATION
(tests/drone/csp.yaml there). The localStorage SecurityError seen in
the logs was a downstream symptom: the CSP-blocked frame ends up with
an opaque origin where storage access throws.

Add the two editor domains to tests/config/ci/csp.yaml's frame-src and
img-src (mirroring web's proven csp.yaml) and point the collaboration
suite at it. The keycloak suite shares this file; for it the new
entries fall back to nonexistent default hosts and are inert.

Signed-off-by: Lukas Hirt <info@hirt.cz>
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

* fix(licenses): attribute REUSE.toml copyright to ownCloud contributors

The web/ tree carries community contributions dating back to 2016; the
CLA grants a relicensing right, not a copyright transfer, so declaring
sole 2020-2026 ownCloud GmbH authorship was inaccurate.

Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>

* fix(tests): trust the Keycloak cert in e2e TLS setup

The Keycloak cert had no SAN, and NODE_EXTRA_CA_CERTS only ever pointed
at the oCIS cert, so any node-fetch/axios call made directly against
Keycloak (admin token fetch, user provisioning) failed TLS validation
and aborted the keycloak/mfa matrix jobs before a spec could run.

Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>

* fix(web): don't wipe assets/ before a successful build

build-assets ran `git clean -xfd assets` before the pnpm build; a failed
typecheck or vite build left assets/core/ empty, so the next Go embed or
docker deployment served no web UI. Clean only after the build succeeds.

Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>

* ci: fail clearly when a release tag matches no known package

If the tag-prefix loop found no match, the workflow silently fell
through to a jq lookup against "packages//package.json", failing with a
confusing path error instead of naming the problem.

Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>

* ci: drop duplicate dependency-license-check job

web-tests.yml already enforces the license allow-list via
`pnpm licenses:check` (license-checker-rseidelsohn) on every PR.
check-licenses.yml's dependency-license-check ran a second, differently
configured tool (npx license-checker, GPL/AGPL deny-list only), which
could disagree with the first without adding coverage.

Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>

---------

Signed-off-by: Lukas Hirt <info@hirt.cz>
Co-authored-by: Claude Fable 5 <noreply@anthropic.com>
2026-07-07 10:37:00 +02:00

7.1 KiB
Raw Permalink Blame History

title, date, weight, geekdocRepo, geekdocEditPath, geekdocFilePath
title date weight geekdocRepo geekdocEditPath geekdocFilePath
Repo Structure and (Published) Packages 2022-01-28T00:00:00+00:00 30 https://github.com/owncloud/web edit/master/docs/development repo-structure.md

{{< toc >}}

Repository Structure

From a developer's perspective, the most important parts of the ownCloud Web repo are the following files and folders:

dev Folder and docker-compose.yml File

The /dev folder contains all the configuration files that are needed in the docker-compose.yml file. This docker compose stack contains all the backend and testing related infrastructure that is needed for an out-of-the-box usable localhost development setup, as described in the [tooling section]({{< ref "tooling.md" >}}).

docs Folder

Within the /docs folder you will find all the documentation source documents that get published to the dev docs.

packages Folder

We're using the ownCloud Web repo as a mono repo. It contains a variety of packages. Some of them get published to npmjs.com, others define the core packages, apps and extensions that are the foundation of the ownCloud Web release artifact.

Having these packages side by side within the /packages folder of the repo is possible because of a pnpm feature called Workspaces. You can learn more about that by visiting the pnpm docs.

tests Folder

We're using the Playwright for UI testing. The UI tests are located in the /tests/e2e

You're more than welcome to make a pull request and adjust this section of the docs accordingly. :-) You can read more about testing in our [testing section]({{< ref "../testing/_index.md" >}})

package.json File

This is probably no surprise: the root level package.json file defines the project information, build scripts, dependencies and some more details. Each package in /packages can and most likely will contain another package.json which does the same for the respective package.

vite.config.ts

We're working with Vite as a local development server and build tool. vite.config.ts is the main configuration file for that. You can read more about the usage in our [tooling section]({{< ref "tooling.md" >}}).

(Published) Packages

Each package in the /packages folder can - not exclusively, but most commonly - consist of

  • source code (/src),
  • unit tests (/tests),
  • translations (/l10n) and
  • a package.json file for package specific details and dependencies.

Code Style and Build Config

Some of our packages in /packages are pure helper packages which ensure a common code style and build configuration for all our internal (mono repo) and external packages. We encourage you to make use of the very same packages. This helps the community understand code more easily, even when coming from different developers or vendors in the ownCloud Web ecosystem.

Namely those packages are

  • /packages/babel-preset
  • /packages/eslint-config
  • /packages/extension-sdk
  • /packages/prettier-config
  • /packages/tsconfig/

ownCloud Design System

The ownCloud Design System (/packages/design-system) is a collection of components, design tokens and styles which ensure a unique and consistent look and feel and branding throughout the ownCloud Web ecosystem. We hope that you use it, too, so that your very own apps and extensions will blend in with all the others. Documentation and code examples can be found in the design system documentation.

The ownCloud Design System is a standalone project, but to make development easier we have the code in our mono repo. We're planning to publish it on npmjs.com as @ownclouders/design-system as soon as possible. Since it's bundled with ownCloud Web, you should not bundle it with your app or extension.

web-client

The client package (/packages/web-client) serves as an abstraction layer for the various ownCloud APIs, like LibreGraph, WebDAV and OCS. The package provides TypeScript interfaces for various entities (like files, folders, shares and spaces) and makes sure that raw API responses are properly transformed so that you can deal with more useful objects. The web-client package gets published on npmjs.com as @ownclouders/web-client.

Dedicated documentation for the web-client package is not available, yet, since our extension system is still work in progress. However, the package's README.md gives you a few examples on how to use it.

web-pkg

The web-pkg package (/packages/web-pkg) is a collection of opinionated components, composables, types and other helpers that aim at making your app and extension developer experience as easy and seamless as possible. The web-pkg package gets published on npmjs.com as @ownclouders/web-pkg.

Dedicated documentation for the web-pkg package is not available, yet, since our extension system is still work in progress.

web-runtime

At the very heart of ownCloud Web, the web-runtime is responsible for dependency injection, app bootstrapping, configuration, authentication, data preloading and much more. It is very likely that you will never get in touch with it as most of the developer-facing features are exposed via web-pkg. If you have more questions about this package, please join our public chat and simply ask or write an issue in our issue tracker.

Standalone Core Apps

Both web-app-admin-settings and web-app-files are standalone apps which are bundled with the default ownCloud Web release artifact.

Viewer and Editor Apps

Apps which fall into the categories viewer or editor can be opened from the context of a file or folder. This mostly happens from within the files app. We currently bundle the following apps with the default ownCloud Web release artifact:

  • web-app-epub-reader a simple reader for .epub files
  • web-app-external an iframe integration of all the apps coming from the app provider (e.g. OnlyOffice, Collabora Online and others)
  • web-app-pdf-viewer a viewer for .pdf files, which relies on native PDF rendering support from the browser
  • web-app-preview a viewer for various media files (audio / video / image formats)
  • web-app-text-editor a simple editor for .txt, .md and other plain text files

If you're interested in writing your own viewer or editor app for certain file types, please get in touch with us for more info.

Testing

Additional unit testing code lives in test-helpers.

View Git Blame Copy Permalink