From c8ed254042185e7b9d911561a49535244012d149 Mon Sep 17 00:00:00 2001 From: Johannes Faltermeier Date: Thu, 23 Mar 2023 15:02:47 +0100 Subject: [PATCH] Restructure Blueprint section * One download section for electron and docker based app * Documentation for creating a desktop application * Documentation for creating a docker application --- src/docs/blueprint_cloud_documentation.md | 107 ++++++++++++++++++ ....md => blueprint_desktop_documentation.md} | 0 src/docs/blueprint_download.md | 12 +- src/docs/menu.js | 10 +- src/docs/summary.md | 5 +- 5 files changed, 127 insertions(+), 7 deletions(-) create mode 100644 src/docs/blueprint_cloud_documentation.md rename src/docs/{blueprint_documentation.md => blueprint_desktop_documentation.md} (100%) diff --git a/src/docs/blueprint_cloud_documentation.md b/src/docs/blueprint_cloud_documentation.md new file mode 100644 index 00000000..b0b6b9ee --- /dev/null +++ b/src/docs/blueprint_cloud_documentation.md @@ -0,0 +1,107 @@ +--- +title: Packaging Theia as a Docker Image +--- + +# Packaging Theia as a Docker Image + +Eclipse Theia Blueprint is an example product used as a reference on how to build IDE-like products based on the Eclipse Theia framework. +Theia Blueprint assembles a selected subset of existing Theia features and extensions. +We provide a Docker image for Theia Blueprint. +In the respective git repository you can also find the source code for Theia Blueprint and the Dockerfile. +This documentation will use these sources as a template. We will explain +how to customize this template so you can build your own custom Theia-based product for the cloud. + +## Building a Docker Image + +The Docker build uses the `browser.Dockerfile` Dockerfile checked in at the root of the repository. + +The build itself consists of two stages.\ +In the `build-stage` we are building the workspace using `yarn` and perform some cleanup tasks to make the build results smaller.\ +The `production-stage` is based on a slim node base-image. Here we create a dedicated user, which will run the application, and the user's home directory. +Additional tools required for the desired use of the application (like Git, a JDK for Java development, Maven, ...) are installed. +The build results are copied from the `build-stage` and environment variables used by Theia are set.\ +Please check the comments in `browser.Dockerfile` for more detailed information about every step. + +You can build the docker image running `docker build -t theia-blueprint -f browser.Dockerfile .` at the root of the repository. + +You can run your image using `docker run -p=3000:3000 --rm theia-blueprint` and pointing your browser to http://localhost:3000. + +## Updating Bundled VS Code Extensions + +All VS Code extensions that are already included in the product at start-up, are defined in `applications/browser/package.json`. +They are listed under the `theiaPlugins` property as key-value pairs. +The keys can be freely chosen as long as they represent a valid folder name and are unique within the `theiaPlugins` property. +We suggest using the extension’s unique identifier. +The value is the download URL of the extensions. +They will be downloaded automatically during the `docker build`. + +To remove an extension from the product, simply delete its entry. + +### Extension sources + +We use the [Open VSX Registry](https://open-vsx.org/) of the Eclipse Foundation to install extensions. +It is an open and community-driven VS Code extension marketplace. +More information can be found at [eclipse.org](https://www.eclipse.org/legal/open-vsx-registry-faq/). + +## Customizing Theia Extensions + +Eclipse Theia extensions can be added through `dependencies` in `applications/browser/package.json`. +Like any other dependency, it will be installed via yarn. +Similarly, removing an extension works by removing it from `dependencies`. +For extensions already published on npm (or your private npm registry) this is all you need to do. + +An alternative approach is developing your extension inside Theia Blueprint’s mono repo. +The advantage of doing this is that you don’t need to publish the extension and can build the product with the local version of the extension. +This is facilitated by the lerna build already configured in the Theia Blueprint’s repository. +It links the product and all extensions in the repository together during the build. + +The easiest way to create a new extension is to use the [official yeoman generator](https://www.npmjs.com/package/generator-theia-extension) for Theia extensions. +Assuming you have [yeoman](https://yeoman.io/) globally installed on your system, simply create a new extension in the repository root with `yo theia-extension --standalone`. +The `--standalone` flag is used to only create an extension but not a whole Theia application frame because it is already provided by the Theia Blueprint. +After successfully generating the extension, add its folder name to the Theia Blueprint’s root `package.json` in the workspaces property. +After adding the extension to the dependencies in `applications/browser/package.json` as described above, the new extension will be part of the built product. + +## Branding + +You can also add your own branding to the product by customizing the application icons and title, the welcome page and the About dialog. +In addition, some parts of the installer can be customized. + +### Customizing the App + +#### Application Window Title + +The window title is the application’s name if no workspace is opened and ` — ` if a workspace is opened. +The application name can be adapted in `applications/browser/package.json`: +Open the file and adapt the value of property `theia.frontend.config.applicationName` to the desired name. + +### Customizing the Welcome Page + +The Eclipse Theia welcome page can be customized by binding a custom `WidgetFactory` for Theia’s `GettingStartedWidget`. +This is done with Theia Blueprint in the theia-blueprint-product extension. +The easiest way to customize the welcome page is to adapt the class `TheiaBlueprintGettingStartedWidget` in `theia-extensions/theia-blueprint-product/src/browser/theia-blueprint-getting-started-widget.tsx`. + +The widget is bound in `theia-extensions/theia-blueprint-product/src/browser/theia-blueprint-frontend-module.ts` like this: + +```typescript + bind(TheiaBlueprintGettingStartedWidget).toSelf(); + bind(WidgetFactory).toDynamicValue(context => ({ + id: GettingStartedWidget.ID, + createWidget: () => context.container.get(TheiaBlueprintGettingStartedWidget), + })).inSingletonScope(); +``` + +To use another custom widget, remove this code and bind your widget correspondingly. + +### Customizing the About Dialog + +The Eclipse Theia about dialog can be customized by binding a custom subclass of Theia’s `AboutDialog` class to `AboutDialog`. +This is done with Theia Blueprint in the theia-blueprint-product extension. +The easiest way to customize the about dialog is to adapt the class `TheiaBlueprintAboutDialog` in `theia-extensions/theia-blueprint-product/src/browser/theia-blueprint-about-dialog.tsx`. + +The widget is bound in `theia-extensions/theia-blueprint-product/src/browser/theia-blueprint-frontend-module.ts` like this: + +```typescript +isBound(AboutDialog) ? rebind(AboutDialog).to(TheiaBlueprintAboutDialog).inSingletonScope() : bind(AboutDialog).to(TheiaBlueprintAboutDialog).inSingletonScope(); +``` + +To use another custom dialog widget, remove this code, extend Theia’s AboutDialog class, and (re)bind it as above. diff --git a/src/docs/blueprint_documentation.md b/src/docs/blueprint_desktop_documentation.md similarity index 100% rename from src/docs/blueprint_documentation.md rename to src/docs/blueprint_desktop_documentation.md diff --git a/src/docs/blueprint_download.md b/src/docs/blueprint_download.md index 9a75c244..2e985720 100644 --- a/src/docs/blueprint_download.md +++ b/src/docs/blueprint_download.md @@ -8,7 +8,7 @@ title: Eclipse Theia Blueprint ## What is Eclipse Theia Blueprint? -Eclipse Theia Blueprint is a **template** for building desktop-based products based on the Eclipse Theia platform, as well as to showcase Eclipse Theia capabilities. It is made up of a subset of existing Eclipse Theia features and extensions and can be easily downloaded and installed on all major operating system platforms (see below). Documentation is available to help you customize and build your own Eclipse Theia-based product. +Eclipse Theia Blueprint is a **template** for building desktop-based and cloud-based products based on the Eclipse Theia platform, as well as to showcase Eclipse Theia capabilities. It is made up of a subset of existing Eclipse Theia features and extensions and can be easily downloaded and installed on all major operating system platforms (see below). Documentation is available to help you customize and build your own Eclipse Theia-based product. ## What is it not? @@ -18,6 +18,8 @@ Eclipse Theia Blueprint is ***not*** **a production-ready product**. Therefore, NOTE: Eclipse Theia Blueprint is currently in beta. While we are continuing to make improvements and add functionality, we welcome and value your feedback. Help us make Theia even better, by sharing your experience and suggestions [here](https://github.com/eclipse-theia/theia/discussions). +### Desktop Application + @@ -35,9 +37,15 @@ NOTE: Eclipse Theia Blueprint is currently in beta. While we are continuing to m
+### Docker Image + +A docker image is available at `ghcr.io/eclipse-theia/theia-blueprint/blueprint` + +You may run this on your machine with `docker run -p=3000:3000 --rm ghcr.io/eclipse-theia/theia-blueprint/blueprint` and point your browser to http://localhost:3000. + ## Try Theia Blueprint Online -You can also [try the latest version of Theia Blueprint online](https://try.theia-cloud.io/). The online test version is limited to 30 minutes per session and hosted via [Theia.cloud](https://github.com/eclipsesource/theia-cloud). +You can also [try the latest version of Theia Blueprint online](https://try.theia-cloud.io/). The online test version is limited to 30 minutes per session and hosted via [Theia Cloud](https://theia-cloud.io/). ## Reporting Feature Requests and Bugs diff --git a/src/docs/menu.js b/src/docs/menu.js index 29e8c34d..46b1a36e 100644 --- a/src/docs/menu.js +++ b/src/docs/menu.js @@ -139,15 +139,19 @@ export const MENU = [ 'tips' ), { - title: 'Theia Blueprint' + title: 'Packaging as a Product' }, M( 'Download', 'blueprint_download' ), M( - 'Documentation', - 'blueprint_documentation' + 'Desktop', + 'blueprint_desktop_documentation' + ), + M( + 'Cloud', + 'blueprint_cloud_documentation' ) ] diff --git a/src/docs/summary.md b/src/docs/summary.md index ef5176a4..bcc7ecf0 100644 --- a/src/docs/summary.md +++ b/src/docs/summary.md @@ -21,7 +21,8 @@ * [Events](Events.md) * [Communication via JSON-RPC](Json_Rpc.md) -## Blueprint +## Packaging as a Product * [Download](blueprint_download.md) -* [Documentation](blueprint_documentation.md) +* [Desktop](blueprint_desktop_documentation.md) +* [Cloud](blueprint_cloud_documentation.md)