diff --git a/CODE_OF_CONDUCT.md b/CODE_OF_CONDUCT.md new file mode 100644 index 00000000000..ce144bf1fa0 --- /dev/null +++ b/CODE_OF_CONDUCT.md @@ -0,0 +1,8 @@ +# Code of Conduct + +This project follows the ownCloud Code of Conduct. + +Please read the full Code of Conduct at: +**** + +By participating in this project, you agree to abide by its terms. diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md new file mode 100644 index 00000000000..65c99156de9 --- /dev/null +++ b/CONTRIBUTING.md @@ -0,0 +1,9 @@ +# Contributing + +Thank you for your interest in contributing to this project! + +Please read the full contributing guidelines at: +**** + +For development setup, coding standards, and pull request process, +see the README in this repository. diff --git a/README.md b/README.md index 2f8e10cf4db..d968970857b 100644 --- a/README.md +++ b/README.md @@ -1,100 +1,135 @@ -
- - -[![Matrix](https://img.shields.io/matrix/ocis%3Amatrix.org?logo=matrix)](https://app.element.io/#/room/#ocis:matrix.org) -[![Test and build](https://github.com/owncloud/web/actions/workflows/test.yml/badge.svg)](https://github.com/owncloud/web/actions/workflows/test.yml) -[![Security Rating](https://sonarcloud.io/api/project_badges/measure?project=owncloud_web&metric=security_rating)](https://sonarcloud.io/dashboard?id=owncloud_web) -[![Coverage](https://sonarcloud.io/api/project_badges/measure?project=owncloud_web&metric=coverage)](https://sonarcloud.io/dashboard?id=owncloud_web) -[![web docker image](https://img.shields.io/docker/v/owncloud/web?label=web%20docker%20image&logo=docker&sort=semver)](https://hub.docker.com/r/owncloud/web) - # ownCloud Web -With ownCloud Web you can manage your ownCloud in your browser. + -
-Screenshot of ownCloud Web +[![License](https://img.shields.io/badge/License-AGPL--3.0-blue.svg)](LICENSE) [![ownCloud OSPO](https://img.shields.io/badge/OSPO-ownCloud-blue)](https://kiteworks.com/opensource) [![Docker Hub](https://img.shields.io/docker/pulls/owncloud)](https://hub.docker.com/r/owncloud/web) -ownCloud Web is a single page, standalone frontend, based on modern web technologies. It brings new features as well as improved user flows and can be deployed independent of the backend server. +ownCloud Web is the next-generation frontend for ownCloud Infinite Scale, built as a single-page application with Vue.js and TypeScript. It provides a modern, accessible and themeable user interface for managing files, sharing, real-time collaboration and administration -- designed to be extensible through a plugin-based architecture that allows third-party developers to build custom apps and extensions. -## Compatibility +## Part of oCIS -Usage of Web UI and [ownCloud 10](https://github.com/owncloud/core) as backend is **not** recommended starting with version `7.1.0` of the Web UI, meaning newer versions only support [ownCloud Infinite Scale](https://github.com/owncloud/ocis). If you want to use the Web UI with ownCloud 10, please use App version `7.0.2`. Critical bugs can be fixed upon request. +ownCloud Web is the primary frontend for [ownCloud Infinite Scale (oCIS)](https://github.com/owncloud/ocis). Starting with version 7.1.0, the Web UI supports only oCIS as a backend (for ownCloud 10 compatibility, use version 7.0.2). -## Examples +ownCloud Web is available on [Docker Hub](https://hub.docker.com/r/owncloud/web). -Here are some examples of what you can do with ownCloud Web: +**Live Demo:** [https://demo.owncloud.com/](https://demo.owncloud.com/) -- 🗂 **Files**: Upload, download, search and manage files (as you may know it for example from Dropbox, OneDrive, Google Drive etc.). -- 👥 **Share:** Allow fine-grained access to files and whole folders directly with other users on your ownCloud. -- 🔗 **Links**: Create links and share them with anyone in the world - optional password-protection available. -- 📝 **Write**: Edit your documents with the editor of your choice like ONLYOFFICE, Collabora or Microsoft Word and more. -- 🤝 **Collaborate** in real-time on documents. -- 🚀 **Spaces**: You have to manage important projects? Let Spaces, the new special folders, keep order. -- ◀️ **Versioning** Saved the wrong version? We have the time machine you were looking for! Easily go back in time and restore older versions of your files. -- 📥 **Drop-folders:** Collect files from other people in one folder via a simple link, ex. homework from pupils or photos from your family - optional password-protection available. -- 🔒 **Privacy first:** ownCloud Web is GDPR compliant and can both be used completely internally or together with external people. It also will never "phone home". -- 🛡 **Secure:** ownCloud Web is an open source project which means that you can track every action, update and dependency of the software. -- ♿ **Inclusive:** Our goal is to be accessible for kids as well as seniors and for newbies as well as experts - since we are all affected by physical and cognitive limitations, depending on our personal situation. -- 🧩 **Extensible:** ownCloud Web is build as a plattform that can be extended in the most developer friendly way. -- 🌗 **Darkmode:** Initialized with your browser settings, and easily switched to please your eyes better. -- 🎭 **Themes**: Customize to your branding needs or personal taste in no time. -- 👉 and many more... +## Getting Started -While the `web` frontend provides a performant, elegant, accessible and themeable base, it also aims to be extendable with custom extensions provided by external developers. +Set up a local development environment for ownCloud Web: -## Live Demos +### Prerequisites -- **Infinitescale** - Try the latest commit on the master branch with an ownCloud Infinite Scale backend: - - Demo: [https://demo.owncloud.com/](https://demo.owncloud.com/) +- [Node.js](https://nodejs.org/) (LTS recommended) +- [pnpm](https://pnpm.io/) +- [Docker Compose](https://docs.docker.com/compose/) (for backend) -## Repository structure +For the complete development setup, see the [setup guide](https://owncloud.dev/clients/web/getting-started/). -The backbone of this project is built by the following parts of the `packages`: +### Repository Structure -- **client:** Generated TypeScript client for communications with the ownCloud Infinite Scale graph API -- **container:** Static assets and rarely changing base files -- **extension-sdk:** Provides utilities for developing and integrating custom extensions -- **pkg:** Shared logic for various places inside the codebase -- **runtime:** Central place of (user) authentication, provisioning of the user interface layout, client side storage, routing, theming, dependencies and (sub)application handling +The `packages` directory contains the core modules: -The repository's `packages` also contains the following apps, which can be en-/disabled via the `config.json`: +- **client** -- Generated TypeScript client for the oCIS Graph API +- **container** -- Static assets and base files +- **extension-sdk** -- Utilities for developing custom extensions +- **pkg** -- Shared logic used across the codebase +- **runtime** -- Authentication, routing, theming and application handling -- **activities:** An extension that provides a detailed activity stream, showing recent updates -- **admin-settings:** An extension that allows administrators to manage users, groups, spaces and generic settings for their ownCloud instance efficiently -- **app-store:** An extension that allows users to browse and download additional apps and extensions directly from the web interface -- **epub-reader:** An extension for opening ebook files -- **external:** An extension for creating, opening and editing files using the WOPI server -- **files:** The default extension and core part of the project, responsible for file sync-and-share - up- and downloading, sharing with other users/groups or via links, version management and more -- **ocm:** Open cloud mesh integration to allow for collaboration across ownCloud instances -- **pdf-viewer:** An extension for opening PDF files without leaving the UI -- **preview:** An extension for opening audio, video and image files -- **search:** An extension for registering search providers, which then get rendered into the layout in the **runtime** using a portal -- **text-editor:** An extension for creating, opening and editing plain text files, like e.g. `.md` or `.txt` -- **webfinger:** Redirect app for the oCIS webfinger service +Built-in apps (also in `packages`): -The full documentation on all available packages and the general repository structure [can be found in the docs](https://owncloud.dev/clients/web/development/repo-structure/). +- **files** -- Core file sync-and-share functionality +- **admin-settings** -- User, group and space administration +- **activities** -- Activity stream +- **app-store** -- Browse and install extensions +- **epub-reader** -- Ebook file viewer +- **external** -- WOPI-based document editing (Collabora, ONLYOFFICE) +- **pdf-viewer** -- PDF file viewer +- **preview** -- Audio, video and image previewer +- **text-editor** -- Plain text editor -## Releases +## Documentation -We currently publish a new release every couple of weeks, strictly following [semver](https://semver.org/). Releases and their corresponding changelogs can be found on the [release page](https://github.com/owncloud/web/releases) on GitHub. +- [ownCloud Web Documentation](https://owncloud.dev/clients/web) +- [Development Guide](https://owncloud.dev/clients/web/getting-started/) +- [Extension System](https://owncloud.dev/clients/web/extension-system/) +- [Testing Documentation](https://owncloud.dev/clients/web/testing/testing/) +- [Repository Structure](https://owncloud.dev/clients/web/development/repo-structure/) -## Documentation +## Community & Support + +**[Star](https://github.com/owncloud/web)** this repo and **Watch** for release notifications! + +- [ownCloud Website](https://owncloud.com) +- [Community Discussions](https://github.com/orgs/owncloud/discussions) +- [Matrix Chat](https://app.element.io/#/room/#owncloud:matrix.org) +- [Documentation](https://doc.owncloud.com) +- [Enterprise Support](https://owncloud.com/contact-us/) +- [OSPO Home](https://kiteworks.com/opensource) -The documentation is an important part of this project and can be found on [owncloud.dev](https://owncloud.dev/clients/web). -If you want to contribute to the documentation you can find the source files in the [docs](https://github.com/owncloud/web/tree/master/docs) folder of this repository. +## Contributing -## Contribution +We welcome contributions! Please read the [Contributing Guidelines](CONTRIBUTING.md) +and our [Code of Conduct](CODE_OF_CONDUCT.md) before getting started. -Contribution in the form of bug reports, user feedback or actual code is always welcome! We do have a [contribution guide](https://github.com/owncloud/web/blob/master/.github/CONTRIBUTING.md), actively use the [good-first-issue](https://github.com/owncloud/web/issues?q=is%3Aopen+is%3Aissue+label%3ATopic%3Agood-first-issue) label and try to feedback on issues and pull requests in a timely manner. There is also a [setup guide](https://owncloud.dev/clients/web/getting-started/) for building and running `web` locally. +### Workflow -## Tests +- **Rebase Early, Rebase Often!** We use a rebase workflow. Always rebase on the target branch before submitting a PR. +- **Dependabot**: Automated dependency updates are managed via Dependabot. Review and merge dependency PRs promptly. +- **Signed Commits**: All commits **must** be PGP/GPG signed. See [GitHub's signing guide](https://docs.github.com/en/authentication/managing-commit-signature-verification). +- **DCO Sign-off**: Every commit must carry a `Signed-off-by` line: + ``` + git commit -s -S -m "your commit message" + ``` +- **GitHub Actions Policy**: Workflows may only use actions that are (a) owned by `owncloud`, (b) created by GitHub (`actions/*`), or (c) verified in the GitHub Marketplace. -We assert the quality of this project by running an [automated CI](https://drone.owncloud.com/owncloud/web), while a guide on running the tests locally can be found in the [testing documentation](https://owncloud.dev/clients/web/testing/testing/). +## Translations -## Jobs +Help translate this project on Transifex: +**** -At ownCloud, we are always looking for new additions to our team. You are welcome to take a look at [our open positions](https://owncloud.com/career/). +Please submit translations via Transifex -- do not open pull requests for translation changes. + +## Security + +**Do not open a public GitHub issue for security vulnerabilities.** + +Report vulnerabilities at **** -- see [SECURITY.md](SECURITY.md). + +Bug bounty: [YesWeHack ownCloud Program](https://yeswehack.com/programs/owncloud-bug-bounty-program) ## License -GNU Affero General Public License - [Details](https://github.com/owncloud/web/blob/master/LICENSE) +This project is licensed under the [AGPL-3.0](LICENSE). + +## About the ownCloud OSPO + +The [Kiteworks Open Source Program Office](https://kiteworks.com/opensource), operating under +the [ownCloud](https://owncloud.com) brand, launched on May 5, 2026, to steward the open source +ecosystem around ownCloud's products. The OSPO ensures transparent governance, license compliance, +community health, and sustainable collaboration between the open source community and +[Kiteworks](https://www.kiteworks.com), which acquired ownCloud in 2023. + +- **OSPO Home**: +- **GitHub**: +- **ownCloud**: + +For questions about the OSPO or licensing, contact ospo@kiteworks.com. + +### License Migration to Apache 2.0 + +The OSPO is driving a strategic relicensing of ownCloud repositories toward the +[Apache License 2.0](https://www.apache.org/licenses/LICENSE-2.0), following +the [Apache Software Foundation's third-party license policy](https://www.apache.org/legal/resolved.html). + +Individual repositories will migrate as their audit is completed. The LICENSE file +in each repo reflects its **current** license status (not the target). + +**Current license: AGPL-3.0** (Category X per Apache policy -- cannot be included in Apache-2.0 works). + +Migration prerequisites for this repository: + +- **CLA/DCO coverage**: All past contributors must have signed agreements permitting relicensing +- **Copyleft dependency audit**: All AGPL/GPL dependencies must be replaced or isolated +- **KDE heritage review**: Any code with KDE-era copyrights requires legal analysis +- **Complete relicensing**: AGPL-3.0 is a strong copyleft license; migration requires full relicensing of all files, not just a header change diff --git a/SECURITY.md b/SECURITY.md new file mode 100644 index 00000000000..78094ae4caf --- /dev/null +++ b/SECURITY.md @@ -0,0 +1,11 @@ +# Security Policy + +## Reporting a Vulnerability + +**Do NOT open a public GitHub issue for security vulnerabilities.** + +Please report security issues responsibly via: +**** + +You can also report vulnerabilities through our YesWeHack bug bounty program: +**** diff --git a/SUPPORT.md b/SUPPORT.md new file mode 100644 index 00000000000..d87c0ca865a --- /dev/null +++ b/SUPPORT.md @@ -0,0 +1,10 @@ +# Support + +For support with this project, please use the following channels: + +- **Enterprise Support**: +- **Community discussions**: https://github.com/orgs/owncloud/discussions +- **Matrix Chat**: +- **Documentation**: + +Please do not use GitHub issues for general support questions. diff --git a/agents.md b/agents.md new file mode 100644 index 00000000000..92e3423d0c6 --- /dev/null +++ b/agents.md @@ -0,0 +1,100 @@ +# agents.md — web + +## Repository Overview + +ownCloud Web is the next-generation frontend for ownCloud Infinite Scale (oCIS), built as a single-page application with Vue.js and TypeScript. It provides file management, sharing, real-time collaboration and administration through a plugin-based architecture. + +- **Classification:** oCIS +- **Activity Status:** Active +- **License:** AGPL-3.0 +- **Language:** TypeScript, Vue.js + +## Architecture & Key Paths + +- `packages/` — Monorepo packages (core modules and built-in apps) + - `packages/web-client/` — TypeScript client for oCIS Graph API + - `packages/web-container/` — Static assets and base files + - `packages/extension-sdk/` — SDK for custom extension development + - `packages/web-pkg/` — Shared library code + - `packages/web-runtime/` — Authentication, routing, theming, app handling + - `packages/web-app-files/` — Core file management app + - `packages/web-app-admin-settings/` — Admin UI for users, groups, spaces + - `packages/web-app-activities/` — Activity stream app + - `packages/web-app-pdf-viewer/` — PDF viewer app + - `packages/web-app-preview/` — Audio/video/image previewer + - `packages/web-app-text-editor/` — Plain text editor app + - `packages/web-app-external/` — WOPI document editing integration + - `packages/design-system/` — Shared UI component library +- `tests/` — Test suites (unit with Vitest, e2e with Playwright) +- `docs/` — Documentation source files +- `config/` — Configuration examples +- `docker/` — Docker-related files +- `deployments/` — Deployment configurations +- `Makefile` — Build orchestration +- `package.json` — Root package with scripts +- `pnpm-workspace.yaml` — pnpm monorepo workspace config +- `vite.config.ts` — Vite build configuration +- `vitest.config.ts` — Vitest test configuration +- `eslint.config.js` — ESLint configuration + +## Development Conventions + +- pnpm monorepo with workspace packages +- Vite for building, Vitest for unit tests, Playwright for e2e +- EditorConfig and Prettier for formatting +- Semantic versioning with releases every few weeks +- Changelog entries tracked in `changelog/` directory +- `.github/CONTRIBUTING.md` for contribution guidelines +- Issue/PR templates available + +## Build & Test Commands + +```bash +pnpm install # Install all dependencies +pnpm build # Production build +pnpm build:w # Build with watch mode +pnpm test:unit # Run unit tests (Vitest) +pnpm test:e2e # Run e2e tests (Playwright) +make clean # Clean build artifacts +make dist # Build distribution +make release # Create release +make docs-generate # Generate documentation +make docs-serve # Serve documentation locally +``` + +## Important Constraints + +- **AGPL-3.0 copyleft license:** This is a high-profile repository. The OSPO Apache 2.0 migration requires auditing all copyleft dependencies and contributor agreements before relicensing. +- **oCIS-only since v7.1.0:** Versions 7.1.0+ only support oCIS as a backend. OC10 support requires v7.0.2. +- **Extension architecture:** Third-party extensions use the extension-sdk package. +- **Docker image:** Published as `owncloud/web` on Docker Hub. +- **Accessibility goal:** The project explicitly aims for WCAG compliance. + + +## OSPO Policy Constraints + +### GitHub Actions +- **Only** use actions owned by `owncloud`, created by GitHub (`actions/*`), verified on the GitHub Marketplace, or verified by the ownCloud Maintainers. +- Pin all actions to their full commit SHA (not tags): `uses: actions/checkout@ # vX.Y.Z` +- Never introduce actions from unverified third parties. + +### Dependency Management +- Dependabot is configured for automated dependency updates. +- Review and merge Dependabot PRs as part of regular maintenance. +- Do not introduce new dependencies without discussion in an issue first. + +### Git Workflow +- **Rebase policy**: Always rebase; never create merge commits. Use `git pull --rebase` and `git rebase` before pushing. +- **Signed commits**: All commits **must** be PGP/GPG signed (`git commit -S -s`). +- **DCO sign-off**: Every commit needs a `Signed-off-by` line (`git commit -s`). +- **Conventional Commits & Squash Merge**: Use the [Conventional Commits](https://www.conventionalcommits.org/) format where the repository enforces it. Many repos use squash merge, where the PR title becomes the commit message on the default branch — apply Conventional Commits format to PR titles as well. A reusable GitHub Actions workflow enforces this. + +## Context for AI Agents + +- This is a large TypeScript/Vue.js monorepo managed with pnpm workspaces. +- The `packages/` directory contains all core modules and built-in apps. +- Shared code lives in `packages/web-pkg/`; the runtime in `packages/web-runtime/`. +- Configuration is via `config.json` files that specify app loading and server settings. +- The extension system allows external apps to register file handlers, UI components and routes. +- Docker images are built from `docker/Dockerfile`. +- Test infrastructure: Vitest for unit tests, Playwright/Cucumber for e2e.