diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 71675491..599ecd0f 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -17,14 +17,14 @@ We welcome suggestions for improvements. To propose an enhancement, [open a new 1. **Fork the Repository**: Click the "Fork" button at the top right of the repository page. 2. **Clone Your Fork**: - ```bash + ```shell git clone https://github.com/opencloud-eu/docs.git cd docs ``` 3. **Create a New Branch**: - ```bash + ```shell git checkout -b feature/your-feature-name ``` @@ -34,13 +34,13 @@ Implement your changes, adhering to the docs style. 5. **Commit Your Changes**: - ```bash + ```shell git commit -m "Brief description of your changes" ``` 6. **Push to Your Fork**: - ```bash + ```shell git push origin feature/your-feature-name ``` diff --git a/README.md b/README.md index ceba6a03..0c63f890 100644 --- a/README.md +++ b/README.md @@ -4,7 +4,7 @@ This website is built using [Docusaurus](https://docusaurus.io/), a modern stati ### Installation -```bash +```shell pnpm install ``` @@ -12,7 +12,7 @@ pnpm install clone this repository -```bash +```shell pnpm start ``` @@ -22,7 +22,7 @@ This command starts a local development server and opens up a browser window. Mo To see the docs in German you need to start it with the following command -```bash +```shell pnpm run start --locale de ``` @@ -30,7 +30,7 @@ It is not possible to switch between the languages via the language switcher ### Build -```bash +```shell pnpm build ``` @@ -40,13 +40,13 @@ This command generates static content into the `build` directory and can be serv Using SSH: -```bash +```shell USE_SSH=true pnpm deploy ``` Not using SSH: -```bash +```shell GIT_USER= pnpm deploy ``` diff --git a/assets/likec4/README.md b/assets/likec4/README.md index 1b09f12e..ab087e39 100644 --- a/assets/likec4/README.md +++ b/assets/likec4/README.md @@ -31,7 +31,7 @@ These are automatically generated during the build process and updated with each The project has a built-in script to render the C4 models: -```bash +```shell # Install dependencies pnpm install diff --git a/docs/admin/configuration/authentication-and-user-management/external-idp.md b/docs/admin/configuration/authentication-and-user-management/external-idp.md index f7233049..b754137f 100644 --- a/docs/admin/configuration/authentication-and-user-management/external-idp.md +++ b/docs/admin/configuration/authentication-and-user-management/external-idp.md @@ -12,51 +12,37 @@ The following environment variables are relevant when connecting OpenCloud to an - `OC_OIDC_ISSUER`: Set this to the issuer URL of the external Identity Provider - `OC_EXCLUDE_RUN_SERVICES`: To disable the built-in Identity Provider set this to `idp` -- `PROXY_OIDC_REWRITE_WELLKNOWN`: Set this to `true` to expose the Identity - Providers `.well-known/openid-configuration` via the OpenCloud base url. This - help the oidc client, that do not yet support discovery via webfinger to - locate the Identity Provider's configuration. -- `PROXY_USER_OIDC_CLAIM` and `PROXY_USER_CS3_CLAIM`: These two variables - configure how the users mapped between the Identity Provider and OpenCloud. - `PROXY_USER_OIDC_CLAIM` defines the OIDC claim that OpenCloud uses to - uniquely identify a user. It is matched against the OpenCloud user attribute - defined in `PROXY_USER_CS3_CLAIM`. E.g. if `PROXY_USER_OIDC_CLAIM` is set to - `preferred_username` and `PROXY_USER_CS3_CLAIM` is set to `username` then an - OpenID Connect user, that has the `preferred_username` set to `alan` will map - to the OpenCloud user with username `alan`. -- `PROXY_AUTOPROVISION_ACCOUNTS` and `GRAPH_USERNAME_MATCH`: When - `PROXY_AUTOPROVISION_ACCOUNTS` is set to `true`, OpenCloud will create a new - user account in the LDAP Database for every user who logs in via OpenID - Connect for the first time. Enabling this requires access to a writable LDAP - server. For smaller setups this can be the built-in LDAP server provided by - the `idm` service. If set to `false` all users logging in must already be - existing in the LDAP server. (The mapping between the OIDC and LDAP users - happens based on the aforementioned `PROXY_USER_OIDC_CLAIM` and - `PROXY_USER_CS3_CLAIM` settings. Set `GRAPH_USERNAME_MATCH` to `none` when - `PROXY_AUTOPROVISION_ACCOUNTS` is set to `true` to disable OpenCloud's - default restrictions on allowed characters in usernames. -- `PROXY_ROLE_ASSIGNMENT_DRIVER` and `GRAPH_ASSIGN_DEFAULT_USER_ROLE`: For - details see below +- `PROXY_OIDC_REWRITE_WELLKNOWN`: Set this to `true` to expose the Identity Providers `.well-known/openid-configuration` + via the OpenCloud base url. This help the oidc client, that do not yet support discovery via webfinger to locate the + Identity Provider's configuration. +- `PROXY_USER_OIDC_CLAIM` and `PROXY_USER_CS3_CLAIM`: These two variables configure how the users mapped between the + Identity Provider and OpenCloud. `PROXY_USER_OIDC_CLAIM` defines the OIDC claim that OpenCloud uses to uniquely + identify a user. It is matched against the OpenCloud user attribute defined in `PROXY_USER_CS3_CLAIM`. E.g. if + `PROXY_USER_OIDC_CLAIM` is set to `preferred_username` and `PROXY_USER_CS3_CLAIM` is set to `username` then an OpenID + Connect user, that has the `preferred_username` set to `alan` will map to the OpenCloud user with username `alan`. +- `PROXY_AUTOPROVISION_ACCOUNTS` and `GRAPH_USERNAME_MATCH`: When `PROXY_AUTOPROVISION_ACCOUNTS` is set to `true`, + OpenCloud will create a new user account in the LDAP Database for every user who logs in via OpenID Connect for the + first time. Enabling this requires access to a writable LDAP server. For smaller setups this can be the built-in LDAP + server provided by the `idm` service. If set to `false` all users logging in must already be existing in the LDAP + server. (The mapping between the OIDC and LDAP users happens based on the aforementioned `PROXY_USER_OIDC_CLAIM` and + `PROXY_USER_CS3_CLAIM` settings. Set `GRAPH_USERNAME_MATCH` to `none` when `PROXY_AUTOPROVISION_ACCOUNTS` is set to + `true` to disable OpenCloud's default restrictions on allowed characters in usernames. +- `PROXY_ROLE_ASSIGNMENT_DRIVER` and `GRAPH_ASSIGN_DEFAULT_USER_ROLE`: For details see below ### Automatic Role Assignments -When users login into OpenCloud, they get a user role assigned -automatically. The automatic role assignment can be configured in different -ways. The `PROXY_ROLE_ASSIGNMENT_DRIVER` environment variable (or the `driver` -setting in the `role_assignment` section of the configuration file) select which -mechanism to use for the automatic role assignment. +When users login into OpenCloud, they get a user role assigned automatically. The automatic role assignment can be +configured in different ways. The `PROXY_ROLE_ASSIGNMENT_DRIVER` environment variable (or the `driver` setting in the +`role_assignment` section of the configuration file) select which mechanism to use for the automatic role assignment. -When set to `default`, all users which do not have a role assigned at the time -of first login will get the role 'user' assigned. This is also the -default behavior if `PROXY_ROLE_ASSIGNMENT_DRIVER` is unset. +When set to `default`, all users which do not have a role assigned at the time of first login will get the role 'user' +assigned. This is also the default behavior if `PROXY_ROLE_ASSIGNMENT_DRIVER` is unset. -When `PROXY_ROLE_ASSIGNMENT_DRIVER` is set to `oidc` the role assignment for a -user will happen based on the values of an OpenID Connect Claim of that user. -The name of the OpenID Connect Claim to be used for the role assignment can be -configured via the `PROXY_ROLE_ASSIGNMENT_OIDC_CLAIM` environment variable. It -is also possible to define a mapping of claim values to role names defined in -OpenCloud via a `yaml` configuration. See the following `proxy.yaml` snippet -for an example. +When `PROXY_ROLE_ASSIGNMENT_DRIVER` is set to `oidc` the role assignment for a user will happen based on the values of +an OpenID Connect Claim of that user. The name of the OpenID Connect Claim to be used for the role assignment can be +configured via the `PROXY_ROLE_ASSIGNMENT_OIDC_CLAIM` environment variable. It is also possible to define a mapping of +claim values to role names defined in OpenCloud via a `yaml` configuration. See the following `proxy.yaml` snippet for +an example. ```yaml role_assignment: @@ -74,21 +60,20 @@ role_assignment: claim_value: myGuestRole ``` -This would assign the role `admin` to users with the value `myAdminRole` in the claim `opencloudRoles`. -The role `user` to users with the values `myUserRole` in the claims `opencloudRoles` and so on. +This would assign the role `admin` to users with the value `myAdminRole` in the claim `opencloudRoles`. The role `user` +to users with the values `myUserRole` in the claims `opencloudRoles` and so on. Claim values that are not mapped to a specific OpenCloud role will be ignored. -Note: An OpenCloud user can only have a single role assigned. If the configured -`role_mapping` and a user's claim values result in multiple possible roles for a user, the order in -which the role mappings are defined in the configuration is important. The first role in the -`role_mappings` where the `claim_value` matches a value from the user's roles claim will be assigned -to the user. So if e.g. a user's `opencloudRoles` claim has the values `myUserRole` and -`mySpaceAdminRole` that user will get the OpenCloud role `spaceadmin` assigned (because `spaceadmin` -appears before `user` in the above sample configuration). +Note: An OpenCloud user can only have a single role assigned. If the configured `role_mapping` and a user's claim values +result in multiple possible roles for a user, the order in which the role mappings are defined in the configuration is +important. The first role in the `role_mappings` where the `claim_value` matches a value from the user's roles claim +will be assigned to the user. So if e.g. a user's `opencloudRoles` claim has the values `myUserRole` and +`mySpaceAdminRole` that user will get the OpenCloud role `spaceadmin` assigned (because `spaceadmin` appears before +`user` in the above sample configuration). -If a user's claim values don't match any of the configured role mappings an error will be logged and -the user will not be able to login. +If a user's claim values don't match any of the configured role mappings an error will be logged and the user will not +be able to login. The default `role_claim` (or `PROXY_ROLE_ASSIGNMENT_OIDC_CLAIM`) is `roles`. The default `role_mapping` is: @@ -103,7 +88,8 @@ The default `role_claim` (or `PROXY_ROLE_ASSIGNMENT_OIDC_CLAIM`) is `roles`. The claim_value: opencloudGuest ``` -Note: When `PROXY_ROLE_ASSIGNMENT_DRIVER` is set to `oidc` it is recommended to set `GRAPH_ASSIGN_DEFAULT_USER_ROLE` to `false`. +Note: When `PROXY_ROLE_ASSIGNMENT_DRIVER` is set to `oidc` it is recommended to set `GRAPH_ASSIGN_DEFAULT_USER_ROLE` to +`false`. ## Client Configuration diff --git a/docs/admin/configuration/authentication-and-user-management/index.md b/docs/admin/configuration/authentication-and-user-management/index.md index 5aa4d250..284d02d7 100644 --- a/docs/admin/configuration/authentication-and-user-management/index.md +++ b/docs/admin/configuration/authentication-and-user-management/index.md @@ -18,21 +18,28 @@ OpenCloud employs a dual-track authentication strategy: ## Authentication with Keycloak -For production environments, we recommend using Keycloak with LDAP integration. This setup provides a robust authentication system that can scale to enterprise needs. +For production environments, we recommend using Keycloak with LDAP integration. This setup provides a robust +authentication system that can scale to enterprise needs. OpenCloud now supports two authentication modes when using Keycloak with LDAP: ### Shared User Directory Mode -In this mode, LDAP serves as a central user directory for both Keycloak and OpenCloud. -This setup is suitable for scenarios where the LDAP server is not under the control of the OpenCloud admin and can be connected to KeyCloak and OpenCloud using standard attributes and a read-only bind user. +In this mode, LDAP serves as a central user directory for both Keycloak and OpenCloud. This setup is suitable for +scenarios where the LDAP server is not under the control of the OpenCloud admin and can be connected to KeyCloak and +OpenCloud using standard attributes and a read-only bind user. -For detailed configuration and setup instructions, see the [Keycloak Shared User Directory](./keycloak#shared-user-directory-mode) guide. +For detailed configuration and setup instructions, see the +[Keycloak Shared User Directory](./keycloak#shared-user-directory-mode) guide. ### Autoprovisioning Mode -In this mode, Keycloak is holding all users and OpenCloud autoprovisions new users during first login. -This mode is suitable in scenarios where the OpenIDConnect provider is external and not under control of the OpenCloud admin. To mitigate that lack of control, OpenCloud will use an LDAP server which is fully under the control of the OpenCloud admin to store the users and groups and additional attributes. -OpenCloud can disable users for login to actively prevent unwanted access to the system when the workflow with the external Identity Provider is slow or indirect. In this case, the LDAP server needs an OpenCloud Schema and write access for the LDAP bind user. +In this mode, Keycloak is holding all users and OpenCloud autoprovisions new users during first login. This mode is +suitable in scenarios where the OpenIDConnect provider is external and not under control of the OpenCloud admin. To +mitigate that lack of control, OpenCloud will use an LDAP server which is fully under the control of the OpenCloud admin +to store the users and groups and additional attributes. OpenCloud can disable users for login to actively prevent +unwanted access to the system when the workflow with the external Identity Provider is slow or indirect. In this case, +the LDAP server needs an OpenCloud Schema and write access for the LDAP bind user. -For detailed configuration and setup instructions, see the [Keycloak with Autoprovisioning](./keycloak#autoprovisioning-mode) guide. +For detailed configuration and setup instructions, see the +[Keycloak with Autoprovisioning](./keycloak#autoprovisioning-mode) guide. diff --git a/docs/admin/configuration/authentication-and-user-management/keycloak.md b/docs/admin/configuration/authentication-and-user-management/keycloak.md index e7cde01a..99fa97d5 100644 --- a/docs/admin/configuration/authentication-and-user-management/keycloak.md +++ b/docs/admin/configuration/authentication-and-user-management/keycloak.md @@ -6,18 +6,25 @@ title: Keycloak Integration # Keycloak Integration -OpenCloud supports using Keycloak as an external identity provider, providing enterprise-grade identity management capabilities. This guide explains how to set up and configure Keycloak with OpenCloud. -This guide is divided into three main sections: +OpenCloud supports using Keycloak as an external identity provider, providing enterprise-grade identity management +capabilities. This guide explains how to set up and configure Keycloak with OpenCloud. This guide is divided into three +main sections: -- **[Keycloak Integration Overview](#opencloud-configuration-for-keycloak-general)**: A brief overview of the integration process. -- **[Shared User Directory Mode](#configuration-for-shared-directory-mode)**: Keycloak and OpenCloud share a common LDAP directory for user management. -- **[Autoprovisioning Mode](#configuration-for-autoprovisioning-mode)**: OpenCloud autoprovisions users in a separate LDAP directory managed by OpenCloud. +- **[Keycloak Integration Overview](#opencloud-configuration-for-keycloak-general)**: A brief overview of the + integration process. +- **[Shared User Directory Mode](#configuration-for-shared-directory-mode)**: Keycloak and OpenCloud share a common LDAP + directory for user management. +- **[Autoprovisioning Mode](#configuration-for-autoprovisioning-mode)**: OpenCloud autoprovisions users in a separate + LDAP directory managed by OpenCloud. ## OpenCloud Configuration for Keycloak (General) -When using Keycloak as the identity provider, you need to understand the general configuration settings if you want to configure your custom integration. +When using Keycloak as the identity provider, you need to understand the general configuration settings if you want to +configure your custom integration. -You can also use one of our predefined Docker Compose setups, which are located in the `deployments/examples/opencloud_full` directory. These setups include all necessary configurations for Keycloak and OpenLDAP. +You can also use one of our predefined Docker Compose setups, which are located in the +`deployments/examples/opencloud_full` directory. These setups include all necessary configurations for Keycloak and +OpenLDAP. ### Server Configuration @@ -36,11 +43,13 @@ GRAPH_USERNAME_MATCH=none OC_EXCLUDE_RUN_SERVICES=idp,idm # it is not supported to run keycloak with the built-in idm ``` -Look [OpenCloud external IDP configuration](./external-idp.md#opencloud-configuration) for some more details about these settings. +Look [OpenCloud external IDP configuration](./external-idp.md#opencloud-configuration) for some more details about these +settings. ### Client Configuration -The [OIDC clients](./external-idp.md#client-configuration) required by OpenCloud are pre-configured in the Docker Compose setup and match the clients used by the built-in IdP. +The [OIDC clients](./external-idp.md#client-configuration) required by OpenCloud are pre-configured in the Docker +Compose setup and match the clients used by the built-in IdP. ### Manual Client Configuration @@ -62,7 +71,8 @@ If you need to manually configure the clients in Keycloak: #### Backchannel Logout -OpenCloud supports Keycloak's backchannel logout feature, which allows Keycloak to notify OpenCloud when a user logs out. This ensures that all sessions are properly terminated: +OpenCloud supports Keycloak's backchannel logout feature, which allows Keycloak to notify OpenCloud when a user logs +out. This ensures that all sessions are properly terminated: - **Backchannel Logout URL**: `https://your-domain.example.com/backchannel_logout` - **Backchannel Logout Session Required**: `true` @@ -95,13 +105,15 @@ graph TD class opencloud general; ``` -In this mode, a readable LDAP Directory with existing users serves as a central user directory for both Keycloak and OpenCloud. +In this mode, a readable LDAP Directory with existing users serves as a central user directory for both Keycloak and +OpenCloud. **Key characteristics:** - LDAP is the source of truth for user information - The LDAP server uses standard attributes (uid, cn, sn, givenName, mail) -- A common unique identifier (e.g. `entryUUID` or `objectGUID`) guarantees stable user mapping even if users are changing +- A common unique identifier (e.g. `entryUUID` or `objectGUID`) guarantees stable user mapping even if users are + changing - Both Keycloak and OpenCloud read user data directly from LDAP - User accounts must exist in LDAP before they can log in or receive shares - LDAP is configured as read-only for OpenCloud @@ -117,7 +129,7 @@ OpenCloud can work with any LDAP schema containing standard attributes: **Example LDAP Structure:** -```bash +```shell dc=example,dc=org # Base DN ├── ou=users # User organizational unit │ ├── uid=user1 # User entries @@ -132,7 +144,8 @@ dc=example,dc=org # Base DN :::tip -It is possible to use a writable subtree of the LDAP server for custom groups. This is useful if you want to create groups in OpenCloud that are not managed by Keycloak. +It is possible to use a writable subtree of the LDAP server for custom groups. This is useful if you want to create +groups in OpenCloud that are not managed by Keycloak. This feature is optional and can be disabled by setting `GRAPH_LDAP_GROUP_CREATE_BASE_DN` to an empty string. @@ -142,7 +155,7 @@ This feature is optional and can be disabled by setting `GRAPH_LDAP_GROUP_CREATE Keycloak and OpenCloud can be configured using environment variables: -```bash +```shell # Basic Keycloak configuration KEYCLOAK_DOMAIN=keycloak.example.org KEYCLOAK_REALM=openCloud @@ -187,7 +200,7 @@ OpenCloud provides complete example deployments using Docker Compose: **For Shared Directory Mode:** -```bash +```shell # Enable services LDAP=:ldap.yml KEYCLOAK_DOMAIN=your-keycloak-domain.example.com # your public keycloak domain without protocol @@ -198,18 +211,24 @@ KEYCLOAK=:keycloak.yml The Docker Compose files `keycloak.yml`, `ldap.yml` contain the complete configuration for each component. -Keycloak is configured during startup by importing the `keycloak-realm.dist.json` file. This file contains the configuration for the OpenCloud realm, including client settings, roles, and user federation. This file is located in the `deployments/examples/opencloud_full/config/keycloak` directory. +Keycloak is configured during startup by importing the `keycloak-realm.dist.json` file. This file contains the +configuration for the OpenCloud realm, including client settings, roles, and user federation. This file is located in +the `deployments/examples/opencloud_full/config/keycloak` directory. :::warning -Keycloak can import the realm configuration file **only once** during the first startup. If you need to change the configuration, you must delete the Keycloak container and volume and restart it. This will reset Keycloak to its initial state. +Keycloak can import the realm configuration file **only once** during the first startup. If you need to change the +configuration, you must delete the Keycloak container and volume and restart it. This will reset Keycloak to its initial +state. ::: ## Autoprovisioning Mode -In this mode, Keycloak is holding all users and OpenCloud autoprovisions new users during first login. -This mode is suitable in scenarios where the OpenIDConnect provider is external and not under control of the OpenCloud admin. To mitigate that lack of control, OpenCloud will use an LDAP server which is fully under the control of the OpenCloud admin to store the users and groups and additional attributes. +In this mode, Keycloak is holding all users and OpenCloud autoprovisions new users during first login. This mode is +suitable in scenarios where the OpenIDConnect provider is external and not under control of the OpenCloud admin. To +mitigate that lack of control, OpenCloud will use an LDAP server which is fully under the control of the OpenCloud admin +to store the users and groups and additional attributes. ```mermaid graph TD @@ -248,13 +267,14 @@ graph TD - The openCloud Clients and Sessions are configured in Keycloak - Simplified user management with "just-in-time" provisioning - Federation with external identity providers is supported (e.g., Google, GitHub, Facebook, Microsoft) -- In this case, we need to provide an LDAP server which is fully controlled by OpenCloud and needs a custom [LDAP Schema](https://github.com/opencloud-eu/opencloud/blob/main/deployments/examples/shared/config/ldap/schemas/10_opencloud_schema.ldif). +- In this case, we need to provide an LDAP server which is fully controlled by OpenCloud and needs a custom + [LDAP Schema](https://github.com/opencloud-eu/opencloud/blob/main/deployments/examples/shared/config/ldap/schemas/10_opencloud_schema.ldif). ### Configuration for Autoprovisioning Mode Keycloak, OpenCloud and OpenLDAP can be configured using environment variables: -```bash +```shell # Basic Keycloak configuration KEYCLOAK_DOMAIN=keycloak.example.org KEYCLOAK_REALM=openCloud @@ -294,7 +314,7 @@ OpenCloud provides complete example deployments using Docker Compose: **For Autoprovisioning Mode:** -```bash +```shell # Enable services LDAP=:ldap.yml KEYCLOAK_DOMAIN=your-keycloak-domain.example.com # your public keycloak domain without protocol @@ -302,13 +322,19 @@ KEYCLOAK=:keycloak.yml KEYCLOAK_AUTOPROVISIONING=:keycloak-autoprovisioning.yml ``` -The Docker Compose files `keycloak.yml`, `ldap.yml`, and `keycloak-autoprovisioning.yml` contain the complete configuration for each component. The file `10_opencloud_ldap_schema.ldif` contains the OpenCloud LDAP schema and is loaded during the startup of the OpenLdap container. +The Docker Compose files `keycloak.yml`, `ldap.yml`, and `keycloak-autoprovisioning.yml` contain the complete +configuration for each component. The file `10_opencloud_ldap_schema.ldif` contains the OpenCloud LDAP schema and is +loaded during the startup of the OpenLdap container. -Keycloak is configured during startup by importing the `keycloak-autoprovisioning-realm.dist.json` file. This file contains the configuration for the OpenCloud realm, including client settings, roles, users and groups. This file is located in the `deployments/examples/opencloud_full/config/keycloak` directory. +Keycloak is configured during startup by importing the `keycloak-autoprovisioning-realm.dist.json` file. This file +contains the configuration for the OpenCloud realm, including client settings, roles, users and groups. This file is +located in the `deployments/examples/opencloud_full/config/keycloak` directory. :::warning -Keycloak can import the realm configuration file **only once** during the first startup. If you need to change the configuration, you must delete the Keycloak container and volume and restart it. This will reset Keycloak to its initial state. +Keycloak can import the realm configuration file **only once** during the first startup. If you need to change the +configuration, you must delete the Keycloak container and volume and restart it. This will reset Keycloak to its initial +state. ::: diff --git a/docs/admin/configuration/logging.md b/docs/admin/configuration/logging.md index 9f1ced1f..234776c3 100644 --- a/docs/admin/configuration/logging.md +++ b/docs/admin/configuration/logging.md @@ -10,13 +10,15 @@ title: Logging ## Introduction -Logging helps monitor OpenCloud’s health and diagnose issues. Log output varies by level, from minimal to detailed. By default, logs are written to `stderr`. In Docker deployments, logs are accessible via `docker logs`. +Logging helps monitor OpenCloud’s health and diagnose issues. Log output varies by level, from minimal to detailed. By +default, logs are written to `stderr`. In Docker deployments, logs are accessible via `docker logs`. --- ## Log Levels -Set the global log level using the `OPEN_CLOUD_LOG_LEVEL` environment variable. You can also override it per service using service-specific variables. Default is `error`. +Set the global log level using the `OPEN_CLOUD_LOG_LEVEL` environment variable. You can also override it per service +using service-specific variables. Default is `error`. ## The log levels are @@ -46,10 +48,11 @@ Highly detailed messages for diagnosing problems. Use cautiously in production d ### X-Request-ID -OpenCloud supports tracing using the `X-Request-ID` header. Clients send a UUID v4 with each request, which is included in backend logs for correlation. +OpenCloud supports tracing using the `X-Request-ID` header. Clients send a UUID v4 with each request, which is included +in backend logs for correlation. To manually test with `curl`, add: -```bash +```shell --header "X-Request-ID: " ``` diff --git a/docs/admin/configuration/mail-notifications.md b/docs/admin/configuration/mail-notifications.md index 37b65895..550fc480 100644 --- a/docs/admin/configuration/mail-notifications.md +++ b/docs/admin/configuration/mail-notifications.md @@ -15,7 +15,7 @@ description: 'How to activate mail notifications in OpenCloud.' Edit the file with your preferred text editor: -```bash +```shell nano .env ``` @@ -40,7 +40,8 @@ SMTP_TRANSPORT_ENCRYPTION=none SMTP_INSECURE=true ``` -⚠️ In the .env file, values should be written without quotation marks. Do not use 'single quotes' or "double quotes" — just enter the plain value. +⚠️ In the .env file, values should be written without quotation marks. Do not use 'single quotes' or "double quotes" — +just enter the plain value. --- @@ -54,11 +55,12 @@ For nano, press Ctrl + O to save and Ctrl + X to exit. Apply the changes by restarting the OpenCloud services: -```bash +```shell docker compose down docker compose up -d ``` --- -OpenCloud is now successfully configured to deliver notification emails, including those triggered by actions such as file sharing. +OpenCloud is now successfully configured to deliver notification emails, including those triggered by actions such as +file sharing. diff --git a/docs/admin/configuration/radicale-integration.md b/docs/admin/configuration/radicale-integration.md index 46dd1ed6..37f4b6a0 100644 --- a/docs/admin/configuration/radicale-integration.md +++ b/docs/admin/configuration/radicale-integration.md @@ -5,31 +5,26 @@ title: Calendar and Contacts Integration with Radicale description: 'How to enable Calendar and Contacts integration via Radicale in OpenCloud.' --- -OpenCloud is able to act as an authenticating reverse proxy for the open-source -CalDAV and CardDAV Server [Radicale](https://radicale.org). With that, users -get a calender- and contacts server out of the box with OpenCloud that can be -used with a wide selection of desktop- and mobile clients without hassle. +OpenCloud is able to act as an authenticating reverse proxy for the open-source CalDAV and CardDAV Server +[Radicale](https://radicale.org). With that, users get a calender- and contacts server out of the box with OpenCloud +that can be used with a wide selection of desktop- and mobile clients without hassle. -The `opencloud_full` deployment example already contains all the required pieces to -setup the integration. This guide explains the required steps to achieve that. +The `opencloud_full` deployment example already contains all the required pieces to setup the integration. This guide +explains the required steps to achieve that. -:::note -The calendar and contacts feature is - until further notice - intended for -non-customers, i.e. please note that it is not covered under our business -license, and we do not provide professional support for it. This means that -this feature is maintained and supported on best effort without warranty. -::: +:::note The calendar and contacts feature is - until further notice - intended for non-customers, i.e. please note that +it is not covered under our business license, and we do not provide professional support for it. This means that this +feature is maintained and supported on best effort without warranty. ::: ## Setting up Calendar and Contacts Integration with Radicale -To use this feature you need at least OpenCloud Version 2.3.0. Earlier releases lack -some of the required features. This guide assumes that you already have a running -deployment based on the `opencloud_full` deployment example. +To use this feature you need at least OpenCloud Version 2.3.0. Earlier releases lack some of the required features. This +guide assumes that you already have a running deployment based on the `opencloud_full` deployment example. ### 1. Configure the `.env` file to deploy Radicale -In the root directory of the `opencloud_full` deployment example, usually `opencloud/deployments/examples/opencloud_full`, -remove the `#` symbol from the line: +In the root directory of the `opencloud_full` deployment example, usually +`opencloud/deployments/examples/opencloud_full`, remove the `#` symbol from the line: ```env #RADICALE=:radicale.yml @@ -37,32 +32,27 @@ remove the `#` symbol from the line: ### 2. Update the deployment -```bash +```shell docker compose up -d ``` -This will launch an additional container (called `radicale`) using the -`opencloudeu/radicale` container image and reconfigure the OpenCloud instance -to automatically forward all authenticated traffic on -`https:///caldav` and -`https:///carddav` to the radicale container adding +This will launch an additional container (called `radicale`) using the `opencloudeu/radicale` container image and +reconfigure the OpenCloud instance to automatically forward all authenticated traffic on +`https:///caldav` and `https:///carddav` to the radicale container adding information about the authenticated users. Radicale is configured to automatically create default calendar and address book for every authenticated user. ## Accessing the Calendar and Address Book -Users should now be able to access their address book and calendar with any -capable CalDAV/CardDAV software (OpenCloud does currently not provide any UI -to access them). +Users should now be able to access their address book and calendar with any capable CalDAV/CardDAV software (OpenCloud +does currently not provide any UI to access them). -As very few clients currently support authentication via OpenID Connect you can use -the "App Token" feature in the user's settings page to generate an application specific -password that can be used for authentication in most existing CalDAV/CardDAV clients. +As very few clients currently support authentication via OpenID Connect you can use the "App Token" feature in the +user's settings page to generate an application specific password that can be used for authentication in most existing +CalDAV/CardDAV clients. -As OpenCloud implements support for the `.well-known/carddav` and `.well-known/caldav` -endpoint. Many clients are able to automatically discover existing calendars and -address books. So the only thing that is needed for those clients to work is -to set `https://` as the target URL for calendars and -address books together with the OpenCloud username as the username and the -generated app token as the password for authentication. +As OpenCloud implements support for the `.well-known/carddav` and `.well-known/caldav` endpoint. Many clients are able +to automatically discover existing calendars and address books. So the only thing that is needed for those clients to +work is to set `https://` as the target URL for calendars and address books together with the +OpenCloud username as the username and the generated app token as the password for authentication. diff --git a/docs/admin/configuration/storage/decomposeds3.md b/docs/admin/configuration/storage/decomposeds3.md index 30f70bf8..a9e19fe5 100644 --- a/docs/admin/configuration/storage/decomposeds3.md +++ b/docs/admin/configuration/storage/decomposeds3.md @@ -6,7 +6,8 @@ title: 'Decomposeds3' # Decomposeds3 Storage Driver -Decomposeds3 is a storage driver for OpenCloud that uses MinIO, an S3-compatible object storage, for handling file storage efficiently. This setup leverages S3’s scalability while integrating seamlessly with OpenCloud. +Decomposeds3 is a storage driver for OpenCloud that uses MinIO, an S3-compatible object storage, for handling file +storage efficiently. This setup leverages S3’s scalability while integrating seamlessly with OpenCloud. --- @@ -22,7 +23,7 @@ Decomposeds3 is a storage driver for OpenCloud that uses MinIO, an S3-compatible Download the `opencloud_full` folder (this folder contains a multi-file Docker Compose configuration): -```bash +```shell git clone https://github.com/opencloud-eu/opencloud.git ``` @@ -30,21 +31,22 @@ git clone https://github.com/opencloud-eu/opencloud.git Navigate to the Docker Compose configuration folder: -```bash +```shell cd opencloud/deployments/examples/opencloud_full ``` Enable `decomposeds3.yml` and `minio.yml` in the `.env` file: -```bash +```shell nano opencloud/deployments/examples/opencloud_full/.env ``` -Find all required environment variables `env` here: [decomposeds3-envs](https://github.com/opencloud-eu/opencloud/blob/main/services/storage-users/pkg/config/config.go#L143-L176) +Find all required environment variables `env` here: +[decomposeds3-envs](https://github.com/opencloud-eu/opencloud/blob/main/services/storage-users/pkg/config/config.go#L143-L176) Start the deployment with Docker Compose: -```bash +```shell docker compose up -d ``` @@ -54,7 +56,7 @@ This starts all necessary containers in the background. Edit the /etc/hosts file and add the following entries for local access: -```bash +```shell 127.0.0.1 cloud.opencloud.test 127.0.0.1 minio.opencloud.test ``` diff --git a/docs/admin/configuration/storage/posixfs.md b/docs/admin/configuration/storage/posixfs.md index 4c1e5164..0ee94412 100644 --- a/docs/admin/configuration/storage/posixfs.md +++ b/docs/admin/configuration/storage/posixfs.md @@ -6,12 +6,15 @@ title: 'PosixFS' # PosixFS Storage Driver -PosixFS is a storage driver that saves OpenClouds files and folders in a folder structure how the user sees that in the web interface or other clients. That is a difference to the previously used driver DecomposedFS, which stores files in a technical folder structure that has limited meaning for admins. +PosixFS is a storage driver that saves OpenClouds files and folders in a folder structure how the user sees that in the +web interface or other clients. That is a difference to the previously used driver DecomposedFS, which stores files in a +technical folder structure that has limited meaning for admins. PosixFS Driver supports two different modes: 1. The _non collaborative mode_ where the filesystem tree in use is exclusively granted to OpenCloud -2. The _collaborative mode_ where modifications of the underlying file tree are permitted by other processes than OpenCloud +2. The _collaborative mode_ where modifications of the underlying file tree are permitted by other processes than + OpenCloud # General Notes @@ -19,34 +22,46 @@ The following general notes apply to both modes of the driver. ## Metadata -To enable OpenCloud to operate without a database, additional metadata is stored using the extended file attributes of each file. If the total size of this metadata exceeds the limitations imposed by the underlying file system, it is automatically moved to a separate metadata file. In such cases, only a reference to this metadata file remains in the extended attributes. This entire process is handled transparently by OpenCloud. +To enable OpenCloud to operate without a database, additional metadata is stored using the extended file attributes of +each file. If the total size of this metadata exceeds the limitations imposed by the underlying file system, it is +automatically moved to a separate metadata file. In such cases, only a reference to this metadata file remains in the +extended attributes. This entire process is handled transparently by OpenCloud. ## Access Model -To ensure reliable operation in _non-collaborative mode_, the underlying file system used by the PosixFS driver **must not** be modified while OpenCloud is running. The assigned file system tree must be exclusively reserved for access by OpenCloud. -All files and directories must be owned by the same user and group under which the OpenCloud process is running. File and directory permissions must allow OpenCloud to read, write, and traverse the entire tree. +To ensure reliable operation in _non-collaborative mode_, the underlying file system used by the PosixFS driver **must +not** be modified while OpenCloud is running. The assigned file system tree must be exclusively reserved for access by +OpenCloud. All files and directories must be owned by the same user and group under which the OpenCloud process is +running. File and directory permissions must allow OpenCloud to read, write, and traverse the entire tree. These conditions are automatically fulfilled as long as the root directory of the assigned tree is writable. ### Assimilation -When OpenCloud starts up, it scans the assigned file system tree for newly added or modified files and directories. During this process, metadata is updated and internal caches are built accordingly. This is referred to as the _assimilation_ of new resources. +When OpenCloud starts up, it scans the assigned file system tree for newly added or modified files and directories. +During this process, metadata is updated and internal caches are built accordingly. This is referred to as the +_assimilation_ of new resources. -It is important to note that assimilation does **not** trigger post-upload checks, such as virus scanning. Since the files are already in their final location within the file system, such checks would be ineffective at this stage and are therefore skipped. +It is important to note that assimilation does **not** trigger post-upload checks, such as virus scanning. Since the +files are already in their final location within the file system, such checks would be ineffective at this stage and are +therefore skipped. However, indexing for the search service **does** take place for assimilated resources. ## Startup -When OpenCloud with PosixFS starts up, it is running over the entire file system to warm up the caches. This might take some time. +When OpenCloud with PosixFS starts up, it is running over the entire file system to warm up the caches. This might take +some time. ## Backup -With PosixFS backup and restore is easy. The entire OpenCloud filesystem tree can be snapshotted regularly and restored as needed. It depends on the filesystem type how that has to be done in detail. +With PosixFS backup and restore is easy. The entire OpenCloud filesystem tree can be snapshotted regularly and restored +as needed. It depends on the filesystem type how that has to be done in detail. ## Migration -PosixFS in this so called _non collaborative mode_ is the default for new installations of OpenCloud. There is currently no way to migrate OpenCloud installations with DecomposedFS backend to PosixFS. +PosixFS in this so called _non collaborative mode_ is the default for new installations of OpenCloud. There is currently +no way to migrate OpenCloud installations with DecomposedFS backend to PosixFS. If that is needed, data needs to be copied into a new installation of OpenCloud. @@ -56,7 +71,8 @@ This describes special aspects of the non collaborative mode. ## External Access -When OpenCloud is shut down, limited manipulation of the underlying file system tree is possible for certain administration tasks such as +When OpenCloud is shut down, limited manipulation of the underlying file system tree is possible for certain +administration tasks such as - adding files and folders - removing files and folders @@ -84,13 +100,16 @@ Involved configuration settings (environment variables) to enable PosixFS are: # PosixFS Collaborative Mode -This section describes the collaborative mode of the PosixFS driver, which allows the file system to be modified while OpenCloud is running. Changes made in this mode are reflected in real time in OpenCloud clients. +This section describes the collaborative mode of the PosixFS driver, which allows the file system to be modified while +OpenCloud is running. Changes made in this mode are reflected in real time in OpenCloud clients. ## Usage -Collaborative mode should always be used with caution. It is intended only for well-defined use cases that are carefully planned, configured, and tested. Operation must take place in a controlled environment. +Collaborative mode should always be used with caution. It is intended only for well-defined use cases that are carefully +planned, configured, and tested. Operation must take place in a controlled environment. -Compared to non-collaborative mode, collaborative mode requires significantly more system resources to monitor the file system. Server hardware must be appropriately sized to handle this increased load. +Compared to non-collaborative mode, collaborative mode requires significantly more system resources to monitor the file +system. Server hardware must be appropriately sized to handle this increased load. ## External Access @@ -105,11 +124,14 @@ The following guidelines are critical for smooth and reliable operation: - Continuously monitor server system resources to identify potential bottlenecks. - Carefully configure components such as Apache Tika to optimize indexing performance. -It is essential to maintain correct file ownership and permissions when modifying the file system externally. Files must be created with the correct user and permissions from the outset. Retroactive changes are discouraged, as assimilation may already be in progress. +It is essential to maintain correct file ownership and permissions when modifying the file system externally. Files must +be created with the correct user and permissions from the outset. Retroactive changes are discouraged, as assimilation +may already be in progress. ## Configuration -In addition to the configuration required for non-collaborative mode, the following setting must be enabled for local file systems such as XFS, ext4, and others: +In addition to the configuration required for non-collaborative mode, the following setting must be enabled for local +file systems such as XFS, ext4, and others: ```env STORAGE_USERS_POSIX_WATCH_FS=true diff --git a/docs/admin/configuration/web-applications.md b/docs/admin/configuration/web-applications.md index f779103c..b6a39dfa 100644 --- a/docs/admin/configuration/web-applications.md +++ b/docs/admin/configuration/web-applications.md @@ -5,7 +5,9 @@ title: Web Aplications description: 'How to enable web applications in OpenCloud.' --- -Administrators have the ability to provide additional web applications to their users. This feature is especially useful for organizations that want to integrate third-party tools or provide internally developed apps within the OpenCloud environment. +Administrators have the ability to provide additional web applications to their users. This feature is especially useful +for organizations that want to integrate third-party tools or provide internally developed apps within the OpenCloud +environment. --- @@ -28,7 +30,7 @@ Find and download the application you want to install. Unzip the downloaded archive and copy the extracted folder into the web application directory. By default, this path is: -```bash +```shell opencloud/services/web/assets/apps ``` @@ -44,9 +46,9 @@ Some OpenCloud apps require additional configuration — for example, the **Exte These configurations can be managed in the following file: -```bash +```shell opencloud/deployments/examples/opencloud_full/config/opencloud/apps.yaml ``` -📘 Note: Configuration details vary between apps. -For specific setup instructions, please refer to the official documentation of the respective app. +📘 Note: Configuration details vary between apps. For specific setup instructions, please refer to the official +documentation of the respective app. diff --git a/docs/admin/getting-started/container/docker-compose-local.md b/docs/admin/getting-started/container/docker-compose-local.md index 34bf22fd..140e7b16 100644 --- a/docs/admin/getting-started/container/docker-compose-local.md +++ b/docs/admin/getting-started/container/docker-compose-local.md @@ -21,7 +21,7 @@ Spin up a temporary local instance of OpenCloud using **Docker Compose**. Clone the OpenCloud repository: -```bash +```shell git clone https://github.com/opencloud-eu/opencloud-compose.git ``` @@ -31,35 +31,37 @@ git clone https://github.com/opencloud-eu/opencloud-compose.git ### cd into the Docker Compose configuration folder -```bash +```shell cd opencloud-compose ``` ### Create environment file -```bash +```shell cp .env.example .env ``` -> **Note:** The repository includes .env.example as a template with default settings and documentation. Your actual .env file is excluded from version control (via .gitignore) to prevent accidentally committing sensitive information like passwords and domain-specific settings. +> **Note:** The repository includes .env.example as a template with default settings and documentation. Your actual .env +> file is excluded from version control (via .gitignore) to prevent accidentally committing sensitive information like +> passwords and domain-specific settings. ### Configure deployment options You can deploy using explicit -f flags: -```bash +```shell docker compose -f docker-compose.yml -f weboffice/collabora.yml -f traefik/opencloud.yml -f traefik/collabora.yml up -d ``` Or by uncomment or adding the COMPOSE_FILE variable in .env: -```bash +```shell COMPOSE_FILE=docker-compose.yml:weboffice/collabora.yml:traefik/opencloud.yml:traefik/collabora.yml ``` Set you initial admin password in the .env -```bash +```shell INITIAL_ADMIN_PASSWORD=YOUR.SECRET.PASSWORD ``` @@ -67,7 +69,7 @@ This is mandatory for security reasons. Otherwise the OpenCloud container will n Start the deployment with Docker Compose: -```bash +```shell docker compose up -d ``` @@ -81,15 +83,18 @@ This starts all necessary containers in the background. Edit the /etc/hosts file and add the following entries for local access: -```bash +```shell 127.0.0.1 cloud.opencloud.test 127.0.0.1 collabora.opencloud.test 127.0.0.1 wopiserver.opencloud.test ``` -Open [https://collabora.opencloud.test](https://collabora.opencloud.test) and accept the self-signed certificate. This step is needed as you can not accept the self-signed certificate if you try to open a .odt document from within the OpenCloud Web UI as Collabora is embedded via an iframe. +Open [https://collabora.opencloud.test](https://collabora.opencloud.test) and accept the self-signed certificate. This +step is needed as you can not accept the self-signed certificate if you try to open a .odt document from within the +OpenCloud Web UI as Collabora is embedded via an iframe. -Accept self signed certificate +Accept self signed +certificate --- diff --git a/docs/admin/getting-started/container/docker-compose/docker-compose.md b/docs/admin/getting-started/container/docker-compose/docker-compose.md index 0c5d4817..1ae978b0 100644 --- a/docs/admin/getting-started/container/docker-compose/docker-compose.md +++ b/docs/admin/getting-started/container/docker-compose/docker-compose.md @@ -9,7 +9,8 @@ description: '🌟 Full-blown featureset including web office.' Install a internet facing OpenCloud with SSL certification with Docker Compose. -This installation documentation is for **Ubuntu and Debian** systems. The software can also be installed on other Linux distributions, but the commands and package managers may differ. +This installation documentation is for **Ubuntu and Debian** systems. The software can also be installed on other Linux +distributions, but the commands and package managers may differ. ## **Prerequisites** @@ -29,7 +30,7 @@ This installation documentation is for **Ubuntu and Debian** systems. The softwa Log into your server via SSH: -```bash +```shell ssh root@YOUR.SERVER.IP ``` @@ -39,15 +40,16 @@ Update your system and install Docker. First, perform an update and upgrade: -```bash +```shell apt update && apt upgrade -y ``` -Install Docker following the [official Docker guide](https://docs.docker.com/engine/install/ubuntu/#install-using-the-repository) +Install Docker following the +[official Docker guide](https://docs.docker.com/engine/install/ubuntu/#install-using-the-repository) Once Docker is installed, enable and start the service: -```bash +```shell systemctl enable docker && systemctl start docker ``` @@ -55,7 +57,7 @@ systemctl enable docker && systemctl start docker Download the necessary configuration files: -```bash +```shell git clone https://github.com/opencloud-eu/opencloud.git ``` @@ -65,7 +67,7 @@ Before requesting real SSL certificates, test the setup with Let's Encrypt’s s Navigate to the OpenCloud configuration folder: -```bash +```shell cd opencloud/deployments/examples/opencloud_full ``` @@ -73,7 +75,7 @@ Edit the `.env` file with the editor of your choice: In our example we use nano -```bash +```shell nano .env ``` @@ -81,13 +83,13 @@ Modify these settings: ### ✅ Disable insecure mode -```bash +```shell # INSECURE=true ``` ### ✅ Set your domain names -```bash +```shell TRAEFIK_DOMAIN=traefik.YOUR.DOMAIN OC_DOMAIN=cloud.YOUR.DOMAIN COLLABORA_DOMAIN=collabora.YOUR.DOMAIN @@ -96,19 +98,19 @@ WOPISERVER_DOMAIN=wopiserver.YOUR.DOMAIN ### ✅ Set your admin password -```bash +```shell ADMIN_PASSWORD=YourSecurePassword ``` ### ✅ Set your email for SSL certification -```bash +```shell TRAEFIK_ACME_MAIL=your@email.com ``` ### ✅ Use Let's Encrypt staging certificates (for testing) -```bash +```shell TRAEFIK_ACME_CASERVER=https://acme-staging-v02.api.letsencrypt.org/directory ``` @@ -142,20 +144,23 @@ OC_DATA_DIR=/your/local/path/opencloud/data Ensure these folders exist and are owned by user and group 1000:1000, which the Docker containers use by default: -```bash +```shell sudo mkdir -p /your/local/path/opencloud/{config,data} sudo chown -R 1000:1000 /your/local/path/opencloud ``` ::: -If these variables are left unset, Docker will use internal volumes, which **do not persist** if the containers are removed — not recommended for real-world use. +If these variables are left unset, Docker will use internal volumes, which **do not persist** if the containers are +removed — not recommended for real-world use. :::caution Security Warning -The user with UID 1000 on your host system will have full access to these mounted directories. This means that any local user account with this ID can read, modify, or delete OpenCloud config and data files. +The user with UID 1000 on your host system will have full access to these mounted directories. This means that any local +user account with this ID can read, modify, or delete OpenCloud config and data files. -This can pose a security risk in shared or multi-user environments. Make sure to implement proper user and permission management and consider isolating access to these directories. +This can pose a security risk in shared or multi-user environments. Make sure to implement proper user and permission +management and consider isolating access to these directories. ::: @@ -163,7 +168,7 @@ This can pose a security risk in shared or multi-user environments. Make sure to Launch OpenCloud using Docker Compose: -```bash +```shell docker compose up -d ``` @@ -173,12 +178,12 @@ This will start all required services in the background. In your web browser, visit: -```bash +```shell https://cloud.YOUR.DOMAIN ``` -You should see a security warning because the staging certificate is not fully trusted. -Same should appear with the other domains you are using. +You should see a security warning because the staging certificate is not fully trusted. Same should appear with the +other domains you are using. Example with Chrome browser: @@ -197,13 +202,13 @@ Once the staging certificate works, switch to a production certificate. #### 1️⃣ Stop Docker Compose -```bash +```shell docker compose down ``` #### 2️⃣ Remove old staging certificates -```bash +```shell docker volume rm opencloud_full_certs ``` @@ -211,19 +216,19 @@ docker volume rm opencloud_full_certs #### 3️⃣ Disable staging mode in `.env` -```bash +```shell nano .env ``` Comment the staging server: -```bash +```shell # TRAEFIK_ACME_CASERVER=https://acme-staging-v02.api.letsencrypt.org/directory ``` #### 4️⃣ Restart OpenCloud with a real SSL certificate -```bash +```shell docker compose up -d ``` @@ -235,7 +240,7 @@ docker compose up -d Open a browser and visit: -```bash +```shell https://cloud.YOUR.DOMAIN ``` @@ -273,7 +278,7 @@ This will include the LDAP and Keycloak service definitions in the Docker Compos ### After starting OpenCloud, Keycloak will be available at -```bash +```shell https://keycloak.your.domain ``` @@ -283,7 +288,7 @@ https://keycloak.your.domain #### 1. Open your browser and go to -```bash +```shell https://keycloak.your.domain ``` @@ -297,45 +302,38 @@ https://keycloak.your.domain #### 3. In the top-left dropdown (labeled Keycloak), switch to the OpenCloud realm -Top left dropdown menue -

+Top left dropdown menue

#### 4. Navigate to the "Users" section and click "Add user" -User section -
+User section
- Fill in a username - Optionally add email, first/last name -- Click "Create" - Fill in userdata -

+- Click "Create" Fill in userdata

#### 5. Go to the "Credentials" tab -- Click "Set password" - Credentials -
+- Click "Set password" Credentials
- Set a temporary password - Enable "Temporary" to force password change on first login (optional) -- Click "Save" - Set password -

+- Click "Save" Set password

#### 6. Go to the "Role Mapping" tab -Role mapping -
+Role mapping
-- Click "Assign role" - Assign role -
-- In the dialog, click "Filter by realm roles" - Filter by realm roles -
+- Click "Assign role" Assign role
+- In the dialog, click "Filter by realm roles" Filter by realm roles
- Choose the appropriate role (e.g., user, admin, etc.) -- Click "Assign" - Realm roles -
+- Click "Assign" Realm roles
The user can now log in via OpenCloud using the Keycloak credentials. diff --git a/docs/admin/getting-started/container/docker.md b/docs/admin/getting-started/container/docker.md index 5f19ad2a..b40588e4 100644 --- a/docs/admin/getting-started/container/docker.md +++ b/docs/admin/getting-started/container/docker.md @@ -20,7 +20,7 @@ description: 'Classic docker setup.' ### 1. Create Required Directories for Bind Mounts -```bash +```shell mkdir -p $HOME/opencloud/opencloud-config mkdir -p $HOME/opencloud/opencloud-data ``` @@ -29,7 +29,7 @@ mkdir -p $HOME/opencloud/opencloud-data ### 2. Pull OpenCloud Image -```bash +```shell docker pull opencloudeu/opencloud-rolling:latest ``` @@ -37,7 +37,7 @@ docker pull opencloudeu/opencloud-rolling:latest ### 3. Initialize OpenCloud (First-time Setup) -```bash +```shell docker run --rm -it \ -v $HOME/opencloud/opencloud-config:/etc/opencloud \ -v $HOME/opencloud/opencloud-data:/var/lib/opencloud \ @@ -53,7 +53,7 @@ You can set your own password using `IDM_ADMIN_PASSWORD=your_password`. If not s ### 4. Start OpenCloud -```bash +```shell docker run \ --name opencloud \ --rm \ diff --git a/docs/admin/getting-started/other/bare-metal.md b/docs/admin/getting-started/other/bare-metal.md index 29a25d02..5b2e5d88 100644 --- a/docs/admin/getting-started/other/bare-metal.md +++ b/docs/admin/getting-started/other/bare-metal.md @@ -7,12 +7,12 @@ description: 'Manual, minimalist setup with essential features.' ## User Guide for Installing OpenCloud -Follow the steps below to install and configure OpenCloud on your system.
-This example is on Linux Ubuntu 24.04 distribution! +Follow the steps below to install and configure OpenCloud on your system.
This example is on Linux Ubuntu 24.04 +distribution! -:::danger[Disclaimer] -Bare-metal deployments are not officially supported by OpenCloud. They are great for quick evaluation but are undocumented and have a minimalist feature set. If you choose this setup, you are on your own. With great power comes great responsibility. -::: +:::danger[Disclaimer] Bare-metal deployments are not officially supported by OpenCloud. They are great for quick +evaluation but are undocumented and have a minimalist feature set. If you choose this setup, you are on your own. With +great power comes great responsibility. ::: --- @@ -22,13 +22,13 @@ Bare-metal deployments are not officially supported by OpenCloud. They are great - Update your package list: - ```bash + ```shell sudo apt update && apt upgrade ``` - Install Git using the following command: - ```bash + ```shell sudo apt install git ``` @@ -36,7 +36,7 @@ Bare-metal deployments are not officially supported by OpenCloud. They are great - Clone the OpenCloud repository: - ```bash + ```shell git clone https://github.com/opencloud-eu/opencloud.git ``` @@ -50,7 +50,7 @@ Bare-metal deployments are not officially supported by OpenCloud. They are great - Install npm (Node Package Manager): - ```bash + ```shell sudo apt install npm -y ``` @@ -58,7 +58,7 @@ Bare-metal deployments are not officially supported by OpenCloud. They are great - Install corepack globally: - ```bash + ```shell sudo npm install -g corepack ``` @@ -66,7 +66,7 @@ Bare-metal deployments are not officially supported by OpenCloud. They are great - Enable `pnpm` using corepack: - ```bash + ```shell corepack enable pnpm ``` @@ -78,7 +78,7 @@ Bare-metal deployments are not officially supported by OpenCloud. They are great - Navigate to the OpenCloud directory: - ```bash + ```shell cd opencloud ``` @@ -86,14 +86,14 @@ Bare-metal deployments are not officially supported by OpenCloud. They are great - Run the build generate process: - ```bash + ```shell make clean generate make -C opencloud build ``` - Initialize OpenCloud with insecure configuration and set an admin password: - ```bash + ```shell ./bin/opencloud init --insecure true --admin-password admin ``` @@ -101,7 +101,7 @@ Bare-metal deployments are not officially supported by OpenCloud. They are great - Start the OpenCloud server: - ```bash + ```shell ./bin/opencloud server ``` diff --git a/docs/admin/getting-started/other/raspberry-pi.md b/docs/admin/getting-started/other/raspberry-pi.md index f0405721..36cd9cd5 100644 --- a/docs/admin/getting-started/other/raspberry-pi.md +++ b/docs/admin/getting-started/other/raspberry-pi.md @@ -6,10 +6,9 @@ title: Raspberry Pi # OpenCloud on Raspberry Pi -:::note -The installation of OpenCloud on a Raspberry Pi is intended for private or non-production use only. -It is not recommended for enterprise or critical environments due to the hardware's limited resources and potential performance constraints. -::: +:::note The installation of OpenCloud on a Raspberry Pi is intended for private or non-production use only. +It is not recommended for enterprise or critical environments due to the hardware's limited resources and potential +performance constraints. ::: ## 1.1 Hardware requirements @@ -37,13 +36,13 @@ The IP for this can be viewed in your router. ### Establish connection via SSH -```bash +```shell ssh pi@YOUR-IP ``` After the first login, you should change the password for security reasons: -```bash +```shell passwd ``` @@ -54,25 +53,25 @@ Detailed installation instructions for Docker can be found here: - Perform update and upgrade: -```bash +```shell sudo apt update && sudo apt upgrade -y ``` - Install Docker via script: -```bash +```shell curl -fsSL test.docker.com -o get-docker.sh && sh get-docker.sh ``` - Add current user to the Docker group: -```bash +```shell sudo usermod -aG docker ${USER} ``` - Check if it's working: -```bash +```shell groups ${USER} ``` @@ -80,31 +79,31 @@ groups ${USER} - Reboot the Raspberry Pi: -```bash +```shell sudo shutdown -r now ``` ## 1.5 Clone OpenCloud repository -```bash +```shell git clone https://github.com/opencloud-eu/opencloud-compose.git ``` ## 1.6 Start the Docker Compose setup -```bash +```shell cd opencloud-compose ``` Copy the `.env.example` file: -```bash +```shell cp .env.example .env ``` Edit the `.env` file: -```bash +```shell nano .env ``` @@ -116,19 +115,20 @@ COMPOSE_FILE=docker-compose.yml:traefik/opencloud.yml Then start Docker: -```bash +```shell docker compose up ``` Now OpenCloud is running locally on your Raspberry Pi, and you can adjust it to your needs. -We will describe how to mount an external disk or USB stick and make OpenCloud available outside the local network using No-IP. +We will describe how to mount an external disk or USB stick and make OpenCloud available outside the local network using +No-IP. ## 1.7 Mount external hard disk or USB stick ### 1. Find your external drive -```bash +```shell lsblk ``` @@ -136,7 +136,7 @@ lsblk ### 2. Format the drive to ext4 -```bash +```shell sudo mkfs.ext4 /dev/sda1 -L DATA ``` @@ -146,26 +146,26 @@ sudo mkfs.ext4 /dev/sda1 -L DATA Open `fstab`: -```bash +```shell sudo nano /etc/fstab ``` Add this line: -```bash +```shell LABEL=DATA /mnt/data ext4 auto,defaults 0 0 ``` ### 4. Create the mount point and set permissions -```bash +```shell sudo mkdir -p /mnt/data sudo chown -R 1000:1000 /mnt/data ``` ### 5. Mount the drive -```bash +```shell sudo mount -a ``` @@ -175,7 +175,7 @@ If an error occurs: Run: -```bash +```shell systemctl daemon-reload ``` @@ -185,13 +185,13 @@ And try mounting again. Stop Docker: -```bash +```shell docker compose down ``` Open the `.env` file: -```bash +```shell cd opencloud-compose nano .env ``` @@ -206,7 +206,7 @@ OC_DATA_DIR=/mnt/data Restart Docker: -```bash +```shell docker compose up ``` @@ -248,7 +248,7 @@ More help: [No-IP Support](https://www.noip.com/support/knowledgebase/how-to-con SSH into your Pi and update the domain: -```bash +```shell cd opencloud-compose docker compose down nano .env @@ -264,7 +264,7 @@ OC_DOMAIN=opencloud.webhop.me Restart Docker: -```bash +```shell docker compose up ``` diff --git a/docs/admin/maintenance/backup.md b/docs/admin/maintenance/backup.md index 2dae4602..929a71d8 100644 --- a/docs/admin/maintenance/backup.md +++ b/docs/admin/maintenance/backup.md @@ -14,7 +14,8 @@ title: 'Backup' - Pure POSIX Setup: All data (configuration, blobs, and metadata) is stored on a POSIX-compliant filesystem. -- Distributed Setup: Blobs are stored on an S3-compliant storage, while configuration and metadata remain on a POSIX-compliant filesystem +- Distributed Setup: Blobs are stored on an S3-compliant storage, while configuration and metadata remain on a + POSIX-compliant filesystem To determine which filesystems are supported, see: Filesystems and Shared Storage diff --git a/docs/admin/maintenance/dataexport.md b/docs/admin/maintenance/dataexport.md index 5d81df01..c20b856a 100644 --- a/docs/admin/maintenance/dataexport.md +++ b/docs/admin/maintenance/dataexport.md @@ -9,7 +9,9 @@ description: 'Information about data export.' ## Files -OpenCloud stores files by default in the file system under the path `/var/lib/opencloud/`. Any other path that is local to the server instance running the OpenCloud backend can be configured as alternative path using the environment variable `OC_BASE_DATA_PATH`. +OpenCloud stores files by default in the file system under the path `/var/lib/opencloud/`. Any other path that is local +to the server instance running the OpenCloud backend can be configured as alternative path using the environment +variable `OC_BASE_DATA_PATH`. Files and folders are stored in a folder structure underneath that base path in folder `data/storage/users/`. @@ -17,7 +19,9 @@ Files are by default stored in the original format and not encrypted. ## Metadata -File metadata is stored in the file system with every file. It is either in the extended file attributes (user namespace) or in a separate metadata file. That file is in the [MessagePack](https://msgpack.org) format and can be read with the CLI tools for that file type. +File metadata is stored in the file system with every file. It is either in the extended file attributes (user +namespace) or in a separate metadata file. That file is in the [MessagePack](https://msgpack.org) format and can be read +with the CLI tools for that file type. ## Configuration diff --git a/docs/admin/maintenance/migrate.md b/docs/admin/maintenance/migrate.mdx similarity index 93% rename from docs/admin/maintenance/migrate.md rename to docs/admin/maintenance/migrate.mdx index 64dfe175..cb24c28e 100644 --- a/docs/admin/maintenance/migrate.md +++ b/docs/admin/maintenance/migrate.mdx @@ -5,12 +5,13 @@ title: 'Migrate' description: 'Guide to migrating data using rclone.' --- -import Tabs from '@theme/Tabs' -import TabItem from '@theme/TabItem' +import Tabs from '@theme/Tabs'; +import TabItem from '@theme/TabItem'; ## 🚀 Migrate Personal Space Data to OpenCloud Using rclone -This guide will help you migrate personal space data from `NextCloud` and `oCIS` to `OpenCloud` using `rclone`. Follow these steps carefully to ensure a smooth migration! +This guide will help you migrate personal space data from `NextCloud` and `oCIS` to `OpenCloud` using `rclone`. Follow +these steps carefully to ensure a smooth migration! ### 1. Generate users token using CLI or API @@ -21,13 +22,13 @@ This guide will help you migrate personal space data from `NextCloud` and `oCIS` Modify `.env` file: -```bash +```shell START_ADDITIONAL_SERVICES="auth-app" ``` Enable `auth-app` service: -```bash +```shell PROXY_ENABLE_APP_AUTH="true" ``` @@ -35,13 +36,13 @@ PROXY_ENABLE_APP_AUTH="true" Access the OpenCloud container: -```bash +```shell docker exec -it opencloud_full-opencloud-1 sh ``` Generate an authentication token for a user (e.g., `alan`) with expiration (`h`, `m`, `s`): -```bash +```shell opencloud auth-app create --user-name=alan --expiration=72h ``` @@ -51,13 +52,13 @@ opencloud auth-app create --user-name=alan --expiration=72h Requires additional configuration! Start the server with: -```bash +```shell AUTH_APP_ENABLE_IMPERSONATION=true ``` Then generate a token via API: -```bash +```shell curl -vk -XPOST 'https://opencloud_url/auth-app/tokens?expiry=72h&userName=alan' -uadmin:admin ``` @@ -69,13 +70,13 @@ curl -vk -XPOST 'https://opencloud_url/auth-app/tokens?expiry=72h&userName=alan' Modify `.env` file: -```bash +```shell START_ADDITIONAL_SERVICES="auth-app" ``` Enable `auth-app` service: -```bash +```shell PROXY_ENABLE_APP_AUTH="true" ``` @@ -83,13 +84,13 @@ PROXY_ENABLE_APP_AUTH="true" Access the oCIS container: -```bash +```shell docker exec -it ocis_full-ocis-1 sh ``` Generate an authentication token for a user (e.g., `einstein`) with expiration (`h`, `m`, `s`): -```bash +```shell ocis auth-app create --user-name=einstein --expiration=72h ``` @@ -99,13 +100,13 @@ ocis auth-app create --user-name=einstein --expiration=72h Requires additional configuration! Start the server with: -```bash +```shell AUTH_APP_ENABLE_IMPERSONATION=true ``` Then generate a token via API: -```bash +```shell curl -vk -XPOST 'https://ocis_url/auth-app/tokens?expiry=72h&userName=einstein' -uadmin:admin ``` @@ -132,7 +133,7 @@ Download and install rclone by following the official guide: 🔗[**rclone.org/i ### 3. Encrypt Authentication Tokens 🔒 -```bash +```shell rclone obscure ``` @@ -142,13 +143,13 @@ rclone obscure Edit the rclone configuration file: -```bash +```shell nano ~/.config/rclone/rclone.conf ``` 📌 Example Configuration: -```bash +```shell [opencloud-admin] type = webdav url = https://opencloud_url/remote.php/webdav @@ -211,7 +212,7 @@ description = nc-bob Use `rclone copy` to transfer data from `oCIS` and `Nextcloud` to `OpenCloud`: -```bash +```shell rclone copy ocis-admin:/ opencloud-admin:/ --no-check-certificate -P # Copy oCIS admin personal space to OpenCloud admin space rclone copy ocis-einstein:/ opencloud-alan:/ --no-check-certificate -P # Copy oCIS bob's personal space to OpenCloud admin space rclone copy nc-bob:/ opencloud-alan:/ --no-check-certificate -P # Copy Nextcloud admin personal space to OpenCloud admin space diff --git a/docs/admin/maintenance/uninstall.md b/docs/admin/maintenance/uninstall.md index bb665ee4..53c0919d 100644 --- a/docs/admin/maintenance/uninstall.md +++ b/docs/admin/maintenance/uninstall.md @@ -7,7 +7,8 @@ description: 'Guide to uninstall OpenCloud.' # Uninstall OpenCloud with Docker Compose -> ⚠️ **Warning:** This guide will completely remove all OpenCloud data. Make sure to back up any important files before proceeding. +> ⚠️ **Warning:** This guide will completely remove all OpenCloud data. Make sure to back up any important files before +> proceeding. --- @@ -15,13 +16,13 @@ description: 'Guide to uninstall OpenCloud.' Navigate to your `opencloud-compose` directory (where your `docker-compose.yml` file is located), then run: -```bash +```shell docker compose down ``` To also remove unnamed volumes and orphan containers: -```bash +```shell docker compose down --volumes --remove-orphans ``` @@ -29,7 +30,7 @@ docker compose down --volumes --remove-orphans To check your existing volumes: -```bash +```shell docker volume ls ``` @@ -41,13 +42,13 @@ Typical OpenCloud volumes may include: To delete specific volumes: -```bash +```shell docker volume rm opencloud_compose_opencloud-data opencloud_compose_opencloud-config ``` Or to clean up all unused volumes (be careful!): -```bash +```shell docker volume prune ``` @@ -55,7 +56,7 @@ docker volume prune If your .env referenced local folders such as /mnt/opencloud/data, you should delete those manually: -```bash +```shell sudo rm -rf /mnt/opencloud/data sudo rm -rf /mnt/opencloud/config ``` @@ -66,7 +67,7 @@ Adjust the paths to match your setup. If you want to delete the entire project directory: -```bash +```shell cd .. rm -rf opencloud-compose ``` diff --git a/docs/admin/maintenance/upgrade/release-notes.md b/docs/admin/maintenance/upgrade/release-notes.md index c9b21bfd..649a6794 100644 --- a/docs/admin/maintenance/upgrade/release-notes.md +++ b/docs/admin/maintenance/upgrade/release-notes.md @@ -18,13 +18,15 @@ draft: false This release introduces a **breaking change in the GraphAPI**. If you are using OpenCloud only through official clients (Web, Desktop, or Mobile), **no migration is needed**. -If you're using any other software that utilizes the GraphAPI, that software might need to be adjusted to follow the new behavior of the GraphAPI. +If you're using any other software that utilizes the GraphAPI, that software might need to be adjusted to follow the new +behavior of the GraphAPI. --- ## Key Changes -The following endpoints of the GraphAPI were changed in a way that is not backwards compatible with the previous releases: +The following endpoints of the GraphAPI were changed in a way that is not backwards compatible with the previous +releases: ```http GET /v1.0/me/drives/ @@ -33,4 +35,5 @@ GET /v1beta1/drives/ GET /v1beta1/me/drives/ ``` -Due to performance optimizations, these endpoints no longer automatically expand all permissions on the drives root items. If needed, the permissions can be explicitly requested via the appropriate $expand query option. +Due to performance optimizations, these endpoints no longer automatically expand all permissions on the drives root +items. If needed, the permissions can be explicitly requested via the appropriate $expand query option. diff --git a/docs/admin/maintenance/upgrade/upgrade.md b/docs/admin/maintenance/upgrade/upgrade.mdx similarity index 54% rename from docs/admin/maintenance/upgrade/upgrade.md rename to docs/admin/maintenance/upgrade/upgrade.mdx index 19fe0ec9..eabf64b7 100644 --- a/docs/admin/maintenance/upgrade/upgrade.md +++ b/docs/admin/maintenance/upgrade/upgrade.mdx @@ -5,25 +5,25 @@ title: 'Upgrade' description: '🔄 Keep your setup up to date with the latest features!' --- -import Tabs from '@theme/Tabs' -import TabItem from '@theme/TabItem' +import Tabs from '@theme/Tabs'; +import TabItem from '@theme/TabItem'; -This guide provides steps to upgrade OpenCloud for both [docker](docs/admin/getting-started/container/docker.md) and [docker compose](docs/admin/getting-started/container/docker-compose/docker-compose.md) +This guide provides steps to upgrade OpenCloud for both [docker](docs/admin/getting-started/container/docker.md) and +[docker compose](docs/admin/getting-started/container/docker-compose/docker-compose.md) ### 1. Stop OpenCloud Stop the currently running OpenCloud instance: + {/* prettier-ignore */} - ```Shell - docker stop opencloud - ``` - + ```shell + docker stop opencloud + ``` + - ```Shell - docker compose stop - ``` + ```shell docker compose stop ``` @@ -37,7 +37,7 @@ It is recommended to create a [backup](../backup.md) before proceeding with the ### 3. Pull the new Opencloud version -```bash +```shell docker pull opencloudeu/opencloud:{tag} ``` @@ -49,42 +49,42 @@ If upgrading from an older release, check for required configuration changes: Go inside the container: -```bash +```shell docker run --rm -it --entrypoint /bin/sh -v $HOME/opencloud/opencloud-config:/etc/opencloud opencloudeu/opencloud:{tag} ``` -```bash +```shell opencloud init --diff ``` -If you see `no changes, your config is up to date`, no further action is needed. Otherwise, update your `opencloud.yaml` file accordingly and start OpenCloud. +If you see `no changes, your config is up to date`, no further action is needed. Otherwise, update your `opencloud.yaml` +file accordingly and start OpenCloud. -init -diff +init -diff --- ### 5. Start OpenCloud with updated image + {/* prettier-ignore */} - ```Shell - docker run \ - --name opencloud \ - --rm \ - -it \ - -p 9200:9200 \ - -v $HOME/opencloud/opencloud-config:/etc/opencloud \ - -v $HOME/opencloud/opencloud-data:/var/lib/opencloud \ - -e OC_INSECURE=true \ - -e PROXY_HTTP_ADDR=0.0.0.0:9200 \ - -e OC_URL=https://localhost:9200 \ - opencloudeu/opencloud:{tag} - ``` - + ```shell + docker run \ + --name opencloud \ + --rm \ + -it \ + -p 9200:9200 \ + -v $HOME/opencloud/opencloud-config:/etc/opencloud \ + -v $HOME/opencloud/opencloud-data:/var/lib/opencloud \ + -e OC_INSECURE=true \ + -e PROXY_HTTP_ADDR=0.0.0.0:9200 \ + -e OC_URL=https://localhost:9200 \ + opencloudeu/opencloud:{tag} + ``` + - ```Shell - OC_DOCKER_IMAGE=opencloudeu/opencloud OC_DOCKER_TAG=tag docker compose up -d - ``` + ```shell OC_DOCKER_IMAGE=opencloudeu/opencloud OC_DOCKER_TAG=tag docker compose up -d ``` diff --git a/docs/admin/resources/common-issues.md b/docs/admin/resources/common-issues.md index b1b9fcfa..a0f57674 100644 --- a/docs/admin/resources/common-issues.md +++ b/docs/admin/resources/common-issues.md @@ -8,7 +8,7 @@ title: Common Issues & Help ### Check whether the containers are running -```bash +```shell docker ps ``` @@ -36,43 +36,48 @@ Confirm the risk with **Accept the risk and Continue** ### Docker Permission Issues -If your Docker Compose setup fails to start and the logs contain messages such as `permission denied`, it's likely due to incorrect ownership of local directories used by the containers. +If your Docker Compose setup fails to start and the logs contain messages such as `permission denied`, it's likely due +to incorrect ownership of local directories used by the containers. **Example log output:** -```bash +```shell opencloud-1 | {"level":"fatal","service":"nats","time":"2025-04-08T09:59:59Z","line":"github.com/opencloud-eu/opencloud/services/nats/pkg/logging/nats.go:33","message":"Can't start JetStream: could not create storage directory - mkdir /var/lib/opencloud/nats: permission denied"} ``` -This error typically occurs when the mounted directories are owned by the wrong user, such as `root`, instead of the standard Docker user (`UID 1000`). +This error typically occurs when the mounted directories are owned by the wrong user, such as `root`, instead of the +standard Docker user (`UID 1000`). **Incorrect directory ownership:** -```bash +```shell drwxr-xr-x 3 root root 4096 Apr 8 09:59 opencloud-data ``` **Correct ownership should be:** -```bash +```shell drwxr-xr-x 9 1000 1000 4096 Apr 7 07:57 opencloud-data ``` To resolve this issue, adjust the ownership of the directory using the `chown` command: -```bash +```shell chown -R 1000:1000 opencloud-data ``` :::caution Security Warning -The user with UID 1000 on your host system will have full access to these mounted directories. This means that any local user account with this ID can read, modify, or delete OpenCloud config and data files. +The user with UID 1000 on your host system will have full access to these mounted directories. This means that any local +user account with this ID can read, modify, or delete OpenCloud config and data files. -This can pose a security risk in shared or multi-user environments. Make sure to implement proper user and permission management and consider isolating access to these directories. +This can pose a security risk in shared or multi-user environments. Make sure to implement proper user and permission +management and consider isolating access to these directories. ::: -Ensure you apply this to all relevant folders that are mounted into your containers. This will grant the Docker container the necessary permissions to access and write to these directories. +Ensure you apply this to all relevant folders that are mounted into your containers. This will grant the Docker +container the necessary permissions to access and write to these directories. --- @@ -105,7 +110,7 @@ If the admin password is forgotten or needs to be changed via the terminal: First, stop your OpenCloud container: -```bash +```shell docker compose stop opencloud ``` @@ -113,7 +118,7 @@ docker compose stop opencloud Use the following command to reset the password: -```bash +```shell sudo docker run -it --rm -v :/var/lib/opencloud -v :/etc/opencloud opencloudeu/opencloud: idm resetpassword ``` @@ -125,10 +130,9 @@ Replace: `` – Use latest or your specific version -🔍 How to find the volume names -You can list your current Docker volumes with: +🔍 How to find the volume names You can list your current Docker volumes with: -```bash +```shell docker volume ls ``` @@ -140,12 +144,12 @@ Look for volumes like: 💡 Example for standard setup: -```bash +```shell sudo docker run -it --rm -v opencloud_full_opencloud-data:/var/lib/opencloud -v opencloud_full_opencloud-config:/etc/opencloud opencloudeu/opencloud:latest idm resetpassword ``` #### Step 3: Start the container again -```bash +```shell docker compose up -d ``` diff --git a/docs/admin/resources/demo-user.md b/docs/admin/resources/demo-user.md index 87d18a40..d34286c1 100644 --- a/docs/admin/resources/demo-user.md +++ b/docs/admin/resources/demo-user.md @@ -6,9 +6,12 @@ title: Demo User # **Demo User Overview** -This page introduces the pre-configured demo users available in OpenCloud. These users are designed to help you explore the platform’s features, test different roles, and experience OpenCloud from various perspectives without setting up new accounts. +This page introduces the pre-configured demo users available in OpenCloud. These users are designed to help you explore +the platform’s features, test different roles, and experience OpenCloud from various perspectives without setting up new +accounts. -Each demo user has specific permissions and access levels, allowing you to simulate real-world scenarios such as **admin management, file sharing, and collaboration**. +Each demo user has specific permissions and access levels, allowing you to simulate real-world scenarios such as **admin +management, file sharing, and collaboration**. Below, you’ll find details about each user, including their roles and login credentials. diff --git a/docs/admin/resources/faq.md b/docs/admin/resources/faq.md index 1317e711..49d5b20a 100644 --- a/docs/admin/resources/faq.md +++ b/docs/admin/resources/faq.md @@ -18,18 +18,25 @@ draft: true 1. Simplified Administration -OpenCloud is designed to be straightforward to set up and manage, allowing administrators to handle the system with minimal effort and without unnecessary complexity. +OpenCloud is designed to be straightforward to set up and manage, allowing administrators to handle the system with +minimal effort and without unnecessary complexity. 2. Independent File-sharing -OpenCloud is designed to give you a privacy-focused alternative to mainstream platforms like Microsoft OneDrive or Google Drive, freeing you from reliance on big tech services and their data-collection practices. +OpenCloud is designed to give you a privacy-focused alternative to mainstream platforms like Microsoft OneDrive or +Google Drive, freeing you from reliance on big tech services and their data-collection practices.
How does OpenCloud differ from other open source file sharing applications? -OpenCloud is simpler and more reliable than existing PHP-based solutions. OpenCloud stands out by offering a radically simplified architecture compared to other open-source file-sharing solutions. While many alternatives require maintaining complex stacks involving multiple components like PHP, MySQL, Redis, and Apache — creating a web of dependencies and potential security risks—OpenCloud avoids this entirely. It writes data directly to disk instead of relying on a dedicated database, making it much easier to maintain and far more reliable. With OpenCloud, you can focus on your files without worrying about intricate setups or data loss risks. +OpenCloud is simpler and more reliable than existing PHP-based solutions. OpenCloud stands out by offering a radically +simplified architecture compared to other open-source file-sharing solutions. While many alternatives require +maintaining complex stacks involving multiple components like PHP, MySQL, Redis, and Apache — creating a web of +dependencies and potential security risks—OpenCloud avoids this entirely. It writes data directly to disk instead of +relying on a dedicated database, making it much easier to maintain and far more reliable. With OpenCloud, you can focus +on your files without worrying about intricate setups or data loss risks.
@@ -59,8 +66,11 @@ Absolutely!
If OpenCloud is free, how are the employees paid? -We're glad you asked. -We provide a paid support subscription, see [https://opencloud.eu/en/product/service-and-support](https://opencloud.eu/en/product/service-and-support). With a support subscription you’ll be the first to know about security vulnerabilities and receive detailed instructions on how to address them or how to integrate OpenCloud into your existing systems and storage. We also provide Long-Term-Support if you don't want to upgrade your system so frequently. +We're glad you asked. We provide a paid support subscription, see +[https://opencloud.eu/en/product/service-and-support](https://opencloud.eu/en/product/service-and-support). With a +support subscription you’ll be the first to know about security vulnerabilities and receive detailed instructions on how +to address them or how to integrate OpenCloud into your existing systems and storage. We also provide Long-Term-Support +if you don't want to upgrade your system so frequently.
@@ -85,7 +95,8 @@ Yes, of course!
What types of files can I store and share with OpenCloud? -No restrictions. You can store and share any filetype. If necessary, you can restrict the upload of certain filetypes like .exe or documents with macros like xlsm. +No restrictions. You can store and share any filetype. If necessary, you can restrict the upload of certain filetypes +like .exe or documents with macros like xlsm.
@@ -106,14 +117,16 @@ Yes. We use the WOPI standard for realtime collabration in the web office applic
Can I create and manage user accounts and permissions? -Yes, you can either use the built-in user management system or integrate OpenCloud with your existing identity management. +Yes, you can either use the built-in user management system or integrate OpenCloud with your existing identity +management.
Are there mobile apps, and do they offer the same features as the desktop version? -We provide apps for Windows, MacOS, Linux, iOS and Android. Please refer to the roadmap to see when the apps will be available: [https://opencloud.eu/roadmap](https://opencloud.eu/roadmap) +We provide apps for Windows, MacOS, Linux, iOS and Android. Please refer to the roadmap to see when the apps will be +available: [https://opencloud.eu/roadmap](https://opencloud.eu/roadmap)
@@ -129,30 +142,41 @@ Yes. In case you made a mistake, you can always jump back to older versions of a
Can I self-host OpenCloud on my own server? -Yes and we encourage you to do so! (We do not provide a SaaS service that stores your files on our servers, like Google Drive or Microsoft OneDrive do.) +Yes and we encourage you to do so! (We do not provide a SaaS service that stores your files on our servers, like Google +Drive or Microsoft OneDrive do.)
What are the system requirements for hosting OpenCloud? -The system requirements for hosting OpenCloud depend heavily on the number of concurrent users and the workload they generate, such as the frequency of their requests. OpenCloud is versatile—it can run on anything from a Raspberry Pi to a large data center setup. +The system requirements for hosting OpenCloud depend heavily on the number of concurrent users and the workload they +generate, such as the frequency of their requests. OpenCloud is versatile—it can run on anything from a Raspberry Pi to +a large data center setup. -For example, a Raspberry Pi 4 can support hundreds of registered users, but the key factor is the number of users actively using the system at the same time. Concurrent users, especially those using desktop or mobile clients (which frequently check for updates), require more resources. Additional features like the web office integration Collabora or antivirus scanning also impact performance. +For example, a Raspberry Pi 4 can support hundreds of registered users, but the key factor is the number of users +actively using the system at the same time. Concurrent users, especially those using desktop or mobile clients (which +frequently check for updates), require more resources. Additional features like the web office integration Collabora or +antivirus scanning also impact performance. -For a minimal setup, OpenCloud can comfortably support 20 concurrent users browsing files via the web interface. As your user base or workload increases, scaling the hardware accordingly will ensure smooth performance. A factor to scale performance is just to add storage, as OpenCloud needs storage IOPS for performance. +For a minimal setup, OpenCloud can comfortably support 20 concurrent users browsing files via the web interface. As your +user base or workload increases, scaling the hardware accordingly will ensure smooth performance. A factor to scale +performance is just to add storage, as OpenCloud needs storage IOPS for performance. Key Factors for Optimal Performance: - Storage IOPS: The performance of OpenCloud highly relies on the amount of IOPS of your storage - the more, the better. -- Network throughput: Another factor for enhancing the performance of OpenCloud is network throughput in distributed storage. +- Network throughput: Another factor for enhancing the performance of OpenCloud is network throughput in distributed + storage.
How difficult is it to set up, and is technical expertise required? -One of our goals is to make the deployment of OpenCloud as simple as possible. Depending on your expereince, it's possible to set up a basic OpenCloud instance in less than 1 minute. See [https://docs.opencloud.eu/docs/category/getting-started-1](https://docs.opencloud.eu/docs/category/getting-started-1) +One of our goals is to make the deployment of OpenCloud as simple as possible. Depending on your expereince, it's +possible to set up a basic OpenCloud instance in less than 1 minute. See +[https://docs.opencloud.eu/docs/category/getting-started-1](https://docs.opencloud.eu/docs/category/getting-started-1)
@@ -173,8 +197,10 @@ Yes. Yes, OpenCloud allows you customizations: -- **Wordings**: You can replace specific terms, such as changing the word “Spaces” to “Datarooms” to better fit your terminology. -- **Extensions**: The web UI also supports custom web extensions. Check out our developer documentation [here] to learn how to get started with creating and adding your own extensions and find existing extensions [here]. +- **Wordings**: You can replace specific terms, such as changing the word “Spaces” to “Datarooms” to better fit your + terminology. +- **Extensions**: The web UI also supports custom web extensions. Check out our developer documentation [here] to learn + how to get started with creating and adding your own extensions and find existing extensions [here]. @@ -185,28 +211,36 @@ Yes, OpenCloud allows you customizations: OpenCloud offers three main ways to share files, making it easy to collaborate and manage access: -1. **Personal Share**: Share files with registered users within your organization. You can assign permissions such as view, edit, or download, providing flexible control over file access. -2. **Share via Link**: Share files with anyone, even outside your organization, by generating a link. No account is required for accessing the file. -3. **Spaces**: Spaces are user-independent datarooms that belong to the organization rather than an individual. This ensures files remain within the organization, even if users leave. Examples of Spaces include school classes, collaborative projects, or organizational units like Marketing, Sales, or Finance. Spaces are easier for admins to manage, as they can be self-managed by designated users. +1. **Personal Share**: Share files with registered users within your organization. You can assign permissions such as + view, edit, or download, providing flexible control over file access. +2. **Share via Link**: Share files with anyone, even outside your organization, by generating a link. No account is + required for accessing the file. +3. **Spaces**: Spaces are user-independent datarooms that belong to the organization rather than an individual. This + ensures files remain within the organization, even if users leave. Examples of Spaces include school classes, + collaborative projects, or organizational units like Marketing, Sales, or Finance. Spaces are easier for admins to + manage, as they can be self-managed by designated users. -**Special Feature: Secret File Drop** -The Secret File Drop allows anonymous users to securely upload files (e.g., homework, photos or even whistleblower material) without needing an account. +**Special Feature: Secret File Drop** The Secret File Drop allows anonymous users to securely upload files (e.g., +homework, photos or even whistleblower material) without needing an account.
Can I share files with external users? -Yes. You can share files with anyone, even outside your organization, by generating a link. No account is required for accessing the file. Link sharing can be disabled if needed. +Yes. You can share files with anyone, even outside your organization, by generating a link. No account is required for +accessing the file. Link sharing can be disabled if needed.
Does it support federated sharing between different instances? -Yes, federated sharing is possible via Open Cloud Mesh (OCM). This feature allows you to securely share files and collaborate across different instances, even if they are hosted by different organizations. +Yes, federated sharing is possible via Open Cloud Mesh (OCM). This feature allows you to securely share files and +collaborate across different instances, even if they are hosted by different organizations. -For example, a company with multiple branches in different regions could use OCM to share files between instances, enabling collaboration across teams while maintaining control over local data. +For example, a company with multiple branches in different regions could use OCM to share files between instances, +enabling collaboration across teams while maintaining control over local data.
@@ -222,7 +256,10 @@ No.
Where is my data stored, and can I choose the storage location? -OpenCloud is a fully self-hosted (on-premise) solution, meaning you have complete control over where your data is stored. You can choose the server and country where OpenCloud will be installed. Unlike SaaS services like Google Drive or Microsoft OneDrive, which store your files on their servers, OpenCloud gives you full control over your data, ensuring privacy and security on your terms. +OpenCloud is a fully self-hosted (on-premise) solution, meaning you have complete control over where your data is +stored. You can choose the server and country where OpenCloud will be installed. Unlike SaaS services like Google Drive +or Microsoft OneDrive, which store your files on their servers, OpenCloud gives you full control over your data, +ensuring privacy and security on your terms.
@@ -244,7 +281,8 @@ Yes, the following storage can be used: **Download updates** on download.opencloud.eu or via docker hub. -OpenCloud is released in three different release types: **Production, Rolling and Daily**. Each of them is targeted to a specific use case and audience group. +OpenCloud is released in three different release types: **Production, Rolling and Daily**. Each of them is targeted to a +specific use case and audience group. @@ -269,9 +307,13 @@ Yes, of course!
Is the OpenCloud Web UI accessible according to EN 301 549 / WCAG / BITV 2.0? -Yes, the OpenCloud Web UI is accessible according to EN 301 549, WCAG, and BITV 2.0. We believe that accessibility is important for everyone, not just for individuals with disabilities, as it benefits all users at some point in their lives. +Yes, the OpenCloud Web UI is accessible according to EN 301 549, WCAG, and BITV 2.0. We believe that accessibility is +important for everyone, not just for individuals with disabilities, as it benefits all users at some point in their +lives. -As we release new features every 3 weeks, we ensure that accessibility is integrated into the feature development lifecycle. While we strive to maintain high accessibility standards, we’re only human and occasional mistakes may happen. If a new feature unintentionally impacts accessibility, we treat it as a bug and address it in the next release. +As we release new features every 3 weeks, we ensure that accessibility is integrated into the feature development +lifecycle. While we strive to maintain high accessibility standards, we’re only human and occasional mistakes may +happen. If a new feature unintentionally impacts accessibility, we treat it as a bug and address it in the next release. If you encounter any accessibility violations, please let us know so we can promptly resolve the issue. @@ -280,14 +322,22 @@ If you encounter any accessibility violations, please let us know so we can prom
Can access controls and permissions be configured to meet regulatory requirements? -Yes, OpenCloud offers robust access control and permission settings that can be fully configured to meet various regulatory requirements. You can define user roles, assign specific permissions, and set up granular access controls to ensure compliance with industry standards and regulations such as GDPR, HIPAA, and others. With OpenCloud, you have the flexibility to control who accesses your data, what actions they can perform, and how data is shared, ensuring that your system remains secure and compliant with the required regulations. +Yes, OpenCloud offers robust access control and permission settings that can be fully configured to meet various +regulatory requirements. You can define user roles, assign specific permissions, and set up granular access controls to +ensure compliance with industry standards and regulations such as GDPR, HIPAA, and others. With OpenCloud, you have the +flexibility to control who accesses your data, what actions they can perform, and how data is shared, ensuring that your +system remains secure and compliant with the required regulations.
How does it handle requests for data access or deletion under GDPR? -OpenCloud provides users with the ability to trigger a GDPR Export in a self-service manner. This export generates a detailed report of all personal data stored in the context of OpenCloud, excluding the user’s own files. The report includes relevant data related to the user’s account and activity within the system, ensuring transparency and compliance with GDPR requirements. For the deletion of personal files, users have full control to manage and remove their own data as needed. +OpenCloud provides users with the ability to trigger a GDPR Export in a self-service manner. This export generates a +detailed report of all personal data stored in the context of OpenCloud, excluding the user’s own files. The report +includes relevant data related to the user’s account and activity within the system, ensuring transparency and +compliance with GDPR requirements. For the deletion of personal files, users have full control to manage and remove +their own data as needed.
@@ -296,7 +346,10 @@ OpenCloud provides users with the ability to trigger a GDPR Export in a self-ser
Does OpenCloud offer multi-language support? -Yes, OpenCloud fully maintains both **English** and **German** languages. Additionally, the web UI offers support for other languages, which are listed below. Please note that these languages are not 100% translated and are maintained by the community on a best-effort basis. We appreciate the contributions from our community to help improve the language support over time. +Yes, OpenCloud fully maintains both **English** and **German** languages. Additionally, the web UI offers support for +other languages, which are listed below. Please note that these languages are not 100% translated and are maintained by +the community on a best-effort basis. We appreciate the contributions from our community to help improve the language +support over time. Community maintained languages: diff --git a/docs/admin/resources/lifecycle.md b/docs/admin/resources/lifecycle.mdx similarity index 79% rename from docs/admin/resources/lifecycle.md rename to docs/admin/resources/lifecycle.mdx index 08999922..066fd440 100644 --- a/docs/admin/resources/lifecycle.md +++ b/docs/admin/resources/lifecycle.mdx @@ -10,13 +10,18 @@ import TabItem from '@theme/TabItem'; ## Release Types -OpenCloud offers three release types to suit different needs: **Rolling**, **Production**, and **LTS**. For most users, Rolling is ideal, providing the **latest features** every few weeks. Production focuses on **stability**. LTS (Long-Term Support Release) is designed specifically for businesses that need longevity and extended **backports**. +OpenCloud offers three release types to suit different needs: **Rolling**, **Production**, and **LTS**. For most users, +Rolling is ideal, providing the **latest features** every few weeks. Production focuses on **stability**. LTS (Long-Term +Support Release) is designed specifically for businesses that need longevity and extended **backports**. -Release types +Release types ### Advantage of the LTS Releases -With LTS, businesses can continue using an older production release without needing to upgrade to the latest version, while still **receiving critical security patches** and **critical stability fixes**. This makes LTS the perfect choice for organizations seeking a **stable long-term** solution. LTS is available exclusively to customers with a service and support entitlement through a business license. +With LTS, businesses can continue using an older production release without needing to upgrade to the latest version, +while still **receiving critical security patches** and **critical stability fixes**. This makes LTS the perfect choice +for organizations seeking a **stable long-term** solution. LTS is available exclusively to customers with a service and +support entitlement through a business license. | Rolling | Production | LTS | | :-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | :---------------------------------------------------------------------------------------------------------------------------------------------------------------------- | :----------------------------------------------------------------------------------------------------------------------------------------------------------------------- | @@ -62,6 +67,8 @@ With LTS, businesses can continue using an older production release without need # Versioning Scheme: Semantic Versioning -OpenCloud follows [Semantic Versioning](https://semver.org/), also known as SemVer. Version numbers are structured as MAJOR.MINOR.PATCH. Breaking changes increase the MAJOR version, new backward-compatible features increase the MINOR version, and backward-compatible bug fixes increment the PATCH version. +OpenCloud follows [Semantic Versioning](https://semver.org/), also known as SemVer. Version numbers are structured as +MAJOR.MINOR.PATCH. Breaking changes increase the MAJOR version, new backward-compatible features increase the MINOR +version, and backward-compatible bug fixes increment the PATCH version. -Semantic Versioning +Semantic Versioning diff --git a/docs/admin/resources/whats-new.md b/docs/admin/resources/whats-new.md index 91a992e3..074c0ffc 100644 --- a/docs/admin/resources/whats-new.md +++ b/docs/admin/resources/whats-new.md @@ -8,13 +8,23 @@ title: "What's New" Release notes OpenCloud 2.0.0 (Production release) -- 🌲 File Native Backups with PosixFS: OpenCloud introduces PosixFS to allow for easy file native backups. As all files and metadata information is stored directly on the storage (no database needed), you can create standard file-level snapshots or copies.
- Previously, files and folders were stored in a hash-based structure, making the layout unreadable for humans. With PosixFS, the full file tree is directly visible on the storage, providing transparency and confidence that all data is being backed up correctly. Admins benefit from easier maintenance, fewer moving parts, and improved fault tolerance in backup and disaster recovery scenarios.
- Note: Before adding, writing, or restoring files directly into the OpenCloud storage, make sure to stop OpenCloud. Once the changes are made, start it again. This ensures that all changes are properly recognized. A future feature, currently in development, called “collaborative storage” will allow external file changes (e.g., via CLI) to be detected in real time by OpenCloud and its clients. +- 🌲 File Native Backups with PosixFS: OpenCloud introduces PosixFS to allow for easy file native backups. As all files + and metadata information is stored directly on the storage (no database needed), you can create standard file-level + snapshots or copies.
Previously, files and folders were stored in a hash-based structure, making the layout + unreadable for humans. With PosixFS, the full file tree is directly visible on the storage, providing transparency and + confidence that all data is being backed up correctly. Admins benefit from easier maintenance, fewer moving parts, and + improved fault tolerance in backup and disaster recovery scenarios.
Note: Before adding, writing, or restoring + files directly into the OpenCloud storage, make sure to stop OpenCloud. Once the changes are made, start it again. + This ensures that all changes are properly recognized. A future feature, currently in development, called + “collaborative storage” will allow external file changes (e.g., via CLI) to be detected in real time by OpenCloud and + its clients. :::warning[Breaking Change] -No migration path – There is no programmatic migration from earlier versions (using decomposedFS) to version 2.0.0. If you need assistance, please reach out in our [Matrix channel](https://matrix.to/#/#opencloud:matrix.org) or open an issue on [GitHub](https://github.com/opencloud-eu/opencloud/issues). This helps us gauge how impactful this change is and respond accordingly. +No migration path – There is no programmatic migration from earlier versions (using decomposedFS) to version 2.0.0. If +you need assistance, please reach out in our [Matrix channel](https://matrix.to/#/#opencloud:matrix.org) or open an +issue on [GitHub](https://github.com/opencloud-eu/opencloud/issues). This helps us gauge how impactful this change is +and respond accordingly. ::: @@ -22,13 +32,18 @@ No migration path – There is no programmatic migration from earlier versions ( Release notes OpenCloud 1.1.0 -- 🎨 Material Design Color Roles: The custom color framework has been replaced with Material Design color roles. This change standardizes theming by using a small set of base colors to generate a consistent, accessible color palette across the UI. It lays the groundwork for improved visual coherence and better support for dark mode, accessibility, and future theming options. +- 🎨 Material Design Color Roles: The custom color framework has been replaced with Material Design color roles. This + change standardizes theming by using a small set of base colors to generate a consistent, accessible color palette + across the UI. It lays the groundwork for improved visual coherence and better support for dark mode, accessibility, + and future theming options. # 2025 February 25 Release notes OpenCloud 1.0.0 -Say hello to OpenCloud 1.0.0! A fresh take on secure file sharing & collaboration! Built as a fork of ocis, OpenCloud is all about doing things right. No unnecessary fluff, no distractions—just rock-solid data management, great user experience, secure and convenient administration and an awesome service by our support team. +Say hello to OpenCloud 1.0.0! A fresh take on secure file sharing & collaboration! Built as a fork of ocis, OpenCloud is +all about doing things right. No unnecessary fluff, no distractions—just rock-solid data management, great user +experience, secure and convenient administration and an awesome service by our support team. We believe in keeping things simple but powerful. @@ -76,7 +91,8 @@ We believe in keeping things simple but powerful. ## 📂 Spaces - Collaborative Team Folders -- Project-Based Team Folders: Designed for teams to store, access, and manage files collectively. Files in Spaces belong to multiple users, ensuring continuity even if team members leave. +- Project-Based Team Folders: Designed for teams to store, access, and manage files collectively. Files in Spaces belong + to multiple users, ensuring continuity even if team members leave. - Self-Service Admin Transfer: Easily reassign space owners and assign multiple owners for shared responsibility. - Easy Permission Control: Manage user access based on the roles Viewers, Editors, Managers. diff --git a/docs/admin/welcome/features.md b/docs/admin/welcome/features.md index b0fee220..9945e09a 100644 --- a/docs/admin/welcome/features.md +++ b/docs/admin/welcome/features.md @@ -48,7 +48,8 @@ title: Features ## **📂 Spaces - Collaborative Team Folders** -- **Project-Based Team Folders**: Designed for teams to store, access, and manage files collectively. Files in Spaces belong to **multiple** users, ensuring continuity even if team members leave. +- **Project-Based Team Folders**: Designed for teams to store, access, and manage files collectively. Files in Spaces + belong to **multiple** users, ensuring continuity even if team members leave. - **Self-Service Admin Transfer**: Easily reassign space owners and assign multiple owners for shared responsibility. - **Easy Permission Control**: Manage user access based on the roles Viewers, Editors, Managers. diff --git a/docs/admin/welcome/index.md b/docs/admin/welcome/index.md index f9758378..efcac428 100644 --- a/docs/admin/welcome/index.md +++ b/docs/admin/welcome/index.md @@ -5,11 +5,12 @@ slug: /admin/intro # 🙋🏻‍♀️ Welcome to OpenCloud Admin Docs -Welcome to **OpenCloud**, your self-hosted file sharing platform: Secure, simple and reliable. This documentation helps you to **get started, configure, and maintain** OpenCloud. +Welcome to **OpenCloud**, your self-hosted file sharing platform: Secure, simple and reliable. This documentation helps +you to **get started, configure, and maintain** OpenCloud. ## Quick start -```bash +```shell curl -L https://opencloud.eu/install | /bin/bash ``` @@ -21,4 +22,5 @@ curl -L https://opencloud.eu/install | /bin/bash ## Need Help? -Check our [GitHub Discussion](https://github.com/orgs/opencloud-eu/discussions), or [Matrix Channel](https://matrix.to/#/#opencloud:matrix.org)\*\*. Let’s get started! 🚀 +Check our [GitHub Discussion](https://github.com/orgs/opencloud-eu/discussions), or +[Matrix Channel](https://matrix.to/#/#opencloud:matrix.org)\*\*. Let’s get started! 🚀 diff --git a/docs/dev/server/index.md b/docs/dev/server/index.md index 51bfd4d4..efebd2ee 100644 --- a/docs/dev/server/index.md +++ b/docs/dev/server/index.md @@ -5,4 +5,5 @@ sidebar_position: 1 Our current Architecture Diagrams can be found here. -You’ll find the Libre Graph API documentation by clicking this link. +You’ll find the Libre Graph API documentation by clicking +this link. diff --git a/docs/dev/web/development/conventions.md b/docs/dev/web/development/conventions.md index 05d9731f..96d1dd81 100644 --- a/docs/dev/web/development/conventions.md +++ b/docs/dev/web/development/conventions.md @@ -4,20 +4,22 @@ sidebar_position: 3 id: conventions --- -This is a collection of tips and conventions to follow when working on the [OpenCloud Web frontend](https://github.com/opencloud-eu/web). -Since it is a living document, please open a PR if you find something missing. +This is a collection of tips and conventions to follow when working on the +[OpenCloud Web frontend](https://github.com/opencloud-eu/web). Since it is a living document, please open a PR if you +find something missing. ## Contributing to OpenCloud Web -Everyone is invited to contribute. Simply fork the [codebase](https://github.com/opencloud-eu/web/), -check the [issues](https://github.com/opencloud-eu/web/issues?q=is%3Aopen%20is%3Aissue%20label%3AType%3AGood-First-Issue) -for a suitable one and open a pull request! +Everyone is invited to contribute. Simply fork the [codebase](https://github.com/opencloud-eu/web/), check the +[issues](https://github.com/opencloud-eu/web/issues?q=is%3Aopen%20is%3Aissue%20label%3AType%3AGood-First-Issue) for a +suitable one and open a pull request! ### Formal checks -To make sure your pull request can be efficiently reviewed and won't need a lot of changes down the road, please run all formal checks (linter, formatter, type checks and unit tests) via `pnpm check:all` locally. Our [CI](https://ci.opencloud.eu/repos/6) 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](./../testing/running-tests.md). +To make sure your pull request can be efficiently reviewed and won't need a lot of changes down the road, please run all +formal checks (linter, formatter, type checks and unit tests) via `pnpm check:all` locally. Our +[CI](https://ci.opencloud.eu/repos/6) 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](./../testing/running-tests.md). ## Code Conventions @@ -27,31 +29,40 @@ We're trying to stick with early returns in our code to make it more performant ### Translations -Use `$gettext` (or a variation of it) inside HTML tags (instead of a `` or similar) in order to translate strings. +Use `$gettext` (or a variation of it) inside HTML tags (instead of a `` or similar) in order to +translate strings. ### TypeScript -We're using TypeScript which allows us to catch bugs at transpile time. Clean types make sure our IDEs can support us in reasoning about our ever-growing, complex codebase. +We're using TypeScript which allows us to catch bugs at transpile time. Clean types make sure our IDEs can support us in +reasoning about our ever-growing, complex codebase. ### Composition API and script setup -We prefer using Vue's Composition API in combination with [script setup](https://vuejs.org/api/sfc-script-setup) over the traditional options API. This integrates nicely with TypeScript and allows us to use composables and reactive APIs more effectively. +We prefer using Vue's Composition API in combination with [script setup](https://vuejs.org/api/sfc-script-setup) over +the traditional options API. This integrates nicely with TypeScript and allows us to use composables and reactive APIs +more effectively. -That being said, due to the fact that we are still in the process of migrating our codebase, you might find some files using the options API or even composition API without script setup. We are working on this and will eventually migrate all files. +That being said, due to the fact that we are still in the process of migrating our codebase, you might find some files +using the options API or even composition API without script setup. We are working on this and will eventually migrate +all files. ### Composables -We make heavy use of composables to encapsulate reusable logic. This allows us to share code between components and keep our components clean and focused on their specific tasks. +We make heavy use of composables to encapsulate reusable logic. This allows us to share code between components and keep +our components clean and focused on their specific tasks. ### Split large components -If a component is getting too big, consider splitting it into smaller components. This will make it easier to read and maintain. A good rule of thumb is to keep components under 300 lines of code. +If a component is getting too big, consider splitting it into smaller components. This will make it easier to read and +maintain. A good rule of thumb is to keep components under 300 lines of code. ### Services -We try to avoid services when possible and rather use composables instead. If writing a service is necessary, it should be instantiated once via the `web-runtime` package and then made available via a `useYourService` composable. +We try to avoid services when possible and rather use composables instead. If writing a service is necessary, it should +be instantiated once via the `web-runtime` package and then made available via a `useYourService` composable. ### Dependencies -To keep the bundle size small and reduce the risk of introducing security problems for our users, we try to limit -the amount of dependencies in our code base and keep them as up-to-date as possible. +To keep the bundle size small and reduce the risk of introducing security problems for our users, we try to limit the +amount of dependencies in our code base and keep them as up-to-date as possible. diff --git a/docs/dev/web/development/repo-structure.md b/docs/dev/web/development/repo-structure.md index c65d56ca..919ec68b 100644 --- a/docs/dev/web/development/repo-structure.md +++ b/docs/dev/web/development/repo-structure.md @@ -6,35 +6,39 @@ id: repo-structure ## Repository Structure -From a developer's perspective, the most important parts of the [OpenCloud Web repo](https://github.com/opencloud-eu/web) are the following files and folders: +From a developer's perspective, the most important parts of the +[OpenCloud Web repo](https://github.com/opencloud-eu/web) 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](./../development/tooling.md). +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](./../development/tooling.md). ### packages Folder -We're using the [OpenCloud Web repo](https://github.com/opencloud-eu/web) as a mono repo. It contains a variety of packages. Some of them get -published to [npmjs.com](https://npmjs.com), others define the core packages, apps and extensions that are the foundation of -the `OpenCloud Web` release artifact. +We're using the [OpenCloud Web repo](https://github.com/opencloud-eu/web) as a mono repo. It contains a variety of +packages. Some of them get published to [npmjs.com](https://npmjs.com), others define the core packages, apps and +extensions that are the foundation of the `OpenCloud 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](https://pnpm.io/workspaces). +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](https://pnpm.io/workspaces). ### tests Folder -We're using [Playwright](https://playwright.dev) for UI testing. The UI tests are located in `/tests/e2e`. You can read more about testing in our [testing docs](./../testing/running-tests.md). +We're using [Playwright](https://playwright.dev) for UI testing. The UI tests are located in `/tests/e2e`. You can read +more about testing in our [testing docs](./../testing/running-tests.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. +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](https://vitejs.dev) 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](./../development/tooling.md). +We're working with [Vite](https://vitejs.dev) 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](./../development/tooling.md). ## Packages @@ -47,9 +51,10 @@ Each package in the `/packages` folder can - not exclusively, but most commonly ### 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 OpenCloud Web ecosystem. +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 OpenCloud +Web ecosystem. Namely those packages are @@ -60,38 +65,46 @@ Namely those packages are ### OpenCloud Design System -The OpenCloud 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 OpenCloud 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](https://docs.opencloud.eu/design-system/). +The OpenCloud 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 OpenCloud 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](https://docs.opencloud.eu/design-system/). -The OpenCloud Design System is a standalone project that gets published on npmjs.com as [@opencloud-eu/design-system](https://www.npmjs.com/package/@opencloud-eu/design-system). Since it's bundled with OpenCloud Web, you should not bundle it with your app or extension. However, you can add it as a dev dependency for better IDE support. +The OpenCloud Design System is a standalone project that gets published on npmjs.com as +[@opencloud-eu/design-system](https://www.npmjs.com/package/@opencloud-eu/design-system). Since it's bundled with +OpenCloud Web, you should not bundle it with your app or extension. However, you can add it as a dev dependency for +better IDE support. ### web-client The client package (`/packages/web-client`) serves as an abstraction layer for the various OpenCloud APIs, like -[LibreGraph](https://docs.opencloud.eu/apis/http/graph/), [WebDAV](https://docs.opencloud.eu/server/next/developer_manual/webdav_api/) and -[OCS](https://docs.opencloud.eu/server/next/developer_manual/core/apis/ocs-capabilities.html). 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 +[LibreGraph](https://docs.opencloud.eu/apis/http/graph/), +[WebDAV](https://docs.opencloud.eu/server/next/developer_manual/webdav_api/) and +[OCS](https://docs.opencloud.eu/server/next/developer_manual/core/apis/ocs-capabilities.html). 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 [@opencloud-eu/web-client](https://www.npmjs.com/package/@opencloud-eu/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](https://github.com/opencloud-eu/web/blob/main/packages/web-client/README.md) gives you a few examples on how to use it. +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](https://github.com/opencloud-eu/web/blob/main/packages/web-client/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 [@opencloud-eu/web-pkg](https://www.npmjs.com/package/@opencloud-eu/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 [@opencloud-eu/web-pkg](https://www.npmjs.com/package/@opencloud-eu/web-pkg). -Dedicated documentation for the `web-pkg` package is not available, yet, since our extension system is still work in progress. +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 OpenCloud 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 write an issue in our [issue tracker](https://github.com/opencloud-eu/web/issues). +At the very heart of OpenCloud 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 write an issue in our [issue tracker](https://github.com/opencloud-eu/web/issues). ### Standalone Core Apps @@ -107,18 +120,22 @@ The repo also includes some standalone apps which are bundled with the default O ### 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 OpenCloud Web release artifact: +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 OpenCloud 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. Collabora Online, OnlyOffice and others) +- `web-app-external` an iframe integration of all the apps coming from the app provider (e.g. Collabora Online, + OnlyOffice 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 have a look at the [extension system docs](./../extension-system). +If you're interested in writing your own viewer or editor app for certain file types, please have a look at the +[extension system docs](./../extension-system). ### Testing -Basic setup and helpers for unit testing lives in `web-test-helpers`. This package gets published on npmjs.com as [@opencloud-eu/web-test-helpers](https://www.npmjs.com/package/@opencloud-eu/web-test-helpers) to ensure its functionality can be used anywhere inside the OpenCloud Web ecosystem. +Basic setup and helpers for unit testing lives in `web-test-helpers`. This package gets published on npmjs.com as +[@opencloud-eu/web-test-helpers](https://www.npmjs.com/package/@opencloud-eu/web-test-helpers) to ensure its +functionality can be used anywhere inside the OpenCloud Web ecosystem. diff --git a/docs/dev/web/development/tooling.md b/docs/dev/web/development/tooling.md index ad449285..a2093b4c 100644 --- a/docs/dev/web/development/tooling.md +++ b/docs/dev/web/development/tooling.md @@ -6,7 +6,8 @@ id: tooling ## Packaging -Web is using [pnpm](https://pnpm.io/) as package manager and [vite](https://vitejs.dev/) as build tool. The latter is built on top of [rollup](https://rollupjs.org/) and brings some additional features such as instant hot-reloading. +Web is using [pnpm](https://pnpm.io/) as package manager and [vite](https://vitejs.dev/) as build tool. The latter is +built on top of [rollup](https://rollupjs.org/) and brings some additional features such as instant hot-reloading. ## Development Setup @@ -19,12 +20,10 @@ Please make sure you have the following tools installed on your system: - node - pnpm (we recommend the installation via `corepack` which is included in newer node versions) -:::note -If you’re not using Docker Desktop, you might have to modify your `/etc/hosts` and add `127.0.0.1 host.docker.internal` to make `host.docker.internal` links work. -::: +:::note If you’re not using Docker Desktop, you might have to modify your `/etc/hosts` and add +`127.0.0.1 host.docker.internal` to make `host.docker.internal` links work. ::: -:::note -This setup currently doesn't work on Windows out of the box. +:::note This setup currently doesn't work on Windows out of the box.
Workaround @@ -40,20 +39,26 @@ After cloning the source code, install the dependencies via `pnpm install`. ### Starting the Server -You can start the OpenCloud server by running `docker-compose up opencloud -d`. If you want to run the full stack, you can run `docker-compose up -d` instead. This will also start the wopi service and an instance of Collabora. +You can start the OpenCloud server by running `docker-compose up opencloud -d`. If you want to run the full stack, you +can run `docker-compose up -d` instead. This will also start the wopi service and an instance of Collabora. ### Building and Accessing Web -After starting the docker containers, you can build Web by running `pnpm build:w`. This command compiles the project and includes support for hot-reloading, allowing you to see changes as you make them. However, note that the rebuild process may take some time. +After starting the docker containers, you can build Web by running `pnpm build:w`. This command compiles the project and +includes support for hot-reloading, allowing you to see changes as you make them. However, note that the rebuild process +may take some time. -For a faster development experience, consider enabling instant hot-reloading. Details on how to set this up are provided below. +For a faster development experience, consider enabling instant hot-reloading. Details on how to set this up are provided +below. Now you can access Web via [https://host.docker.internal:9200](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](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. +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](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. -:::note -Make sure that you ran `pnpm build` once before starting the server with `pnpm vite`. Also, you need to accept the self-signed certificate in your browser for [https://host.docker.internal:9200](https://host.docker.internal:9200) _and_ [https://host.docker.internal:9201](https://host.docker.internal:9201). -::: +:::note Make sure that you ran `pnpm build` once before starting the server with `pnpm vite`. Also, you need to accept +the self-signed certificate in your browser for [https://host.docker.internal:9200](https://host.docker.internal:9200) +_and_ [https://host.docker.internal:9201](https://host.docker.internal:9201). ::: diff --git a/docs/dev/web/embed-mode.md b/docs/dev/web/embed-mode.md index 083dbc47..7f239d3c 100644 --- a/docs/dev/web/embed-mode.md +++ b/docs/dev/web/embed-mode.md @@ -3,11 +3,13 @@ title: 'Embed Mode' sidebar_position: 4 --- -The OpenCloud Web can be consumed by another application in a stripped down version called "Embed mode". This mode is supposed to be used in the context of selecting or sharing resources. +The OpenCloud Web can be consumed by another application in a stripped down version called "Embed mode". This mode is +supposed to be used in the context of selecting or sharing resources. ## Getting started -To integrate OpenCloud Web into your application, add an iframe element pointing to your OpenCloud Web deployed instance with additional query parameter `embed=true`. +To integrate OpenCloud Web into your application, add an iframe element pointing to your OpenCloud Web deployed instance +with additional query parameter `embed=true`. ```html @@ -15,15 +17,20 @@ To integrate OpenCloud Web into your application, add an iframe element pointing ## Communication -To establish seamless cross-origin communication between the embedded instance and the parent application, our approach involves emitting events using the `postMessage` method. These events can be conveniently captured by utilizing the standard `window.addEventListener('message', listener)` pattern. +To establish seamless cross-origin communication between the embedded instance and the parent application, our approach +involves emitting events using the `postMessage` method. These events can be conveniently captured by utilizing the +standard `window.addEventListener('message', listener)` pattern. ### Target origin -By default, the `postMessage` method does not specify the `targetOrigin` parameter. However, it is recommended best practice to explicitly pass in the URI of the iframe origin (not the parent application). To enhance security, you can specify this value by modifying the config option `options.embed.messagesOrigin`. +By default, the `postMessage` method does not specify the `targetOrigin` parameter. However, it is recommended best +practice to explicitly pass in the URI of the iframe origin (not the parent application). To enhance security, you can +specify this value by modifying the config option `options.embed.messagesOrigin`. ### Events -To maintain uniformity and ease of handling, each event encapsulates the same structure within its payload: `{ name: string, data: any }`. +To maintain uniformity and ease of handling, each event encapsulates the same structure within its payload: +`{ name: string, data: any }`. | Name | Data | Description | | -------------------------- | ------------ | ------------------------------------------------------------------------------------- | @@ -53,8 +60,12 @@ To maintain uniformity and ease of handling, each event encapsulates the same st ## Location picker -By default, the Embed mode allows users to select resources. In certain cases (e.g. uploading a file), this needs to be changed to allow selecting a location. This can be achieved by running the embed mode with additional parameter `embed-target=location`. With this parameter, resource selection is disabled and the selected resources array always includes the current folder as the only item. -In special scenarios you also want the user to set a file name, this can be achieved by adding the `embed-choose-file-name=true` parameter, or if you also want to set a default file name, you can use `embed-choose-file-name-suggestion=my file.text`. +By default, the Embed mode allows users to select resources. In certain cases (e.g. uploading a file), this needs to be +changed to allow selecting a location. This can be achieved by running the embed mode with additional parameter +`embed-target=location`. With this parameter, resource selection is disabled and the selected resources array always +includes the current folder as the only item. In special scenarios you also want the user to set a file name, this can +be achieved by adding the `embed-choose-file-name=true` parameter, or if you also want to set a default file name, you +can use `embed-choose-file-name-suggestion=my file.text`. ### Example @@ -87,9 +98,7 @@ combination of both. If the embed-file-types parameter is not provided, all file ### Example ```html - +