Added docker-compose.yml and enhanced documentation to get a just a UI for development

[janklostermann]

The purpose of this enhancement is simplifying the getting started for people who want to develop just edge, and need an easy way to get a UI up and running. With the docker-compose.yml a container with the UI can be created and spun-up, all network configuration prepared for development on the local host machine. All details around it are explained in the documentation file. I just extended the existing page under deploy with docker for edge (where the documentation on getting the UI via docker leads to).
If you feel there are better places for this stuff, feel free to move it, but be aware that there are references to the doc-file elsewhere.

[da-Kai]

Hi @janklostermann,
thanks for your PR.
I had originally omitted docker-compose files for hosting just the UI, as i didn’t see a clear use case. If this setup supports your development, it’s certainly valuable to include.
I am just not sure about the current placement of the docs and files.

[janklostermann]

Hello @kai_da, I'm fully fine with your recommendations. I just used the existing place of the .adoc. And put the docker-compose.yml in root for simplicity. If you come from getting started there are links to these places. I should be able to find and adjust the place that I am remembering. Are you aware of other links on how to setup UI / UI for dev (with docker being one of them)? Shall I do the changes or will you do them? Thanks, Jan Am 20. November 2025 20:01:46 MEZ schrieb da Kai ***@***.***>:

@da-Kai requested changes on this pull request. Hi @janklostermann, thanks for your PR. I had originally omitted docker-compose files for hosting just the UI, as i didn’t see a clear use case. If this setup supports your development, it’s certainly valuable to include. I am just not sure about the current placement of the docs and files. > + +== OpenEMS UI for development + +If you just want to have the OpenEMS UI served from a docker container, you can do so by adjusting your `docker-compose.yml` file to look like this: + +[source,yaml] +---- +services: + openems-ui: + image: openems/ui-edge:latest + container_name: openems_ui + hostname: openems_ui + restart: unless-stopped + volumes: + - openems-ui-conf:/etc/nginx:rw + - openems-ui-log:/var/log/nginx:rw + environment: + - WEBSOCKET_HOST=host.docker.internal + - WEBSOCKET_PORT=8085 + ports: + - 4200:80 + - 443:443 + +volumes: + openems-ui-conf: + openems-ui-log: +---- + +summary of the changes: +1. Just the service `openems-ui` in the docker-compose file +2. The WEBSOCKET_HOST is directed to the localhost of the host computer (assumed to be your development machine) +3. The internal port 80 is mapped to the external port 4200 to allow the links to localhost:4200 in the dev environment and documentation to function +4. The volumes `openems-ui-conf` and `openems-ui-log` + +=== Update docker-compose + +Update the compose running with: `docker compose up -d` + +==== Check container status + +[source,bash] +---- ***@***.***:~$ docker ps +CONTAINER ID IMAGE COMMAND CREATED STATUS PORTS NAMES +d708a6cd1583 openems/ui-edge:latest "/init" 2 hours ago Up About an hour 0.0.0.0:443->443/tcp, [::]:443->443/tcp, 0.0.0.0:4200->80/tcp, [::]:4200->80/tcp openems_ui_dev +---- + +=== Troubleshooting +If after opening the page at http://localhost:4200/ you get an error page telling you to wait incase the OpenEMS device was just started, then: +* Make sure that the OpenEMS Edge is running (Eclipse: `Run OSGi` in `EdgeApp.bndrun` under `io.openems.edge.application`), +* The Apache Felix Web Console is reachable at http://localhost:8080/system/console/configMgr, and +* You have configured the openEMS component 'Controller Api Websocket` with Port set to `8085`. The file `doc/modules/ROOT/pages/edge/deploy/docker.adoc` is focused on setting up an Edge instance. The section about running a single UI instance would fit better either under [`doc/modules/ROOT/pages/gettingstarted.adoc?plain=1#L241`](https://github.com/OpenEMS/openems/blob/develop/doc/modules/ROOT/pages/gettingstarted.adoc?plain=1#L241) or in a separate document such as `doc/modules/ROOT/pages/ui/deploy/docker.adoc`. > +services: + openems-ui-dev: + image: openems/ui-edge:latest + container_name: openems_ui_dev + hostname: openems_ui + restart: unless-stopped + volumes: + - openems-ui-conf:/etc/nginx:rw + - openems-ui-log:/var/log/nginx:rw + environment: + - WEBSOCKET_HOST=host.docker.internal + - WEBSOCKET_PORT=8085 + ports: + - 4200:80 + - 443:443 + + +volumes: + openems-ui-conf: + openems-ui-log: This file should be moved to `tools/docker/ui/` to stay consistent with the location of the other docker-compose files. -- Reply to this email directly or view it on GitHub: #3430 (review) You are receiving this because you were mentioned. Message ID: ***@***.***>

-- Jan Klostermann Klostermann Engineering AI Transformation Partner Von /e/ Mail gesendet.

[da-Kai]

Hi @janklostermann,

Are you aware of other links on how to setup UI / UI for dev (with docker being one of them)?

Not that I know of. The standalone UI Docker container is mostly just helpful for development.

Shall I do the changes or will you do them?

It's your PR, so feel free to make the changes. But if you just want it added quickly, I’m happy to handle it too.

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.

Additional details and impacted files

@@              Coverage Diff              @@
##             develop    #3430      +/-   ##
=============================================
+ Coverage      59.75%   59.79%   +0.05%     
  Complexity       112      112              
=============================================
  Files           2870     2870              
  Lines         124042   124042              
  Branches        9298     9298              
=============================================
+ Hits           74111    74162      +51     
+ Misses         47150    47088      -62     
- Partials        2781     2792      +11     

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.
• 📦 JS Bundle Analysis: Save yourself from yourself by tracking and limiting bundle sizes in JS merges.

[da-Kai]

Hi @janklostermann,

Thanks, this looks much better! I have just a few minor improvements and a small bugfix.

[janklostermann]

Yesterday I found out that the above docker-compose.yml works under Windows as dev machine (where I tested it before the PR), but not under WSL2/Linux.
WSL2/Linux is quite tricky: After trying various paths using standard docker & network concepts, the only one working was using the explicit use of the IP address of the WSL2 in the docker-compose.yml, Which as a result needs a shell script to keep the process simple, automatic and fault resistant.
I am still working on it, to simplify it and provide a good understandable documentation.
Unfortunately I cannot test it on pure Linux or Mac myself. (I guess it should be identical to Windows and just WSL2/Linux needs a workaround due to its system in system architecture.)
Summary: There is more to come for this PR, beyond the port clarification.

[da-Kai]

Hi @janklostermann,
thanks for your adjustments, i see you extended your PR.

[da-Kai]

Hi @janklostermann,
i noticed two minor points that could simplify your script.

[sfeilmeier]

Thank you!