Re-organize the two docker examples into a monorepo

Also:
- update them to use the "previous latest" Theia community release, v1.49.1
- move docker example using the Trace Viewer for VS Code
- rename docker examples sub-folders
- rename example-package.json to package.json

Signed-off-by: Marc Dumais <[email protected]>

Author: marcdumais-work

.github/workflows/docker-example.yml

@@ -17,6 +17,11 @@ jobs:
       matrix:
         os: [ubuntu-latest]
         node-version: [18]
+        params:
+          - name: "tate"
+            resources-folder: "theia-app-theia-ext"
+          - name: "tave"
+            resources-folder: "theia-app-vscode-ext"
 
     steps:
     - uses: actions/checkout@v4
@@ -26,23 +31,25 @@ jobs:
       with:
         node-version: ${{ matrix.node-version }}
 
-    - name: Build example-docker
+    - name: Build example app
       uses: nick-invision/retry@v3
       with:
         timeout_minutes: 10
         retry_wait_seconds: 15
-        max_attempts: 3
+        max_attempts: 1
         retry_on: error
         command: |
-          cd examples/docker
-          docker build -t tte .
+          cd docker
+          docker build . --build-arg RESOURCES=${{ matrix.params.resources-folder }} -t tv-${{ matrix.params.name }} -f Dockerfile-${{ matrix.params.name }} 
         on_retry_command: cd ../..
 
     - name: Run docker image
       run: |
-        docker run --init -d -p 0.0.0.0:3000:4000 tte
+        docker run --init -d -p 0.0.0.0:3000:4000 tv-${{ matrix.params.name }}
 
     - name: Test trace viewer appliance
       run: |
         yarn --ignore-scripts
-        yarn test:browser-app
+        cd docker
+        yarn --cwd ${{ matrix.params.resources-folder }} test
+

.gitignore

@@ -0,0 +1,6 @@
+docker/*/gen-webpack.*
+docker/*/lib
+docker/*/src-gen
+node_modules/
+docker/*/plugins
+

README.md

@@ -1,2 +1,31 @@
-# trace-viewer-examples
-Trace viewer example applications and building blocks that can be used in or with them. Each application integrates either the Eclipse Theia trace viewer extension or the trace viewer extension for VS Code
+# Trace Viewer Examples
+
+Trace viewer example applications and building blocks that can be used in or with them. Each application integrates either the [Eclipse Theia trace viewer extension](https://www.npmjs.com/package/theia-traceviewer) (npmjs.com) or the [Trace Viewer extension for VSCode](https://open-vsx.org/extension/eclipse-cdt/vscode-trace-extension) (open-vsx.org).
+
+## Requirements
+
+### General Requirements
+
+Generally speaking, all trace viewer example applications rely on the Trace Server Protocol (TSP), and require a compatible _Trace Server_. ATM it's left to the user to provide the trace server, start it and potentially configure the example application to access it, if it's not on the default host/port (localhost:8080). For more details, please consult the following documentation:
+
+- obtaining/using the Eclipse Trace Compass trace server: [doc](https://github.com/eclipse-cdt-cloud/vscode-trace-extension/blob/master/vscode-trace-extension/README.md#obtain-the-trace-server-eclipse-trace-compass)
+- using the theia trace viewer extension: [README](https://github.com/eclipse-cdt-cloud/theia-trace-extension#using-the-trace-extension)
+- using the trace viewer for vscode: [README](https://github.com/eclipse-cdt-cloud/vscode-trace-extension/blob/master/vscode-trace-extension/README.md)
+
+### Development Requirements
+
+To build Theia-based applications "natively", i.e. not in docker:
+
+- see this page: [Theia Developing.md "Prerequisites"](https://github.com/eclipse-theia/theia/blob/master/doc/Developing.md#prerequisites)
+
+To build the docker images you need to have Docker, or potentially a replacement such as Podman, installed and configured to be usable as a non-admin user.
+
+## Examples Applications
+
+### Docker examples
+
+Easy to consume _trace viewer appliance_ Docker images, that you can build yourself. For more details look under folder [docker](./docker)
+
+### Electron
+
+(TODO) Electron-based desktop trace viewer application, that can be packaged for distribution

docker/theia-trace-extension/Dockerfile docker/Dockerfile-tatedocker/theia-trace-extension/Dockerfile renamed to docker/Dockerfile-tate

@@ -1,4 +1,5 @@
-FROM node:18.19.1-bookworm-slim as build
+FROM node:18.20.4-bookworm-slim AS build
+ARG RESOURCES
 
 RUN apt-get update && apt-get install -y \
     git \
@@ -11,31 +12,32 @@ RUN apt-get update && apt-get install -y \
     libxkbfile-dev
 
 # Build the browser theia-trace-extension application
-COPY example-package.json /app/tte/package.json
-COPY webpack.config.js /app/tte/webpack.config.js
-WORKDIR /app/tte/
+COPY ${RESOURCES}/package.json /app/tv/
+COPY ${RESOURCES}/webpack.config.js /app/tv/
+COPY yarn.lock  /app/tv/
+WORKDIR /app/tv/
 RUN yarn && \
-    npx theia build --app-target=\"browser\" --mode production && \
+    yarn build:prod && \
     yarn autoclean --init && \
     echo *.ts >> .yarnclean && \
     echo *.ts.map >> .yarnclean && \
     echo *.spec.* >> .yarnclean && \
     yarn --production && \
-    yarn cache clean && \
-    du -hs /app/tte
+    yarn cache clean
 
 FROM node:18.19.1-bookworm-slim
+ARG RESOURCES
 
-COPY --from=build /app/tte /app/tte
+COPY --from=build /app/tv /app/tv
 
 RUN apt-get update && apt-get install -y \
     libx11-6 \
     libxkbfile1 \
     libsecret-1-0 \
     && rm -rf /var/lib/apt/lists/*
-ENV NODE_ENV production
+ENV NODE_ENV=production
 
-WORKDIR /app/tte
-COPY docker-entrypoint.sh /usr/local/bin
+WORKDIR /app/tv
+COPY ${RESOURCES}/docker-entrypoint.sh /usr/local/bin
 EXPOSE 4000
 ENTRYPOINT ["docker-entrypoint.sh"]

examples/docker/Dockerfile docker/Dockerfile-taveexamples/docker/Dockerfile renamed to docker/Dockerfile-tave

@@ -1,4 +1,5 @@
-FROM node:18.19.1-bookworm-slim as build
+FROM node:18.20.4-bookworm-slim AS build
+ARG RESOURCES
 
 RUN apt-get update && apt-get install -y \
     git \
@@ -11,33 +12,34 @@ RUN apt-get update && apt-get install -y \
     libxkbfile-dev
 
 # Build the browser trace-extension application
-COPY example-package.json /app/tte/package.json
-COPY webpack.config.js /app/tte/webpack.config.js
-WORKDIR /app/tte/
+COPY ${RESOURCES}/package.json /app/tv/
+COPY ${RESOURCES}/webpack.config.js /app/tv/
+COPY yarn.lock  /app/tv/
+WORKDIR /app/tv/
 RUN yarn && \
     yarn run download:plugins && \
-    npx theia build --app-target=\"browser\" --mode production && \
+    yarn build:prod && \
     yarn autoclean --init && \
     echo *.ts >> .yarnclean && \
     echo *.ts.map >> .yarnclean && \
     echo *.spec.* >> .yarnclean && \
     echo "!@theia/test" >> .yarnclean && \
     yarn --production && \
-    yarn cache clean && \
-    du -hs /app/tte
+    yarn cache clean
 
 FROM node:18.19.1-bookworm-slim
+ARG RESOURCES
 
-COPY --from=build /app/tte /app/tte
+COPY --from=build /app/tv /app/tv
 
 RUN apt-get update && apt-get install -y \
     libx11-6 \
     libxkbfile1 \
     libsecret-1-0 \
     && rm -rf /var/lib/apt/lists/*
-ENV NODE_ENV production
+ENV NODE_ENV=production
 
-WORKDIR /app/tte
-COPY docker-entrypoint.sh /usr/local/bin
+WORKDIR /app/tv
+COPY ${RESOURCES}/docker-entrypoint.sh /usr/local/bin
 EXPOSE 4000
 ENTRYPOINT ["docker-entrypoint.sh"]

docker/README.md

@@ -0,0 +1,120 @@
+# Docker examples
+
+This folder and sub-folders contain what's necessary to build Trace Viewer example Docker images, that each contain a Trace Viewer frontend application.
+
+Each application has a `DockerFile` in this folder and its resources in a sub-folder:
+
+- `DockerFile-tate, resources folder: theia-app-theia-ext/`: Dockerfile and resourced needed to build a Trace Viewer Appliance, using a Theia application that includes the _Theia Trace Viewer_ _(Theia) extension_, installed [from npm][npm package].
+- `DockerFile-tave, resources folder: theia-app-vscode-ext/`: Dockerfile and resources needed to build a Trace Viewer Appliance, using a Theia application that includes the _Trace Viewer for VSCode_ _(vsix) extension_, installed [from the open vsx public registry][vsix package]
+
+Note:
+
+- the images will contain exclusively the trace viewer front-end. If you want to run a complete _trace viewer_ application, you will need a service running the trace-server (not included here)
+
+## Quickly Build/Run the example Docker images
+
+(_see section further down to learn how to manually build/run the images_)
+
+For convenience and use in CI, there are `package.json scripts` to build the docker images on Linux. Note that it's not necessary to build anything in the repo first:
+
+```bash
+$ cd <repo>/docker
+
+# build all docker images
+$ yarn build:docker
+
+
+# build docker images individually
+
+# build "tate" image: Theia app that uses 
+# the theia trace viewer extension:
+$ yarn build:docker:tate
+# Run image:
+$ yarn run:docker:tate
+
+
+# build "tave" image: Theia app that uses 
+# the vscode trace viewer extension:
+$ yarn build:docker:tave
+# Run image:
+$ yarn run:docker:tave
+
+# Access the application at http://localhost:4000/
+# e.g.:
+$ firefox http://localhost:4000
+
+```
+
+## Manually Build/run the example Docker images
+
+The Docker images can be build from the `<repo>/docker` folder. For each image, the resources it needs are in a sub-folder, whose name is passed as a `docker build` build argument and used to retrieve expected resourced needed during image build.
+
+### Build/Run the "tate" image
+
+Build the image and name it _tv-tate_ (short for `"trace viewer - theia application/theia extension"`). You may use a different name if you prefer.
+
+Try adding `--network host` in case of build failures related to debian packages retrieval:
+
+```bash
+docker build -f Dockerfile-tate -t tv-tate --build-arg RESOURCES=theia-app-theia-ext .
+```
+
+Once the image has been built, start a container named _tv-tate-1_ from the _tv-tate_ image:
+
+```bash
+docker run --name tv-tate-1 tv-tate
+```
+
+Find the IP address of the _tv-tate-1_ container:
+
+```bash
+docker inspect -f '{{range .NetworkSettings.Networks}}{{.IPAddress}}{{end}}' tv-tate-1
+```
+
+Connect to port `4000` of the IP identified earlier using your browser. You should be able to see the theia-trace-extension UI. If it is not visible, click on `View -> Open View... -> Trace Viewer`
+
+#### Connect to a trace-server
+
+Let's say you have another container running the trace-server at IP 172.17.0.2, port `8080`. You can launch the _tv-tate-1_ container and connect it to the trace-server using the following command:
+
+```bash
+docker run --name tv-tate-1 --network="host" -e TRACE_SERVER_URL=172.17.0.2:8080/tsp/api tv-tate
+```
+
+### Build/Run the "tave" image
+
+Build the image and name it _tv-tave_ (short for `"trace viewer - theia application/vscode extension"`). You may use a different name if you prefer.
+
+Try adding `--network host` in case of build failures related to debian packages retrieval.
+
+```bash
+docker build -f Dockerfile-tave -t tv-tave --build-arg RESOURCES=theia-app-vscode-ext .
+```
+
+Once the image has been built, start a container named _tv-tave-1_ fromthe _tave_ image:
+
+```bash
+docker run --name tv-tave-1 --network host tv-tave
+```
+
+Connect to `localhost:4000` your browser. You should be able to see the trace-extension UI. If it is not visible, click on `View -> Open View... -> Trace Viewer`
+
+## Development
+
+When the _Theia applications_ are modified/updated, e.g. to update the contained trace extension or for other reasons, it's important to build the modified app(s) outside Docker and check-in the modified `yarn.lock`. The lock file is used when building in the container, to insure a known/curated set of dependencies/versions are used. Without the lock file, unexpected 3PPs or versions of 3PPs might be pulled.
+
+To build the Theia applications:
+
+```bash
+# build both apps (dev)
+$ yarn && yarn build
+
+# build both apps (prod version)
+$ yarn && yarn build:prod
+```
+
+If after the build, it turns-out that `yarn.lock` has been modified, the new version needs to be upstreamed as part of the PR that changed the Theia application.
+
+
+[npm package]: https://www.npmjs.com/package/theia-traceviewer
+[vsix package]: https://open-vsx.org/extension/eclipse-cdt/vscode-trace-extension

docker/package.json

@@ -0,0 +1,32 @@
+{
+  "private": true,
+  "name": "docker-examples",
+  "version": "0.1.0",
+  "dependencies": {
+
+  },
+  "devDependencies": {
+  },
+  "scripts": {
+    "prepare": "yarn tave",
+    "build": "yarn tate build && yarn tave build",
+    "build:prod": "yarn tate build:prod && yarn tave build:prod",
+    "tate": "yarn --cwd theia-app-theia-ext",
+    "tave": "yarn --cwd theia-app-vscode-ext",
+    "build:docker": "yarn build:docker:tate && yarn build:docker:tave",
+    "build:docker:tate": "docker build  --no-cache --network=host . --build-arg RESOURCES=theia-app-theia-ext -t tv-tate -f Dockerfile-tate",
+    "build:docker:tave": "docker build  --no-cache --network=host . --build-arg RESOURCES=theia-app-vscode-ext -t tv-tave -f Dockerfile-tave",
+    "run:docker:tate": "docker run --rm --name tv-tate-1 --network host tv-tate",
+    "run:docker:tave": "docker run --rm --name tv-tave-1 --network host tv-tave"
+  },
+  "engines": {
+  },
+  "resolutions": {
+    "msgpackr": "^1.10.1",
+    "**/nan": "2.18.0"
+  },
+  "workspaces":[
+    "theia-app-theia-ext",
+    "theia-app-vscode-ext"
+  ]
+}

docker/theia-app-theia-ext/README.md

@@ -0,0 +1,20 @@
+# Resources for the "tate" Example docker image example
+
+This folder contains the resources, needed to create the docker image example, that bundles at its core a Theia-based application that uses the _Theia Trace Viewer_ front-end.
+
+`package.json`: This is where the Theia application is defined
+`docker-entrypoint.sh`: the docker entrypoint script, that's called when starting a container based on the image
+`webpack.config.js`: a webpack configuration file, used when building the Theia application
+
+Notes:
+
+- the various `@theia` packages used in the app need to be the same version as the ones used in other Theia apps in this monorepo, such that a single version of the Theia framework is pulled by `yarn`, else there will be problems
+- for the same reason, the `theia-traceviewer` extension used in this Theia application needs to have its Theia version aligned with the various `@theia` packages used in the app
+
+To check for this, run `yarn` in the parent folder and then `yarn why @theia/core` and confirm a single version is reported. e.g.:
+
+```bash
+[...]
+=> Found "@theia/[email protected]"
+[...]
+```

…eia-trace-extension/docker-entrypoint.sh …theia-app-theia-ext/docker-entrypoint.shdocker/theia-trace-extension/docker-entrypoint.sh renamed to docker/theia-app-theia-ext/docker-entrypoint.sh docker/theia-trace-extension/docker-entrypoint.sh renamed to docker/theia-app-theia-ext/docker-entrypoint.sh

@@ -18,17 +18,21 @@
     "@emotion/react": "^11.10.5",
     "@emotion/styled": "^11.10.5",
     "@mui/material": "^5.10.14",
-    "@theia/core": "1.45.1",
-    "@theia/navigator": "1.45.1",
-    "@theia/preferences": "1.45.1",
-    "theia-traceviewer": "0.2.0-next.20240229144356.c22cb2c.0"
+    "@theia/core": "1.49.1",
+    "@theia/navigator": "1.49.1",
+    "@theia/preferences": "1.49.1",
+    "theia-traceviewer": "0.2.7"
   },
   "devDependencies": {
-    "@theia/cli": "1.45.1"
+    "@theia/cli": "1.49.1"
   },
   "scripts": {
+    "build": "npx theia build --app-target=\"browser\" --mode development",
+    "build:prod": "npx theia build --app-target=\"browser\" --mode production",
     "start": "theia start",
-    "watch": "theia build --watch"
+    "watch": "theia build --watch",
+    "clean": "echo 'Docker: Fake clean!!!'",
+    "test": "yarn --cwd ../../playwright-tests ui-tests"
   },
   "engines": {
     "yarn": ">=1.7.0 <2",