[docs-only] docs: first draft of the custom apps in ocis and web blog post, part-1

docs/writings/web-apps/part-1.md

@@ -0,0 +1,199 @@
+### Blog Post Series: Understanding Web Applications in oCIS
+
+#### Part 1: Overview and How to Load Extensions
+
+---
+
+**Introduction to Web Applications in oCIS**
+
+In today's fast-paced digital world, web applications play a crucial role in enhancing user experience and functionality.
+
+For organizations using ownCloud Infinite Scale (oCIS), understanding how to leverage web applications can significantly enhance their productivity and user engagement.
+
+In this series, we will delve into the world of web applications in oCIS, focusing on how extensions are loaded and utilized.
+
+---
+
+**Why We Need Web Applications**
+
+Web applications are essential for several reasons:
+
+1. **Accessibility**:\
+Web applications can be accessed from any device with an internet connection, providing flexibility and convenience.
+2. **Customization**:\
+They allow organizations to customize and extend the functionality of their platform to meet specific needs.
+3. **Integration**:\
+Web applications enable seamless integration with third-party services and tools, enhancing overall functionality.
+
+By leveraging web applications, organizations can create a more tailored and efficient environment for their users, ensuring that they have the tools they need to succeed.
+
+---
+
+**Use Cases and Benefits of Custom Extensions**
+
+The ability to provide custom extensions in oCIS opens up a myriad of possibilities for organizations. Here are some key use cases and benefits:
+
+1. **Tailored User Experience**:\
+Custom extensions allow organizations to create a unique user experience that aligns with their specific needs. For instance, a company can develop a custom dashboard that displays relevant metrics and reports, enhancing productivity and decision-making.
+
+2. **Third-Party Integrations**:\
+Organizations can integrate third-party services and tools directly into their oCIS environment. This can include CRM systems, marketing automation tools, or custom data visualization tools, providing a seamless workflow for users.
+
+3. **Enhanced Security and Compliance**:\
+Custom extensions can help organizations adhere to specific security and compliance requirements by adding features like custom authentication mechanisms, data encryption tools, or compliance reporting modules.
+
+4. **Branding and Identity**:\
+By customizing the look and feel of the web applications, organizations can ensure their brand identity is consistently represented across their digital platforms. This can include custom themes, logos, and color schemes.
+
+5. **Innovative Features**:\
+Custom extensions allow organizations to experiment with new features and functionalities that are not available in the default setup. This can include AI-powered tools, advanced analytics, or unique collaboration features.
+
+The ability to provide custom extensions makes oCIS a powerful and flexible platform that can adapt to the evolving needs of any organization.
+
+It empowers administrators to craft solutions that are not only functional but also aligned with their strategic goals.
+
+---
+
+**Loading Extensions in oCIS**
+
+In oCIS, extensions can be loaded at both build time and runtime. Understanding the difference between these two methods is key to effectively managing and utilizing extensions.
+
+- **Build Time Extensions**:\
+These are integrated into the binary during the build process. They are part of the core system and cannot be altered without rebuilding the system. This ensures a stable and consistent environment where critical applications are always available.
+
+- **Run Time Extensions**:\
+These are loaded dynamically at runtime, providing greater flexibility. They can be placed in a designated directory and are automatically picked up by the system. This allows administrators to easily add, update, or remove extensions as needed, without the need for a system rebuild.
+
+---
+
+**How to Load Extensions**
+
+1. **Build Time Extensions**:
+   - Located in `<ocis_repo>/services/web/assets/apps`.
+   - Integrated into the system during the build process.
+   - These extensions are part of the binary and cannot be modified at runtime.
+
+2. **Run Time Extensions**:
+   - Stored in the directory specified by the `WEB_ASSET_APPS_PATH` environment variable.
+   - By default, this path is `$OCIS_BASE_DATA_PATH/web/apps`, but it can be customized.
+   - Run time extensions are automatically loaded from this directory, making it easy to add or remove extensions without rebuilding the system.
+
+The ability to load extensions at runtime is particularly powerful, as it allows for a high degree of customization and flexibility. Administrators can quickly respond to changing needs by adding new functionality or removing outdated extensions.
+
+---
+
+**Manifest File**
+
+Each web application must include a `manifest.json` or `manifest.yaml` file. This file contains essential information about the application, including its entry point and configuration details.
+
+**Example of a manifest.json file**:
+```json
+{
+  "entrypoint": "index.js",
+  "config": {
+    "maxWidth": 1280,
+    "maxHeight": 1280
+  }
+}
+```
+
+The manifest file ensures that the system correctly recognizes and integrates the extension. It is a crucial component for defining how the web application should be loaded and what configurations it requires.
+
+---
+
+**Custom Configuration and Overwriting Options**
+
+Administrators can provide custom configurations in the `$OCIS_BASE_DATA_PATH/config/apps.yaml` file. This allows for fine-tuning of each extension's behavior and settings.
+
+The `apps.yaml` file can contain custom settings that overwrite the default configurations specified in the extension's `manifest.json` file.
+
+**Example of apps.yaml file**:
+```yaml
+image-viewer-obj:
+  config:
+    maxHeight: 640
+    maxSize: 512
+```
+
+In this example, the `maxHeight` value specified in the `apps.yaml` file will overwrite the value from the `manifest.json` file.
+
+This provides administrators with the flexibility to customize extensions to better meet the specific needs of their environment.
+
+---
+
+**Using Custom Assets**
+
+Besides configuration, administrators might need to customize certain assets within an extension, such as logos or images.
+
+This can be achieved by placing the custom assets in the path defined by `WEB_ASSET_APPS_PATH`.
+
+For instance, if the default `image-viewer-dfx` application includes a logo that an organization wants to replace,
+they can place the new logo in a directory structured like `WEB_ASSET_APPS_PATH/image-viewer-dfx/logo.png`.
+
+The system will load this custom asset, replacing the default one. This method allows for easy and effective customization without altering the core application code.
+
+---
+
+**Configuration Example**
+
+To illustrate how custom configurations and assets work together, consider the following scenario:
+
+1. **Default Configuration**:
+   ```json
+   {
+     "entrypoint": "index.js",
+     "config": {
+       "maxWidth": 1280,
+       "maxHeight": 1280
+     }
+   }
+   ```
+
+2. **Custom Configuration in apps.yaml**:
+   ```yaml
+   image-viewer-obj:
+     config:
+       maxHeight: 640
+       maxSize: 512
+   ```
+
+3. **Final Merged Configuration**:
+   ```json
+   {
+     "external_apps": [
+       {
+         "id": "image-viewer-obj",
+         "path": "index.js",
+         "config": {
+           "maxWidth": 1280,
+           "maxHeight": 640,
+           "maxSize": 512
+         }
+       }
+     ]
+   }
+   ```
+
+This example demonstrates how the system merges default and custom configurations to create the final settings used by the application.
+
+---
+
+**Conclusion**
+
+In this first part of our series, we've covered the basics of web applications in oCIS, focusing on the importance of web applications,
+how extensions are loaded, and how administrators can customize these extensions through configuration and asset overwriting.
+
+Understanding these fundamentals is crucial for effectively managing and leveraging web applications in oCIS.
+
+In the next post, we will dive deeper into the process of writing and running a basic extension.
+
+Stay tuned for detailed instructions and tips on getting started with your first web extension in oCIS.
+
+---
+
+**Resources**:
+
+- [Web Readme](https://github.com/owncloud/ocis/tree/master/services/web)
+- [Overview of Available Extensions](https://github.com/owncloud/awesome-ocis)
+- [Introduction PR](https://github.com/owncloud/ocis/pull/8523)
+- [Design Document and Requirements](https://github.com/owncloud/ocis/issues/8392)

docs/writings/web-apps/run/apps/hello/.dockerignore

@@ -0,0 +1,2 @@
+node_modules
+.pnpm-store

docs/writings/web-apps/run/apps/hello/.editorconfig

@@ -0,0 +1,14 @@
+root = true
+
+[*]
+insert_final_newline = true
+charset = utf-8
+trim_trailing_whitespace = true
+end_of_line = lf
+
+[*.{js,json,vue,feature}]
+indent_style = space
+indent_size = 2
+
+[*.{md,markdown}]
+trim_trailing_whitespace = false

docs/writings/web-apps/run/apps/hello/.eslintrc.json

@@ -0,0 +1,8 @@
+{
+  "extends": "@ownclouders",
+  "settings": {
+    "jest": {
+      "version": "remove jest rules from @ownclouders/eslint-config and remove this"
+    }
+  }
+}

docs/writings/web-apps/run/apps/hello/.prettierrc.json

@@ -0,0 +1 @@
+"@ownclouders/prettier-config"

docs/writings/web-apps/run/apps/hello/Dockerfile

@@ -0,0 +1,10 @@
+FROM node:20-slim AS base
+ENV PNPM_HOME="/pnpm"
+ENV PATH="$PNPM_HOME:$PATH"
+RUN corepack enable
+WORKDIR /app
+COPY ./package.json .
+COPY ./pnpm-lock.yaml .
+RUN pnpm install --frozen-lockfile
+COPY . .
+CMD [ "pnpm", "build:w" ]

docs/writings/web-apps/run/apps/hello/package.json

@@ -0,0 +1,38 @@
+{
+  "name": "web-app-hello",
+  "version": "0.0.0",
+  "type": "module",
+  "scripts": {
+    "lint": "eslint src --ext vue --ext js --ext ts --color",
+    "build": "pnpm vite build",
+    "build:w": "pnpm vite build --watch --mode development"
+  },
+  "devDependencies": {
+    "@ownclouders/eslint-config": "0.0.1",
+    "@ownclouders/extension-sdk": "0.0.5-alpha.2",
+    "@ownclouders/prettier-config": "0.0.1",
+    "@ownclouders/tsconfig": "0.0.5-alpha.1",
+    "@types/node": "^20.2.3",
+    "eslint": "^8.25.0",
+    "prettier": "^3.3.2",
+    "typescript": "^5.5.3",
+    "vite": "^5.3.3",
+    "vite-plugin-generate-file": "^0.1.1",
+    "vite-plugin-static-copy": "^1.0.6",
+    "vue": "^3.4.31"
+  },
+  "peerDependencies": {
+    "@ownclouders/web-pkg": "0.0.5-alpha.9"
+  },
+  "pnpm": {
+    "peerDependencyRules": {
+      "ignoreMissing": [
+        "design-system*"
+      ]
+    }
+  },
+  "dependencies": {
+    "three": "^0.166.1"
+  },
+  "packageManager": "[email protected]"
+}