diff --git a/docs/backend-oc10.md b/docs/backend-oc10.md deleted file mode 100644 index a68b2e83855..00000000000 --- a/docs/backend-oc10.md +++ /dev/null @@ -1,74 +0,0 @@ ---- -title: "Setup with ownCloud 10" -date: 2020-04-15T00:00:00+00:00 -weight: 40 -geekdocRepo: https://github.com/owncloud/web -geekdocEditPath: edit/master/docs -geekdocFilePath: backend-oc10.md ---- - -{{< toc >}} - -## Compatibility - -Please note that the usage of Web UI and ownCloud 10 as backend is not recommended starting with version 7.1.0 of the Web UI. Therefore, this section only applies to versions < 7.1.0. - -## Prerequisites - -Decide on which host and port Web will be served, for example `https://web-host:9100/web-path/`. -In this document, we will refer to the following: -- `` as the full URL, for example `https://web-host:9100/web-path/` -- `` as the protocol, domain and port, for example: `https://web-host:9100` - -## Setting up the ownCloud Server - -Make sure you have an [ownCloud Server](https://owncloud.org/download/#owncloud-server) already installed. - -### Adjusting config.php - -Add the following entries to config/config.php: - -- tell ownCloud where Web is located: -``` -'web.baseUrl' => '', -``` - -- add a CORS domain entry for Web in config.php: -``` -'cors.allowed-domains' => [''], -``` - -### Setting up OAuth2 - -To connect to the ownCloud server, it is necessary to set it up with OAuth2. - -Install and enable the [oauth2 app](https://marketplace.owncloud.com/apps/oauth2): -```bash -% occ market:install oauth2 -% occ app:enable oauth2 -``` - -Login as administrator in the ownCloud Server web interface and go to the "User Authentication" section in the admin settings and add an entry for Web as follows: - -- pick an arbitrary name for the client -- set the redirection URI to `/oidc-callback.html` -- make sure to take note of the **client identifier** value as it will be needed in the Web configuration later on - -### Setting up Web - -In the local Web checkout, copy the `config/config.json.sample-oc10` file to `config/config.json` and adjust it accordingly: - -- Set the "server" key to the URL of the ownCloud server including path. If the URL contains a path, please also add a **trailing slash** there. -- Set the "clientId" key to the **client identifier** as copied from the "User Authentication" section before. -- Adjust "url" and "authUrl" using the ownCloud server URL as prefix for both -- Optionally adjust "apps" for the list of apps to be loaded. These match the app names inside the "apps" folder. - -## Running Web - -- if running from source, make sure to [build Web]({{< ref "./building.md" >}}) first -- run by launching a rollup dev server `pnpm serve` -- when working on the Web code, rollup will recompile the code automatically - -## Running acceptance tests - -For testing, please refer to the [testing docs]({{< ref "testing/_index.md" >}}) diff --git a/docs/backend-ocis.md b/docs/backend-ocis.md deleted file mode 100644 index 21dce807bee..00000000000 --- a/docs/backend-ocis.md +++ /dev/null @@ -1,36 +0,0 @@ ---- -title: "Setup with oCIS" -date: 2020-04-15T00:00:00+00:00 -weight: 50 -geekdocRepo: https://github.com/owncloud/web -geekdocEditPath: edit/master/docs -geekdocFilePath: backend-ocis.md ---- - -{{< toc >}} - -## Setting up Web - -- Clone the [repository](https://github.com/owncloud/web/) -- Initally install all dependencies by running `pnpm install` -- Copy `./config/config.json.sample-ocis` to `./config/config.json` and adjust values if required - -## Running Web - -- Start bundling web with a watcher by running `pnpm build:w` - -## Setting up oCIS - -- Setup oCIS by following the [setup instructions](https://owncloud.dev/ocis/getting-started/) -- Start oCIS with local links to your bundled web frontend and config by running `WEB_ASSET_CORE_PATH=../../web/dist WEB_UI_CONFIG_FILE=../../web/dist/config.json OCIS_INSECURE=true IDM_CREATE_DEMO_USERS=true ./bin/ocis server` (and make sure to adjust paths as necessary) - -## Start oCIS - -- open [https://localhost:9200](https://localhost:9200) and accept the certificate -- when signing in, use one of the [available demo users](https://owncloud.dev/ocis/getting-started/demo-users/) -- whenever code changes are made, you need to manually reload the browser page (no hot reload) - -## Running tests - -For testing, please refer to the [testing docs]({{< ref "testing/_index.md" >}}) - diff --git a/docs/deployments/_index.md b/docs/deployments/_index.md deleted file mode 100644 index 3082f7b3420..00000000000 --- a/docs/deployments/_index.md +++ /dev/null @@ -1,11 +0,0 @@ ---- -title: "Deployments" -date: 2018-05-02T00:00:00+00:00 -weight: 55 -geekdocRepo: https://github.com/owncloud/web -geekdocEditPath: edit/master/docs/deployments -geekdocFilePath: _index.md -geekdocCollapseSection: true ---- - -Showcases of different scenarios of deploying ownCloud Web. diff --git a/docs/deployments/oc10-app.md b/docs/deployments/oc10-app.md deleted file mode 100644 index bf2c3332422..00000000000 --- a/docs/deployments/oc10-app.md +++ /dev/null @@ -1,288 +0,0 @@ ---- -title: "Deploy as an app in ownCloud 10" -date: 2018-05-02T00:00:00+00:00 -weight: 1 -geekdocRepo: https://github.com/owncloud/web -geekdocEditPath: edit/master/docs/deployments -geekdocFilePath: oc10-app.md ---- - -{{< toc >}} - - -## Compatibility - -Please note that the usage of Web UI and ownCloud 10 as backend is not recommended starting with version 7.1.0 of the Web UI. Therefore, this section only applies to versions < 7.1.0. - -## Introduction - -ownCloud Web is being deployed as an app to [ownCloud marketplace](https://marketplace.owncloud.com/) to enable easy integration into existing ownCloud 10 instances. -After completing this setup, ownCloud Web will be available on `https:///index.php/apps/web`. - -## Prerequisites -- Running [ownCloud 10 server](https://owncloud.com/download-server/) with version 10.8 -- Installed [oauth2 app](https://marketplace.owncloud.com/apps/oauth2) -- Command line access to your server - -## Deploying ownCloud Web -Download the [ownCloud Web app](https://marketplace.owncloud.com/apps/web) from the marketplace and enable it: -```console -occ market:install web -``` - -## Configure oauth2 -Within the `Admin` page of ownCloud 10, head into `User Authentication` and add a new client with arbitrary name (e.g. `ownCloud Web`) and redirection URL `https:///index.php/apps/web/oidc-callback.html`. - -{{< figure src="/clients/web/static/oauth2.png" alt="Example OAuth2 entry" >}} - -{{< hint >}} -You can mark the ownCloud web client as `trusted` by clicking the respective checkbox so authorization after authentication gets omitted. -{{< /hint >}} - -{{< hint >}} -If you use OpenID Connect you need to add a new client for ownCloud Web to your identity provider instead. -{{< /hint >}} - -## Configure ownCloud 10 -### Set ownCloud Web address -To set the ownCloud Web address and to display ownCloud Web in the app switcher, add the following line into `config/config.php`: - -```php -'web.baseUrl' => 'https:///index.php/apps/web', -``` - -### Configure link routing -Administrators can optionally decide whether ownCloud Links (public and private links) should be provided by the Classic web interface or by ownCloud Web using the `web.rewriteLinks` option in `config/config.php`. The option defaults to `false` so that the links open in the Classic web interface. Setting it to `true` will redirect all links to ownCloud Web. To redirect all private and public links to ownCloud Web, add the following line into `config/config.php`: - -```php -'web.rewriteLinks' => true, -``` - -### Make ownCloud Web the default web interface -Administrators can optionally decide to make ownCloud Web the default web interface that users see after they log in to ownCloud. By default, the Classic web interface will be presented to users. To present ownCloud Web to users by default, add the following line into `config/config.php`: - -```php -'defaultapp' => 'web', -``` - -{{< hint info >}} -While it is possible to make ownCloud Web the default web interface, the decision should be carefully evaluated. Features are still being added to ownCloud Web and users might need to use the Classic web interface to do certain actions. -{{< /hint >}} - -## Configure ownCloud Web -There are a few config values which need to be set in order for ownCloud Web to work correctly. Please copy the example config below into `config/config.json` and adjust it for your environment: - -```json -{ - "server" : "https://", - "theme": "https:///index.php/apps/web/themes/owncloud/theme.json", - "auth": { - "clientId": "", - "url": "https:///index.php/apps/oauth2/api/v1/token", - "authUrl": "https:///index.php/apps/oauth2/authorize", - "logoutUrl": "https:///index.php/logout" - }, - "apps" : [ - "files", - "preview", - "search" - ], - "applications" : [ - { - "title": { - "en": "Classic Design", - "de": "Klassisches Design", - "fr": "Design classique", - "zh": "文件" - }, - "icon": "swap-box", - "url": "https:///index.php/apps/files" - }, - { - "icon": "settings-4", - "menu": "user", - "target": "_self", - "title": { - "de": "Einstellungen", - "en": "Settings" - }, - "url": "https:///index.php/settings/personal" - } - ] -} -``` - -{{< hint info >}} -If any issues arise when trying to access the new design, a good start for debugging it is to run your `config.json` file through a json validator of your choice. -{{< /hint >}} - -|config parameter|explanation| -|---|---| -|server|ownCloud 10 server address| -|theme|Theme to be used in ownCloud Web pointing to a json file inside of `themes` folder| -|auth.clientId|Client ID received when adding ownCloud Web in the `User Authentication` section in `Admin`| -|apps|List of internal extensions to be loaded| -|applications|Additional apps and links to be displayed in the application switcher or in the user menu| -|applications[0].title|Visible title in the application switcher or user menu, localizable| -|applications[1].menu|Use `user` to move the menu item into the user menu. Defaults to app switcher| - -{{< hint info >}} -It is important that you don't edit or place the `config.json` within the app folder. If you do, the integrity check of the app will fail and raise warnings. -{{< /hint >}} - -{{< hint >}} -If you use OpenID Connect you need to replace the `"auth"` part with following configuration: - -```json - "openIdConnect": { - "metadata_url": "/.well-known/openid-configuration", - "authority": "", - "client_id": "", - "response_type": "code", - "scope": "openid profile email" - } -``` -{{< /hint >}} - -## Integrate ownCloud Classic features in ownCloud Web -### Add links to the app switcher -ownCloud Classic features that are not deeply integrated with the Classic UI (e.g., full screen apps) can be added to the ownCloud Web app switcher so that users can easily access them from ownCloud Web. You can use the following example and customize it according to your needs. - -{{< hint info >}} -All apps that are listed in the ownCloud Classic app switcher will be added as links to the app switcher of the new ownCloud Web automatically. All of those links will open in a new browser tab on click. -{{< /hint >}} - -To add new elements in the app switcher, paste the following into the `applications` section of `config.json`: - -```json - { - "title": { - "en": "Custom Groups", - "de": "Benutzerdefinierte Gruppen" - }, - "icon": "settings-4", - "url": "https:///settings/personal?sectionid=customgroups" - } -``` - -{{< hint info >}} -The URL in the example might need adaptations depending on the configuration of your ownCloud Server. App switcher elements added this way will open the respective page in a new tab. This method can also be used to link external sites like Help pages or similar. -{{< /hint >}} - -### Add links to the user menu -Just like adding links to the app switcher, you can also add links to the user menu. - -```json - { - "icon": "settings-4", - "menu": "user", - "target": "_self", - "title": { - "de": "Hilfe", - "en": "Help" - }, - "url": "https://help-link.example" - } -``` - -This will add a link to the specified URL in the user menu. This way, the link will open in the same tab. If you instead want to open it in a new tab, just remove the line `"target": "_self",`. - -### ONLYOFFICE -For ONLYOFFICE there is a [native integration](https://github.com/ONLYOFFICE/onlyoffice-owncloud-web) available for ownCloud Web when it is used with ownCloud Classic Server. It fully integrates the ONLYOFFICE Document Editors and allows users to create and open documents right from ownCloud Web. - -To be able to use ONLYOFFICE in ownCloud Web, it is required to run -- ownCloud Server >= 10.8 -- ownCloud Web >= 4.0.0 -- [ONLYOFFICE Connector for ownCloud Classic](https://marketplace.owncloud.com/apps/onlyoffice) >= 7.1.1 - -Make sure that ONLYOFFICE works as expected in the Classic UI and add the following to `config.json` to make it available in ownCloud Web: - -```json -"external_apps": [ - { - "id": "onlyoffice", - "path": "https:///apps-external/onlyoffice/js/web/onlyoffice.js" - } -] -``` - -{{< hint info >}} -The URL in the example might need adaptations depending on the configuration of your ownCloud Server. -{{< /hint >}} - -### Collabora Online -For Collabora Online there is a native integration available for ownCloud Web when it is used with ownCloud Classic Server. It fully integrates the Collabora Online Document Editors and allows users to create and open documents right from ownCloud Web. - -To be able to use Collabora Online in ownCloud Web, it is required to run -- ownCloud Server >= 10.8 -- ownCloud Web >= 4.0.0 -- [Collabora Online Connector for ownCloud Classic](https://marketplace.owncloud.com/apps/richdocuments) >= 2.7.0 - -Make sure that Collabora Online works as expected in the Classic UI and add the following to `config.json` to make it available in ownCloud Web: - -```json -"external_apps": [ - { - "id": "richdocuments", - "path": "https:///apps/richdocuments/js/richdocuments.js" - } -] -``` - -{{< hint info >}} -The URL in the example might need adaptations depending on the configuration of your ownCloud Server. -{{< /hint >}} - -## Additional configuration for certain core apps -There is additional configuration available for certain core apps. You can find them listed below. - -### Preview app -In case the backend has additional preview providers configured there is no mechanism, yet, to announce those to the `Preview` app in ownCloud Web. As an intermediate solution you can add the additional supported mimeTypes to the `Preview` app by following these steps: -1. Remove the `"preview"` string from the `"apps"` section in your `config.json` file -2. Add the following config to your `config.json` file: -```json -"external_apps": [ - { - "id": "preview", - "path": "web-app-preview", - "config": { - "mimeTypes": ["image/tiff", "image/webp"] - } - } - ] -``` - -If you already have an `"external_apps"` section, just add the preview app to the list. Please adjust the `"mimeTypes"` list according to your additional preview providers. See https://github.com/owncloud/files_mediaviewer#supporting-more-media-types for advise on how to add preview providers to the backend. - -### Text-Editor app -The `text-editor` app provides a list of file extensions that the app is associated with, both for opening files and for creating new files. -By default, only `.txt` and `.md` files appear in the file creation menu and offer the text-editor as default app on a left mouse click -in the file list. For other file types the text-editor app only appears in the right mouse click context menu. In case you want to change this -default set of primary file extensions for the text-editor you can overwrite it as follows: -1. Remove the `"text-editor"` string from the `"apps"` section in your `config.json` file -2. Add the following config to your `config.json` file: -```json -"external_apps": [ - { - "id": "text-editor", - "path": "web-app-text-editor", - "config": { - "primaryExtensions": ["txt", "yaml"] - } - } - ] -``` -With the above example config the text editor will offer creation of new files for `.txt` and `.yaml` files instead of `.txt` and `.md` files. -Also, a left mouse click on any `.txt` or `.yaml` file will open the respective file in the text-editor app. In this example, `.md` files would -not be opened in the text-editor by default anymore, but the text-editor will would appear in the context menu for the file as alternative app. - -If you already have an `"external_apps"` section, just add the preview app to the list. Please adjust the `"mimeTypes"` list according to your additional preview providers. See https://github.com/owncloud/files_mediaviewer#supporting-more-media-types for advise on how to add preview providers to the backend. - -{{< hint info >}} -The reason why the app needs to be ported from the `apps` section to the `external_apps` section is that only the `external_apps` support additional configuration. There are plans to change the configuration of apps to give you a coherent admin experience in that regard. -{{< /hint >}} - -## Accessing ownCloud Web -After following all the steps, you should see a new entry in the application switcher called `New Design` which points to the ownCloud web. - -{{< figure src="/clients/web/static/application-switcher-oc10.jpg" alt="ownCloud 10 application switcher" >}} diff --git a/docs/development/conventions.md b/docs/development/conventions.md index f5e0212dd9f..9cf3832dc8f 100644 --- a/docs/development/conventions.md +++ b/docs/development/conventions.md @@ -23,7 +23,7 @@ for a suitable one and open a pull request! To make sure your pull request can be efficiently reviewed and won't need a lot of changes down the road, please run the linter and the unit tests via `pnpm lint --fix` and `pnpm test:unit` locally. Our [CI](https://drone.owncloud.com/owncloud/web) will run on pull requests and report back any problems after that. For a further introduction on how we handle testing, please head to -the [testing docs]({{< ref "../testing/_index.md" >}}). +the [testing docs]({{< ref "../development/testing.md" >}}). ### Changelog Items diff --git a/docs/testing/e2e-testing-standards.md b/docs/development/e2e-testing-standards.md similarity index 99% rename from docs/testing/e2e-testing-standards.md rename to docs/development/e2e-testing-standards.md index 4c37b054662..948f43d66b1 100644 --- a/docs/testing/e2e-testing-standards.md +++ b/docs/development/e2e-testing-standards.md @@ -3,7 +3,7 @@ title: 'End-to-End (E2E) Test Standards' date: 2024-09-11T00:00:00+00:00 weight: 60 geekdocRepo: https://github.com/owncloud/web -geekdocEditPath: edit/master/docs/testing +geekdocEditPath: edit/master/docs/development geekdocFilePath: e2e-testing-standards.md --- diff --git a/docs/releasing.md b/docs/development/releasing.md similarity index 100% rename from docs/releasing.md rename to docs/development/releasing.md diff --git a/docs/development/repo-structure.md b/docs/development/repo-structure.md index edd41c901c1..730e946b212 100644 --- a/docs/development/repo-structure.md +++ b/docs/development/repo-structure.md @@ -36,7 +36,7 @@ Having these packages side by side within the `/packages` folder of the repo is We're using the [Playwright](https://playwright.dev) 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" >}}) +You can read more about testing in our [testing section]({{< ref "../development/testing.md" >}}) ### package.json File diff --git a/docs/testing/testing.md b/docs/development/testing.md similarity index 92% rename from docs/testing/testing.md rename to docs/development/testing.md index 46b58a60575..cb5fc3c92a0 100644 --- a/docs/testing/testing.md +++ b/docs/development/testing.md @@ -3,7 +3,7 @@ title: 'Running tests' date: 2021-07-27T00:00:00+00:00 weight: 60 geekdocRepo: https://github.com/owncloud/web -geekdocEditPath: edit/master/docs/testing +geekdocEditPath: edit/master/docs/development geekdocFilePath: testing.md --- @@ -132,11 +132,11 @@ To see all available options run node tests/e2e/cucumber/report --help ``` -### E2E Tests on oCIS With Keycloak -We can run some of the e2e tests on oCIS setup with Keycloak as an external idp. To run tests against locally, please follow the steps below: +### E2E Tests with Keycloak +We can run some of the e2e tests with Keycloak as an external idp. To run tests against locally, please follow the steps below: -#### Run oCIS With Keycloak -There's a documentation to serve [oCIS with Keycloak](https://owncloud.dev/ocis/deployment/ocis_keycloak/). Please follow each step to run **oCIS with Keycloak**. +#### Run oCIS with Keycloak +Please follow each step of the documentation on how to serve [oCIS with Keycloak](https://owncloud.dev/ocis/deployment/ocis_keycloak/). #### Run E2E Tests ```bash diff --git a/docs/development/tooling.md b/docs/development/tooling.md index 2da762fb3ce..d93a5b4efa9 100644 --- a/docs/development/tooling.md +++ b/docs/development/tooling.md @@ -43,10 +43,3 @@ Now you can access Web via https://host.docker.internal:9200. ### Using Instant Hot-Reload via Vite To work with instant hot-reloading, you can also build Web by running `pnpm vite`. The port to access Web is slightly different then: https://host.docker.internal:9201. Also note that the initial page load may take a bit longer than usual. This is normal and to be expected. - -### Running Web with oC10 - -Older versions of Web (< 7.1.0) also support running oC10 as server. The development setup is nearly the same as mentioned above, the only differences are: - -* The server can be started via `docker-compose up oc10` -* The server port is `8080` (`8081` when running Web via `pnpm vite:oc10`) diff --git a/docs/getting-started.md b/docs/getting-started.md index 5633f9380fc..955d3f66595 100644 --- a/docs/getting-started.md +++ b/docs/getting-started.md @@ -97,13 +97,29 @@ integration libraries. ## Setting up backend and running -Newer versions of Web (> 7.0.2) can only run against [oCIS](https://github.com/owncloud/ocis), whereas older versions (< 7.1.0) can run against [ownCloud 10](https://github.com/owncloud/core/) as well. -Depending which one you chose, please check the matching section: +Newer versions of Web (> 7.0.2) can only run against [oCIS](https://github.com/owncloud/ocis). -- [Setting up with oCIS as backend]({{< ref "backend-ocis.md" >}}) -- [Setting up with ownCloud as backend]({{< ref "backend-oc10.md" >}}) +### Setting up Web -## Running +- Clone the [repository](https://github.com/owncloud/web/) +- Initally install all dependencies by running `pnpm install` +- Copy `./config/config.json.sample-ocis` to `./config/config.json` and adjust values if required -- [Running with oCIS as backend]({{< ref "backend-ocis.md#running-web" >}}) -- [Running with ownCloud as backend]({{< ref "backend-oc10.md#running-web" >}}) +### Running Web + +- Start bundling web with a watcher by running `pnpm build:w` + +### Setting up oCIS + +- Setup oCIS by following the [setup instructions](https://owncloud.dev/ocis/getting-started/) +- Start oCIS with local links to your bundled web frontend and config by running `WEB_ASSET_CORE_PATH=../../web/dist WEB_UI_CONFIG_FILE=../../web/dist/config.json OCIS_INSECURE=true IDM_CREATE_DEMO_USERS=true ./bin/ocis server` (and make sure to adjust paths as necessary) + +### Start oCIS + +- open [https://localhost:9200](https://localhost:9200) and accept the certificate +- when signing in, use one of the [available demo users](https://owncloud.dev/ocis/getting-started/demo-users/) +- whenever code changes are made, you need to manually reload the browser page (no hot reload) + +## Running tests + +For testing, please refer to the [testing docs]({{< ref "development/testing.md" >}}) diff --git a/docs/static/application-switcher-oc10.jpg b/docs/static/application-switcher-oc10.jpg deleted file mode 100644 index f1abf6bfaa9..00000000000 Binary files a/docs/static/application-switcher-oc10.jpg and /dev/null differ diff --git a/docs/static/oauth2.png b/docs/static/oauth2.png deleted file mode 100644 index c948efae8ab..00000000000 Binary files a/docs/static/oauth2.png and /dev/null differ diff --git a/docs/testing/_index.md b/docs/testing/_index.md deleted file mode 100644 index 832263e0472..00000000000 --- a/docs/testing/_index.md +++ /dev/null @@ -1,11 +0,0 @@ ---- -title: "Tests" -date: 2022-01-28T00:00:00+00:00 -weight: 55 -geekdocRepo: https://github.com/owncloud/web -geekdocEditPath: edit/master/docs/testing -geekdocFilePath: _index.md -geekdocCollapseSection: true ---- - -Guides on running different kinds of tests in ownCloud Web. diff --git a/docs/theming/_index.md b/docs/theming/_index.md index a4cf536e32a..51e8e0b11e5 100644 --- a/docs/theming/_index.md +++ b/docs/theming/_index.md @@ -23,7 +23,7 @@ Generally, your theming configuration lives inside a `.json` file, e.g. `theme.j To reference your theme, you have two options: - Using a URL, e.g. `"theme": "https://externalurl.example.com/theme-name/theme.json",`. To avoid CORS issues, please make sure that you host the URL on the same URL as your ownCloud web hosting. -- For development and testing purposes, you can store your `theme.json` inside `packages/web-runtime/themes/{theme-name}/` and reference it in the `config.json`. However, this isn't recommended for production use since your changes may get lost when updating oCIS or the `web` app in OC10. +- For development and testing purposes, you can store your `theme.json` inside `packages/web-runtime/themes/{theme-name}/` and reference it in the `config.json`. However, this isn't recommended for production use since your changes may get lost when updating oCIS. **Hint:** If no theme is provided, the loading of your custom theme fails or the theme can't be parsed correctly, the standard ownCloud theme will be loaded as a fallback and an error with further information will be logged on the browser console.