|
| 1 | +--- |
| 2 | +title: Packaging Theia as a Docker Image |
| 3 | +--- |
| 4 | + |
| 5 | +# Packaging Theia as a Docker Image |
| 6 | + |
| 7 | +Eclipse Theia Blueprint is an example product used as a reference on how to build IDE-like products based on the Eclipse Theia framework. |
| 8 | +Theia Blueprint assembles a selected subset of existing Theia features and extensions. |
| 9 | +We provide a Docker image for Theia Blueprint. |
| 10 | +In the respective git repository you can also find the source code for Theia Blueprint and the Dockerfile. |
| 11 | +This documentation will use these sources as a template. We will explain |
| 12 | +how to customize this template so you can build your own custom Theia-based product for the cloud. |
| 13 | + |
| 14 | +## Building a Docker Image |
| 15 | + |
| 16 | +The Docker build uses the `browser.Dockerfile` Dockerfile checked in at the root of the repository. |
| 17 | + |
| 18 | +The build itself consists of two stages.\ |
| 19 | +In the `build-stage` we are building the workspace using `yarn` and perform some cleanup tasks to make the build results smaller.\ |
| 20 | +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. |
| 21 | +Additional tools required for the desired use of the application (like Git, a JDK for Java development, Maven, ...) are installed. |
| 22 | +The build results are copied from the `build-stage` and environment variables used by Theia are set.\ |
| 23 | +Please check the comments in `browser.Dockerfile` for more detailed information about every step. |
| 24 | + |
| 25 | +You can build the docker image running `docker build -t theia-blueprint -f browser.Dockerfile .` at the root of the repository. |
| 26 | + |
| 27 | +You can run your image using `docker run -p=3000:3000 --rm theia-blueprint` and pointing your browser to http://localhost:3000. |
| 28 | + |
| 29 | +## Updating Bundled VS Code Extensions |
| 30 | + |
| 31 | +All VS Code extensions that are already included in the product at start-up, are defined in `applications/browser/package.json`. |
| 32 | +They are listed under the `theiaPlugins` property as key-value pairs. |
| 33 | +The keys can be freely chosen as long as they represent a valid folder name and are unique within the `theiaPlugins` property. |
| 34 | +We suggest using the extension’s unique identifier. |
| 35 | +The value is the download URL of the extensions. |
| 36 | +They will be downloaded automatically during the `docker build`. |
| 37 | + |
| 38 | +To remove an extension from the product, simply delete its entry. |
| 39 | + |
| 40 | +### Extension sources |
| 41 | + |
| 42 | +We use the [Open VSX Registry](https://open-vsx.org/) of the Eclipse Foundation to install extensions. |
| 43 | +It is an open and community-driven VS Code extension marketplace. |
| 44 | +More information can be found at [eclipse.org](https://www.eclipse.org/legal/open-vsx-registry-faq/). |
| 45 | + |
| 46 | +## Customizing Theia Extensions |
| 47 | + |
| 48 | +Eclipse Theia extensions can be added through `dependencies` in `applications/browser/package.json`. |
| 49 | +Like any other dependency, it will be installed via yarn. |
| 50 | +Similarly, removing an extension works by removing it from `dependencies`. |
| 51 | +For extensions already published on npm (or your private npm registry) this is all you need to do. |
| 52 | + |
| 53 | +An alternative approach is developing your extension inside Theia Blueprint’s mono repo. |
| 54 | +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. |
| 55 | +This is facilitated by the lerna build already configured in the Theia Blueprint’s repository. |
| 56 | +It links the product and all extensions in the repository together during the build. |
| 57 | + |
| 58 | +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. |
| 59 | +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`. |
| 60 | +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. |
| 61 | +After successfully generating the extension, add its folder name to the Theia Blueprint’s root `package.json` in the workspaces property. |
| 62 | +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. |
| 63 | + |
| 64 | +## Branding |
| 65 | + |
| 66 | +You can also add your own branding to the product by customizing the application icons and title, the welcome page and the About dialog. |
| 67 | +In addition, some parts of the installer can be customized. |
| 68 | + |
| 69 | +### Customizing the App |
| 70 | + |
| 71 | +#### Application Window Title |
| 72 | + |
| 73 | +The window title is the application’s name if no workspace is opened and `<workspace name> — <application name>` if a workspace is opened. |
| 74 | +The application name can be adapted in `applications/browser/package.json`: |
| 75 | +Open the file and adapt the value of property `theia.frontend.config.applicationName` to the desired name. |
| 76 | + |
| 77 | +### Customizing the Welcome Page |
| 78 | + |
| 79 | +The Eclipse Theia welcome page can be customized by binding a custom `WidgetFactory` for Theia’s `GettingStartedWidget`. |
| 80 | +This is done with Theia Blueprint in the theia-blueprint-product extension. |
| 81 | +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`. |
| 82 | + |
| 83 | +The widget is bound in `theia-extensions/theia-blueprint-product/src/browser/theia-blueprint-frontend-module.ts` like this: |
| 84 | + |
| 85 | +```typescript |
| 86 | + bind(TheiaBlueprintGettingStartedWidget).toSelf(); |
| 87 | + bind(WidgetFactory).toDynamicValue(context => ({ |
| 88 | + id: GettingStartedWidget.ID, |
| 89 | + createWidget: () => context.container.get<TheiaBlueprintGettingStartedWidget>(TheiaBlueprintGettingStartedWidget), |
| 90 | + })).inSingletonScope(); |
| 91 | +``` |
| 92 | + |
| 93 | +To use another custom widget, remove this code and bind your widget correspondingly. |
| 94 | + |
| 95 | +### Customizing the About Dialog |
| 96 | + |
| 97 | +The Eclipse Theia about dialog can be customized by binding a custom subclass of Theia’s `AboutDialog` class to `AboutDialog`. |
| 98 | +This is done with Theia Blueprint in the theia-blueprint-product extension. |
| 99 | +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`. |
| 100 | + |
| 101 | +The widget is bound in `theia-extensions/theia-blueprint-product/src/browser/theia-blueprint-frontend-module.ts` like this: |
| 102 | + |
| 103 | +```typescript |
| 104 | +isBound(AboutDialog) ? rebind(AboutDialog).to(TheiaBlueprintAboutDialog).inSingletonScope() : bind(AboutDialog).to(TheiaBlueprintAboutDialog).inSingletonScope(); |
| 105 | +``` |
| 106 | + |
| 107 | +To use another custom dialog widget, remove this code, extend Theia’s AboutDialog class, and (re)bind it as above. |
0 commit comments