diff --git a/CHANGELOG.md b/CHANGELOG.md index 871676d..9092a46 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -2,10 +2,14 @@ ## Project `accetto/headless-coding-g3` -[Docker Hub][this-docker] - [Git Hub][this-github] - [sibling Wiki][sibling-wiki] - [sibling Discussions][sibling-discussions] +[User Guide][this-user-guide] - [Docker Hub][this-docker] - [Git Hub][this-github] - [sibling Wiki][sibling-wiki] - [sibling Discussions][sibling-discussions] *** +### Release 23.08 + +This release brings updated and significantly shortened README files, because most of the content has been moved into the new [User guide][this-user-guide]. + ### Release 23.07.1 This release brings some enhancements in the Dockerfiles and the script `user_generator.rc` with the aim to better support extending the images. @@ -342,6 +346,8 @@ This is just a maintenance release. *** +[this-user-guide]: https://accetto.github.io/user-guide-g3/ + [this-docker]: https://hub.docker.com/u/accetto/ [this-github]: https://github.com/accetto/headless-coding-g3/ diff --git a/README.md b/README.md index 7ef3e8e..e3a5c47 100644 --- a/README.md +++ b/README.md @@ -6,7 +6,7 @@ Version: G3v3 *** -[Docker Hub][this-docker] - [Changelog][this-changelog] - [sibling Wiki][sibling-wiki] - [sibling Discussions][sibling-discussions] +[User Guide][this-user-guide] - [Docker Hub][this-docker] - [Changelog][this-changelog] - [sibling Wiki][sibling-wiki] - [sibling Discussions][sibling-discussions] ![badge-github-release][badge-github-release] ![badge-github-release-date][badge-github-release-date] @@ -18,178 +18,80 @@ Version: G3v3 ![badge-github-commits][badge-github-commits] ![badge-github-last-commit][badge-github-last-commit] - - - *** - [Headless Debian/Xfce containers with VNC/noVNC for programming](#headless-debianxfce-containers-with-vncnovnc-for-programming) - [Project `accetto/headless-coding-g3`](#project-accettoheadless-coding-g3) - - [Introduction](#introduction) - - [TL;DR](#tldr) - - [Installing packages](#installing-packages) - - [Shared memory size](#shared-memory-size) - - [Extending images](#extending-images) + - [Introduction](#introduction) - [Building images](#building-images) - - [Sharing devices](#sharing-devices) - - [Project versions](#project-versions) - - [Issues, Wiki and Discussions](#issues-wiki-and-discussions) - - [Credits](#credits) - -## Introduction + - [Image generations](#image-generations) + - [Project versions](#project-versions) + - [Project goals](#project-goals) + - [Project features](#project-features) + - [Getting help](#getting-help) + - [Credits](#credits) -This repository contains resources for building Docker images based on [Debian 11][docker-debian] with [Xfce][xfce] desktop environment and [VNC][tigervnc]/[noVNC][novnc] servers for headless use and selected applications for programming. Adding more tools requires usually only a single or just a few commands. The instructions are in the provided README files and some simple test applications are also already included. +### Introduction -**Remark**: The resources for the previous versions of the images (based on [Ubuntu 20.04 LTS][docker-ubuntu] till G3v2) are still available in this repository as the branches `archived-generation-g3v2-ubuntu` and `archived-generation-g3v1`. +This GitHub repository contains resources and tools for building Docker images for headless working. -All images can optionally include also the [Chromium][chromium] or [Firefox][firefox] web browsers. +The images are based on [Debian 11][docker-debian] and include [Xfce][xfce] desktop, [TigerVNC][tigervnc] server and [noVNC][novnc] client. +The popular web browsers [Chromium][chromium] and [Firefox][firefox] are also included. -The resources for the individual images and their variations (tags) are stored in the subfolders of the **master** branch. Each image has its own README file describing its features and usage. - -This is a sibling project to the project [accetto/debian-vnc-xfce-g3][accetto-github-debian-vnc-xfce-g3]. +This [User guide][this-user-guide] describes the images and how to use them. -Another sibling project [accetto/ubuntu-vnc-xfce-g3][accetto-github-ubuntu-vnc-xfce-g3] contains the detailed description of the third generation (G3) of my Docker images. Please check the [sibling project README][sibling-readme] and the [sibling Wiki][sibling-wiki] for common information. +The content of this GitHub project is intended for developers and image builders. -## TL;DR - -There are currently resources for the following Docker images: +Ordinary users can simply use the images available in the following repositories on Docker Hub: - [accetto/debian-vnc-xfce-nodejs-g3][accetto-docker-debian-vnc-xfce-nodejs-g3] - - [full Readme][this-readme-image-nodejs] - - [Dockerfile][this-dockerfile-nodejs] - - [Dockerfile stages diagram][this-diagram-dockerfile-stages-nodejs] - [accetto/debian-vnc-xfce-postman-g3][accetto-docker-debian-vnc-xfce-postman-g3] - - [full Readme][this-readme-image-postman] - - [Dockerfile][this-dockerfile-postman] - - [Dockerfile stages diagram][this-diagram-dockerfile-stages-postman] - [accetto/debian-vnc-xfce-python-g3][accetto-docker-debian-vnc-xfce-python-g3] - - [full Readme][this-readme-image-python] - - [Dockerfile][this-dockerfile-python] - - [Dockerfile stages diagram][this-diagram-dockerfile-stages-python] - - [Dockerfile][this-dockerfile-python-bonus-gui-frameworks] for bonus images with GUI frameworks (bonus branch) - - [Dockerfile stages diagram][this-diagram-dockerfile-stages-python-bonus] (bonus branch) - -### Installing packages - -I try to keep the images slim. Consequently you can encounter missing dependencies while adding more applications yourself. You can track the missing libraries on the [Debian Packages Search][debian-packages-search] page and install them subsequently. - -You can also try to fix it by executing the following (the default `sudo` password is **headless**): - -```shell -### apt cache needs to be updated only once -sudo apt-get update - -sudo apt --fix-broken install -``` - -### Shared memory size - -Note that some applications require larger shared memory than the default 64MB. Using 256MB usually solves crashes or strange behavior. - -You can check the current shared memory size by executing the following command inside the container: - -```shell -df -h /dev/shm -``` +- [accetto/debian-vnc-xfce-vscode-g3][accetto-docker-debian-vnc-xfce-vscode-g3] -The older sibling Wiki page [Firefox multi-process][that-wiki-firefox-multiprocess] describes several ways, how to increase the shared memory size. - -### Extending images - -The provided example file `Dockerfile.extend` shows how to use the images as the base for your own images. - -Your concrete `Dockerfile` may need more statements, but the concept should be clear. - -The compose file `example.yml` shows how to switch to another non-root user and how to set the VNC password and resolution. +This is a sibling project to the project [accetto/debian-vnc-xfce-g3][accetto-github-debian-vnc-xfce-g3]. ### Building images -The fastest way to build the images: - -```shell -### PWD = project root -### prepare and source the 'secrets.rc' file first (see 'example-secrets.rc') - -### examples of building and publishing the individual images -./builder.sh nodejs all -./builder.sh nodejs-chromium all -./builder.sh nodejs-vscode all -./builder.sh nodejs-vscode-chromium all -./builder.sh nodejs-vscode-firefox all -./builder.sh nodejs-current all -./builder.sh postman all -./builder.sh postman-chromium all -./builder.sh postman-firefox all -./builder.sh python all -./builder.sh python-chromium all -./builder.sh python-vscode all -./builder.sh python-vscode-chromium all -./builder.sh python-vscode-firefox all - -### or skipping the publishing to the Docker Hub -./builder.sh nodejs all-no-push - -### example of building and publishing a group of images -./ci-builder.sh all group nodejs-vscode-chromium postman-firefox python-vscode-chromium - -### or all the images at once -./ci-builder.sh all group complete - -### or skipping the publishing to the Docker Hub -./ci-builder.sh all-no-push group complete - -### or all images featuring Chromium or Firefox -./ci-builder.sh all group complete-chromium -./ci-builder.sh all group complete-firefox - -### or, for example, complete 'nodejs' or 'python' group -./ci-builder.sh all group complete-nodejs -./ci-builder.sh all group complete-python - -### and so on -``` +You can execute the individual hook scripts in the folder [/docker/hooks/][this-folder-docker-hooks]. +However, the provided utilities are more convenient. -You can still execute the individual hook scripts as before (see the folder `/docker/hooks/`). However, the provided utilities `builder.sh` and `ci-builder.sh` are more convenient. Before pushing the images to the **Docker Hub** you have to prepare and source the file `secrets.rc` (see `example-secrets.rc`). The script `builder.sh` builds the individual images. The script `ci-builder.sh` can build various groups of images or all of them at once. Check the [builder-utility-readme][this-builder-readme], [local-building-example][this-readme-local-building-example] and [sibling Wiki][sibling-wiki] for more information. +The script [builder.sh][this-readme-builder] builds individual images. +The script [ci-builder.sh][this-readme-ci-builder] can build various groups of images or all of them at once. -### Sharing devices +Before building the images you have to prepare and source the file `secrets.rc` (see [example-secrets.rc][this-example-secrets-file]). -Sharing the audio device for video with sound works only with `Chromium` and only on Linux: +Features that are enabled by default can be explicitly disabled via environment variables. +This allows building even smaller images by excluding the individual features (e.g. noVNC). -```shell -docker run -it -P --rm \ - --device /dev/snd:/dev/snd:rw \ - --group-add audio \ -accetto/debian-vnc-xfce-python-g3:chromium -``` +The resources for building the individual images and their variations (tags) are in the subfolders of the [/docker/][this-folder-docker] folder. -Sharing the display with the host works only on Linux: +The individual README files contain quick examples of building the images: -```shell -xhost +local:$(whoami) +- [accetto/debian-vnc-xfce-nodejs-g3][this-readme-debian-vnc-xfce-nodejs-g3] +- [accetto/debian-vnc-xfce-postman-g3][this-readme-debian-vnc-xfce-postman-g3] +- [accetto/debian-vnc-xfce-python-g3][this-readme-debian-vnc-xfce-python-g3] +- [accetto/debian-vnc-xfce-vscode-g3][this-readme-debian-vnc-xfce-vscode-g3] -docker run -it -P --rm \ - -e DISPLAY=${DISPLAY} \ - --device /dev/dri/card0 \ - -v /tmp/.X11-unix:/tmp/.X11-unix:rw \ - accetto/debian-vnc-xfce-python-g3:latest --skip-vnc +Each image also has a separate README file intended for Docker Hub. +The final files should be generated by the utility [util-readme.sh][this-readme-util-readme-examples] and then copied to Docker Hub manually. -xhost -local:$(whoami) -``` +The following resources describe the image building subject in details: -Sharing the X11 socket with the host works only on Linux: +- [readme-local-building-example.md][this-readme-local-building-example] +- [readme-builder.md][this-readme-builder] +- [readme-ci-builder.md][this-readme-ci-builder] +- [readme-g3-cache.md][this-readme-g3-cache] +- [readme-util-readme-examples.md][this-readme-util-readme-examples] +- [sibling Wiki][sibling-wiki] -```shell -xhost +local:$(whoami) +### Image generations -docker run -it -P --rm \ - --device /dev/dri/card0 \ - -v /tmp/.X11-unix:/tmp/.X11-unix:rw \ - accetto/debian-vnc-xfce-python-g3:latest +This is the **third generation** (G3) of my headless images. +The **second generation** (G2) contains the GitHub repository [accetto/xubuntu-vnc-novnc][accetto-github-xubuntu-vnc-novnc]. +The **first generation** (G1) contains the GitHub repository [accetto/ubuntu-vnc-xfce][accetto-github-ubuntu-vnc-xfce]. -xhost -local:$(whoami) -``` - -## Project versions +### Project versions This file describes the **third version** (G3v3) of the project, which however corresponds to the **fourth version** (G3v4) of the **sibling project** [accetto/ubuntu-vnc-xfce-g3][accetto-github-ubuntu-vnc-xfce-g3]. @@ -202,7 +104,9 @@ The version `G3v3` brings the following major changes comparing to the previous - The `user name`, the `group name` and the `initial sudo password` can be overridden during the build time. - The permissions of the files `/etc/passwd` and `/etc/groups` are set to the standard `644` after creating the user. - The content of the home folder and the startup folder belongs to the created user. -- The created user gets permissions to use `sudo`. The initial `sudo` password is configurable during the build time using the build argument `ARG_SUDO_INITIAL_PW`. The password can be changed inside the container. +- The created user gets permissions to use `sudo`. +The initial `sudo` password is configurable during the build time using the build argument `ARG_SUDO_INITIAL_PW`. +The password can be changed inside the container. - The default `id:gid` has been changed from `1001:0` to `1000:1000`. - Features `NOVNC` and `FIREFOX_PLUS`, that are enabled by default, can be disabled via environment variables. - If `FEATURES_NOVNC="0"`, then @@ -218,79 +122,99 @@ The version `G3v2` has brought the following major changes comparing to the prev - Significantly improved building performance by introducing a local cache (`g3-cache`). - Auto-building on the **Docker Hub** and using of the **GitHub Actions** have been abandoned. - The enhanced building pipeline moves towards building the images outside the **Docker Hub** and aims to support also stages with CI/CD capabilities (e.g. the **GitLab**). -- The **local stage** is the default building stage now. However, the new building pipeline has already been tested also with a local **GitLab** installation in a Docker container on a Linux machine. -- Automatic publishing of README files to the **Docker Hub** has been removed, because it was not working properly any more. However, the README files for the **Docker Hub** can still be prepared with the provided utility `util-readme.sh` and then copy-and-pasted to the **Docker Hub** manually. +- The **local stage** is the default building stage now. +However, the new building pipeline has already been tested also with a local **GitLab** installation in a Docker container on a Linux machine. +- Automatic publishing of README files to the **Docker Hub** has been removed, because it was not working properly any more. +However, the README files for the **Docker Hub** can still be prepared with the provided utility `util-readme.sh` and then copy-and-pasted to the **Docker Hub** manually. + +The changes affect only the building pipeline, not the Docker images themselves. +The `Dockerfile`, apart from using the new local `g3-cache`, stays conceptually unchanged. + +Please refer to the [sibling project][accetto-github-ubuntu-vnc-xfce-g3_project-versions] to learn more about the older project versions. + +### Project goals -The changes affect only the building pipeline, not the Docker images themselves. The `Dockerfile`, apart from using the new local `g3-cache`, stays conceptually unchanged. +Please refer to the [sibling project][accetto-github-ubuntu-vnc-xfce-g3_project-goals] to learn more about the project goals. -You can learn more about the project generations in the [sibling project README][sibling-readme] and the [sibling Wiki][sibling-wiki]. +### Project features -## Issues, Wiki and Discussions +Please refer to the [sibling project][accetto-github-ubuntu-vnc-xfce-g3_project-features] to learn more about the project features. -If you have found a problem or you just have a question, please check the [Issues][this-issues], the [sibling Issues][sibling-issues] and the [sibling Wiki][sibling-wiki] first. Please do not overlook the closed issues. +### Getting help -If you do not find a solution, you can file a new issue. The better you describe the problem, the bigger the chance it'll be solved soon. +If you have found a problem or you just have a question, please check the [User guide][this-user-guide], [Issues][this-issues] and the [sibling Wiki][sibling-wiki] first. +Please do not overlook the closed issues. + +If you do not find a solution, you can file a new issue. +The better you describe the problem, the bigger the chance it'll be solved soon. If you have a question or an idea and you don't want to open an issue, you can use the [sibling Discussions][sibling-discussions]. -## Credits +### Credits Credit goes to all the countless people and companies, who contribute to open source community and make so many dreamy things real. *** - +[this-user-guide]: https://accetto.github.io/user-guide-g3/ [this-docker]: https://hub.docker.com/u/accetto/ [this-changelog]: https://github.com/accetto/headless-coding-g3/blob/master/CHANGELOG.md + [this-issues]: https://github.com/accetto/headless-coding-g3/issues -[this-dockerfile-nodejs]: https://github.com/accetto/headless-coding-g3/blob/master/docker/Dockerfile.xfce.nodejs -[this-readme-image-nodejs]: https://github.com/accetto/headless-coding-g3/blob/master/docker/xfce-nodejs/README.md +[this-folder-docker]: https://github.com/accetto/headless-coding-g3/tree/master/docker + +[this-folder-docker-hooks]: https://github.com/accetto/headless-coding-g3/tree/master/docker/hooks + +[this-example-secrets-file]: https://github.com/accetto/headless-coding-g3/blob/master/examples/example-secrets.rc + +[this-readme-debian-vnc-xfce-nodejs-g3]: https://github.com/accetto/headless-coding-g3/blob/master/docker/xfce-nodejs/README.md + +[this-readme-debian-vnc-xfce-postman-g3]: https://github.com/accetto/headless-coding-g3/blob/master/docker/xfce-postman/README.md + +[this-readme-debian-vnc-xfce-python-g3]: https://github.com/accetto/headless-coding-g3/blob/master/docker/xfce-python/README.md + +[this-readme-debian-vnc-xfce-vscode-g3]: https://github.com/accetto/headless-coding-g3/blob/master/docker/xfce-vscode/README.md + +[this-readme-builder]: https://github.com/accetto/headless-coding-g3/blob/master/readme-builder.md + +[this-readme-ci-builder]: https://github.com/accetto/headless-coding-g3/blob/master/readme-ci-builder.md -[this-dockerfile-postman]: https://github.com/accetto/headless-coding-g3/blob/master/docker/Dockerfile.xfce.postman -[this-readme-image-postman]: https://github.com/accetto/headless-coding-g3/blob/master/docker/xfce-postman/README.md +[this-readme-g3-cache]: https://github.com/accetto/headless-coding-g3/blob/master/readme-g3-cache.md -[this-dockerfile-python]: https://github.com/accetto/headless-coding-g3/blob/master/docker/Dockerfile.xfce.python -[this-dockerfile-python-bonus-gui-frameworks]: https://github.com/accetto/headless-coding-g3/blob/bonus-images-python-gui-frameworks/docker/Dockerfile.xfce.python -[this-readme-image-python]: https://github.com/accetto/headless-coding-g3/blob/master/docker/xfce-python/README.md +[this-readme-util-readme-examples]: https://github.com/accetto/headless-coding-g3/blob/master/utils/readme-util-readme-examples.md [accetto-docker-debian-vnc-xfce-nodejs-g3]: https://hub.docker.com/r/accetto/debian-vnc-xfce-nodejs-g3 -[accetto-docker-debian-vnc-xfce-postman-g3]: https://hub.docker.com/r/accetto/debian-vnc-xfce-postman-g3 -[accetto-docker-debian-vnc-xfce-python-g3]: https://hub.docker.com/r/accetto/debian-vnc-xfce-python-g3 -[this-builder-readme]: https://github.com/accetto/headless-coding-g3/blob/master/readme-builder.md -[this-readme-local-building-example]: https://github.com/accetto/headless-coding-g3/blob/master/readme-local-building-example.md +[accetto-docker-debian-vnc-xfce-postman-g3]: https://hub.docker.com/r/accetto/debian-vnc-xfce-postman-g3 - +[accetto-docker-debian-vnc-xfce-python-g3]: https://hub.docker.com/r/accetto/debian-vnc-xfce-python-g3 - -[this-diagram-dockerfile-stages-nodejs]: https://raw.githubusercontent.com/accetto/headless-coding-g3/master/docker/doc/images/Dockerfile.xfce.nodejs.png -[this-diagram-dockerfile-stages-python]: https://raw.githubusercontent.com/accetto/headless-coding-g3/master/docker/doc/images/Dockerfile.xfce.python.png -[this-diagram-dockerfile-stages-python-bonus]: https://raw.githubusercontent.com/accetto/headless-coding-g3/master/docker/doc/images/Dockerfile.xfce.python-bonus.png -[this-diagram-dockerfile-stages-postman]: https://raw.githubusercontent.com/accetto/headless-coding-g3/master/docker/doc/images/Dockerfile.xfce.postman.png +[accetto-docker-debian-vnc-xfce-vscode-g3]: https://hub.docker.com/r/accetto/debian-vnc-xfce-vscode-g3 - +[this-readme-local-building-example]: https://github.com/accetto/headless-coding-g3/blob/master/readme-local-building-example.md [accetto-github-debian-vnc-xfce-g3]: https://github.com/accetto/debian-vnc-xfce-g3 [accetto-github-ubuntu-vnc-xfce-g3]: https://github.com/accetto/ubuntu-vnc-xfce-g3/ -[sibling-discussions]: https://github.com/accetto/ubuntu-vnc-xfce-g3/discussions -[sibling-issues]: https://github.com/accetto/ubuntu-vnc-xfce-g3/issues -[sibling-readme]: https://github.com/accetto/ubuntu-vnc-xfce-g3/blob/master/README.md [sibling-wiki]: https://github.com/accetto/ubuntu-vnc-xfce-g3/wiki - +[sibling-discussions]: https://github.com/accetto/ubuntu-vnc-xfce-g3/discussions + +[accetto-github-ubuntu-vnc-xfce-g3_project-versions]: https://github.com/accetto/ubuntu-vnc-xfce-g3#project-versions + +[accetto-github-ubuntu-vnc-xfce-g3_project-goals]: https://github.com/accetto/ubuntu-vnc-xfce-g3#project-goals + +[accetto-github-ubuntu-vnc-xfce-g3_project-features]: https://github.com/accetto/ubuntu-vnc-xfce-g3#changes-and-new-features -[that-wiki-firefox-multiprocess]: https://github.com/accetto/xubuntu-vnc/wiki/Firefox-multiprocess +[accetto-github-xubuntu-vnc-novnc]: https://github.com/accetto/xubuntu-vnc-novnc/ - +[accetto-github-ubuntu-vnc-xfce]: https://github.com/accetto/ubuntu-vnc-xfce [docker-debian]: https://hub.docker.com/_/debian/ -[docker-ubuntu]: https://hub.docker.com/_/ubuntu/ -[debian-packages-search]: https://packages.debian.org/index [chromium]: https://www.chromium.org/Home [firefox]: https://www.mozilla.org @@ -298,12 +222,6 @@ Credit goes to all the countless people and companies, who contribute to open so [tigervnc]: http://tigervnc.org [xfce]: http://www.xfce.org - - - - - - [badge-github-release]: https://badgen.net/github/release/accetto/headless-coding-g3?icon=github&label=release [badge-github-release-date]: https://img.shields.io/github/release-date/accetto/headless-coding-g3?logo=github diff --git a/ci-builder.sh b/ci-builder.sh index de72847..ad3b19a 100644 --- a/ci-builder.sh +++ b/ci-builder.sh @@ -256,6 +256,7 @@ main() { help | --help | -h ) show_unlogged_help + return 0 ;; log ) diff --git a/docker/README.md b/docker/README.md index d74b9b2..6570f33 100644 --- a/docker/README.md +++ b/docker/README.md @@ -6,28 +6,31 @@ Useful links from **this project's** GitHub repository [accetto/headless-coding- - project [Readme][this-readme], [Changelog][this-changelog], [Issues][this-issues], [sibling Wiki][sibling-wiki] and [sibling Discussions][sibling-discussions] - images with **Node.js** - - [full Readme][this-readme-image-nodejs] file on GitHub + - [Readme][this-readme-image-nodejs] file on GitHub - [image repository][this-dockerhub-image-nodejs] on Docker Hub - [Dockerfile][this-dockerfile-nodejs] on GitHub - [Dockerfile stages diagram][this-diagram-dockerfile-stages-nodejs] on GitHub - images with **Postman** - - [full Readme][this-readme-image-postman] file on GitHub + - [Readme][this-readme-image-postman] file on GitHub - [image repository][this-dockerhub-image-postman] on Docker Hub - [Dockerfile][this-dockerfile-postman] on GitHub - [Dockerfile stages diagram][this-diagram-dockerfile-stages-postman] on GitHub - images with **Python** - - [full Readme][this-readme-image-python] file on GitHub + - [Readme][this-readme-image-python] file on GitHub - [image repository][this-dockerhub-image-python] on Docker Hub - [Dockerfile][this-dockerfile-python] on GitHub - [Dockerfile stages diagram][this-diagram-dockerfile-stages-python] on GitHub - bonus images with **Python** and GUI frameworks - [Dockerfile][this-dockerfile-python-bonus-gui-frameworks] on GitHub (branch `bonus-images-python-gui-frameworks`) - [Dockerfile stages diagram][this-diagram-dockerfile-stages-python-bonus] (bonus branch) on GitHub +- images with **Visual Studio Code** + - [Readme][this-readme-image-vscode] file on GitHub + - [image repository][this-dockerhub-image-vscode] on Docker Hub + - [Dockerfile][this-dockerfile-vscode] on GitHub + - [Dockerfile stages diagram][this-diagram-dockerfile-stages-vscode] on GitHub *** - - [this-changelog]: https://github.com/accetto/headless-coding-g3/blob/master/CHANGELOG.md [this-home]: https://github.com/accetto/headless-coding-g3 [this-issues]: https://github.com/accetto/headless-coding-g3/issues @@ -46,14 +49,15 @@ Useful links from **this project's** GitHub repository [accetto/headless-coding- [this-readme-image-python]: https://github.com/accetto/headless-coding-g3/blob/master/docker/xfce-python/README.md [this-dockerhub-image-python]: https://hub.docker.com/r/accetto/debian-vnc-xfce-python-g3 - +[this-dockerfile-vscode]: https://github.com/accetto/headless-coding-g3/blob/master/docker/Dockerfile.xfce.vscode +[this-readme-image-vscode]: https://github.com/accetto/headless-coding-g3/blob/master/docker/xfce-vscode/README.md +[this-dockerhub-image-vscode]: https://hub.docker.com/r/accetto/debian-vnc-xfce-vscode-g3 [this-diagram-dockerfile-stages-nodejs]: https://raw.githubusercontent.com/accetto/headless-coding-g3/master/docker/doc/images/Dockerfile.xfce.nodejs.png +[this-diagram-dockerfile-stages-postman]: https://raw.githubusercontent.com/accetto/headless-coding-g3/master/docker/doc/images/Dockerfile.xfce.postman.png [this-diagram-dockerfile-stages-python]: https://raw.githubusercontent.com/accetto/headless-coding-g3/master/docker/doc/images/Dockerfile.xfce.python.png [this-diagram-dockerfile-stages-python-bonus]: https://raw.githubusercontent.com/accetto/headless-coding-g3/master/docker/doc/images/Dockerfile.xfce.python-bonus.png -[this-diagram-dockerfile-stages-postman]: https://raw.githubusercontent.com/accetto/headless-coding-g3/master/docker/doc/images/Dockerfile.xfce.postman.png - - +[this-diagram-dockerfile-stages-vscode]: https://raw.githubusercontent.com/accetto/headless-coding-g3/master/docker/doc/images/Dockerfile.xfce.vscode.png [sibling-wiki]: https://github.com/accetto/ubuntu-vnc-xfce-g3/wiki [sibling-discussions]: https://github.com/accetto/ubuntu-vnc-xfce-g3/discussions diff --git a/docker/doc/images/animation-headless-coding-nodejs-live.gif b/docker/doc/images/animation-headless-coding-nodejs-live.gif new file mode 100644 index 0000000..9e28dba Binary files /dev/null and b/docker/doc/images/animation-headless-coding-nodejs-live.gif differ diff --git a/docker/doc/images/animation-headless-coding-postman-live.gif b/docker/doc/images/animation-headless-coding-postman-live.gif new file mode 100644 index 0000000..d25203c Binary files /dev/null and b/docker/doc/images/animation-headless-coding-postman-live.gif differ diff --git a/docker/doc/images/animation-headless-coding-python-live.gif b/docker/doc/images/animation-headless-coding-python-live.gif new file mode 100644 index 0000000..76c9438 Binary files /dev/null and b/docker/doc/images/animation-headless-coding-python-live.gif differ diff --git a/docker/doc/images/animation-headless-coding-vscode-live.gif b/docker/doc/images/animation-headless-coding-vscode-live.gif new file mode 100644 index 0000000..8d04e1e Binary files /dev/null and b/docker/doc/images/animation-headless-coding-vscode-live.gif differ diff --git a/docker/doc/images/debian-vnc-xfce-nodejs.jpg b/docker/doc/images/debian-vnc-xfce-nodejs.jpg deleted file mode 100644 index 52b5eab..0000000 Binary files a/docker/doc/images/debian-vnc-xfce-nodejs.jpg and /dev/null differ diff --git a/docker/doc/images/debian-vnc-xfce-postman.jpg b/docker/doc/images/debian-vnc-xfce-postman.jpg deleted file mode 100644 index c6c7e42..0000000 Binary files a/docker/doc/images/debian-vnc-xfce-postman.jpg and /dev/null differ diff --git a/docker/doc/images/debian-vnc-xfce-python.jpg b/docker/doc/images/debian-vnc-xfce-python.jpg deleted file mode 100644 index ca43592..0000000 Binary files a/docker/doc/images/debian-vnc-xfce-python.jpg and /dev/null differ diff --git a/docker/doc/images/debian-vnc-xfce-vscode.jpg b/docker/doc/images/debian-vnc-xfce-vscode.jpg deleted file mode 100644 index 219f908..0000000 Binary files a/docker/doc/images/debian-vnc-xfce-vscode.jpg and /dev/null differ diff --git a/docker/xfce-chromium/src/home/readme-chromium.md b/docker/xfce-chromium/src/home/readme-chromium.md index 1db4ec3..50bfeb1 100644 --- a/docker/xfce-chromium/src/home/readme-chromium.md +++ b/docker/xfce-chromium/src/home/readme-chromium.md @@ -1,3 +1,5 @@ # Readme `Chromium` -Note that `Chromium Browser` in this container runs in `--no-sandbox` mode. You should be aware of the implications. The browser is intended for testing and development. +Note that `Chromium Browser` in this container runs in `--no-sandbox` mode. +You should be aware of the implications. +The browser is intended for testing and development. diff --git a/docker/xfce-nodejs/README-dockerhub.md b/docker/xfce-nodejs/README-dockerhub.md index 47c92d9..68f1749 100644 --- a/docker/xfce-nodejs/README-dockerhub.md +++ b/docker/xfce-nodejs/README-dockerhub.md @@ -2,255 +2,32 @@ ## accetto/debian-vnc-xfce-nodejs-g3 -[Docker Hub][this-docker] - [Git Hub][this-github] - [Dockerfile][this-dockerfile] - [Full Readme][this-readme-full] - [Changelog][this-changelog] - [Project Readme][this-readme-project] +[User Guide][this-user-guide] - [GitHub][this-github] - [Dockerfile][this-dockerfile] - [Readme][this-readme-full] - [Changelog][this-changelog] ![badge-docker-pulls][badge-docker-pulls] ![badge-docker-stars][badge-docker-stars] ![badge-github-release][badge-github-release] -![badge-github-release-date][badge-github-release-date] - -![badge_latest_created][badge_latest_created] -[![badge_latest_version-sticker][badge_latest_version-sticker]][link_latest_version-sticker-verbose] - -*** - -- [Headless Debian/Xfce container with VNC/noVNC for `Node.js` development](#headless-debianxfce-container-with-vncnovnc-for-nodejs-development) - - [accetto/debian-vnc-xfce-nodejs-g3](#accettodebian-vnc-xfce-nodejs-g3) - - [Introduction](#introduction) - - [TL;DR](#tldr) - - [Installing packages](#installing-packages) - - [Shared memory size](#shared-memory-size) - - [Extending images](#extending-images) - - [Building images](#building-images) - - [Sharing devices](#sharing-devices) - - [Other examples](#other-examples) - - [Description](#description) - - [Image tags](#image-tags) - - [Ports](#ports) - - [Volumes](#volumes) - - [Using headless containers](#using-headless-containers) - - [Overriding VNC/noVNC parameters](#overriding-vncnovnc-parameters) - - [Startup options and help](#startup-options-and-help) - - [More information](#more-information) - - [Issues, Wiki and Discussions](#issues-wiki-and-discussions) - - [Credits](#credits) *** -### Introduction - -This repository contains resources for building Docker images based on [Debian 11][docker-debian] with [Xfce][xfce] desktop environment, [VNC][tigervnc]/[noVNC][novnc] servers for headless use, the JavaScript-based platform [Node.js][nodejs] with [npm][npm] and optionally other tools for programming (e.g. [Visual Studio Code][vscode]). - -All images can optionally include also the [Chromium][chromium] or [Firefox][firefox] web browsers. - -Adding more tools like [TypeScript][typescript], [Angular][angular] or [Electron][electron] usually requires only a single or just a few commands. The instructions are in the provided README files and some simple test applications are also already included. - -This is the **short README** version for the **Docker Hub**. There is also the [full-length README][this-readme-full] on the **GitHub**. - -### TL;DR - -#### Installing packages - -I try to keep the images slim. Consequently you can encounter missing dependencies while adding more applications yourself. You can track the missing libraries on the [Debian Packages Search][debian-packages-search] page and install them subsequently. - -You can also try to fix it by executing the following (the default `sudo` password is **headless**): - -```shell -### apt cache needs to be updated only once -sudo apt-get update - -sudo apt --fix-broken install -``` - -#### Shared memory size - -Note that some applications require larger shared memory than the default 64MB. Using 256MB usually solves crashes or strange behavior. - -You can check the current shared memory size by executing the following command inside the container: - -```shell -df -h /dev/shm -``` - -The older sibling Wiki page [Firefox multi-process][that-wiki-firefox-multiprocess] describes several ways, how to increase the shared memory size. - -#### Extending images - -The provided example file `Dockerfile.extend` shows how to use the images as the base for your own images. - -Your concrete `Dockerfile` may need more statements, but the concept should be clear. - -The compose file `example.yml` shows how to switch to another non-root user and how to set the VNC password and resolution. - -#### Building images - -The fastest way to build the images: - -```shell -### PWD = project root -### prepare and source the 'secrets.rc' file first (see 'example-secrets.rc') - -### examples of building and publishing the individual images -./builder.sh nodejs all -./builder.sh nodejs-chromium all -./builder.sh nodejs-vscode all -./builder.sh nodejs-vscode-chromium all -./builder.sh nodejs-vscode-firefox all -./builder.sh nodejs-current all - -### just building the image, skipping the publishing and the version sticker update -./builder.sh nodejs build - -### examples of building and publishing the images as a group -./ci-builder.sh all group nodejs nodejs-current nodejs-vscode-chromium - -### or all the images featuring Node.js -./ci-builder.sh all group complete-nodejs -``` - -You can still execute the individual hook scripts as before (see the folder `/docker/hooks/`). However, the provided utilities `builder.sh` and `ci-builder.sh` are more convenient. Before pushing the images to the **Docker Hub** you have to prepare and source the file `secrets.rc` (see `example-secrets.rc`). The script `builder.sh` builds the individual images. The script `ci-builder.sh` can build various groups of images or all of them at once. Check the [builder-utility-readme][this-builder-readme], [local-building-example][this-readme-local-building-example] and [sibling Wiki][sibling-wiki] for more information. - -Note that selected features that are enabled by default can be explicitly disabled via environment variables. This allows to build even smaller images by excluding, for example, `noVNC`. See the [local-building-example][this-readme-local-building-example] for more information. - -#### Sharing devices - -Sharing the audio device for video with sound works only with `Chromium` and only on Linux: - -```shell -docker run -it -P --rm \ - --device /dev/snd:/dev/snd:rw \ - --group-add audio \ -accetto/debian-vnc-xfce-nodejs-g3:chromium -``` - -Sharing the display with the host works only on Linux: - -```shell -xhost +local:$(whoami) - -docker run -it -P --rm \ - -e DISPLAY=${DISPLAY} \ - --device /dev/dri/card0 \ - -v /tmp/.X11-unix:/tmp/.X11-unix:rw \ - accetto/debian-vnc-xfce-nodejs-g3:latest --skip-vnc - -xhost -local:$(whoami) -``` - -Sharing the X11 socket with the host works only on Linux: - -```shell -xhost +local:$(whoami) - -docker run -it -P --rm \ - --device /dev/dri/card0 \ - -v /tmp/.X11-unix:/tmp/.X11-unix:rw \ - accetto/debian-vnc-xfce-nodejs-g3:latest - -xhost -local:$(whoami) -``` - -#### Other examples - -Making [Visual Studio Code][vscode] settings and extensions persistent: - -```shell -### bind these container folders to external volumes -/home/headless/.config/Code -/home/headless/.vscode/ - -### Tip: Keep keyboard shortcuts consistent by setting the keyboard layout -### before starting the Visual Studio Code. -``` - -Updating [npm][npm]: - -```shell -### globally -npm install -g npm - -### checking the versions -node -v -npm -v -npx -v -``` - -Installing [TypeScript][typescript]: - -```shell -### globally -npm install -g typescript - -### checking the version -tsc --version -``` - -Installing [Angular][angular]: - -```shell -### globally -npm install -g @angular/cli - -### checking the version -ng --version -``` - -Installing [Electron][electron]: - -```shell -### local installation inside a project works usually better -npm install --save-dev electron +This Docker Hub repository contains Docker images for headless working with the free open-source JavaScript runtime environment [Node.js][nodejs] and its package installer [npm][npm]. -### apps need to be started with '--no-sandbox' option -electron-test-app --no-sandbox %U -``` +The images are based on [Debian 11][docker-debian] and include [Xfce][xfce] desktop, [TigerVNC][tigervnc] server and [noVNC][novnc] client. -### Description +The free open-source programming editor [Visual Studio Code][vscode] and the popular web browsers [Chromium][chromium] or [Firefox][firefox] are also included. -This is the **third generation** (G3) of my headless images. The **second generation** (G2) contains the GitHub repository [accetto/xubuntu-vnc-novnc][accetto-github-xubuntu-vnc-novnc]. The **first generation** (G1) contains the GitHub repository [accetto/ubuntu-vnc-xfce][accetto-github-ubuntu-vnc-xfce]. +Adding more tools like [TypeScript][typescript], [Angular][angular] or [Electron][electron] usually requires only a single or just a few commands. +The instructions are in the provided README files and some simple test applications are also already included. -More information about the image generations can be found in the [sibling project README][sibling-readme-project] file and the [sibling Wiki][sibling-wiki]. +This [User guide][this-user-guide] describes the images and how to use them. -**Attention:** If you will build an image containing the [Chromium Browser][chromium], then the browser will run in the `--no-sandbox` mode. You should be aware of the implications. The image is intended for testing and development. +The related [GitHub project][this-github] contains image generators that image users generally don’t need, unless they want to build the images themselves. -**Attention:** If you will build an image containing the [Firefox][firefox] browser, then the browser will run in the `multi-process` mode. Be aware, that this mode requires larger shared memory (`/dev/shm`). At least 256MB is recommended. Please check the **Firefox multi-process** page in this older [sibling Wiki][that-wiki-firefox-multiprocess] for more information and the instructions, how to set the shared memory size in different scenarios. +### Tags -The main features and components of the images in the default configuration are: - -- utilities **ping**, **wget**, **sudo** [curl][curl], [git][git] (Debian distribution) -- current version of JSON processor [jq][jq] -- light-weight [Xfce][xfce] desktop environment (DEbian distribution) -- current version of high-performance [TigerVNC][tigervnc] server and client -- current version of [noVNC][novnc] HTML5 clients (full and lite) (TCP port **6901**) -- popular text editor [nano][nano] (Debian distribution) -- lite but advanced graphical editor [mousepad][mousepad] (Debian distribution) -- current version of [tini][tini] as the entry-point initial process (PID 1) -- support for overriding both the container user account and its group -- support of **version sticker** (see the [full-length README][this-readme-full] on the **GitHub**) -- optionally the current version of [Chromium Browser][chromium] open-source web browser (Debian distribution) -- optionally the current version of [Firefox ESR (Extended Support Release)][firefox] web browser and optionally also some additional **plus features** described in the [sibling project README][sibling-readme-xfce-firefox] - -All images include the `LTS` or the `current` version of [Node.js][nodejs] with [npm][npm] and optionally also the current version of the free open-source developer editor [Visual Studio Code][vscode]. - -The history of notable changes is documented in the [CHANGELOG][this-changelog]. - -![container-screenshot][this-screenshot-container] - -### Image tags - -The included resources allow building of almost any combination of the following selectable features: - -- **VNC** server with optional **noVNC** access -- **LTS** or **current** version of **Node.js** -- optional **Visual Studio Code** editor -- optional **Chromium** or **Firefox** browser with optional **plus features** (described in the [sibling project README][sibling-readme-xfce-firefox]) -- optional **screenshooting** and **thumbnailing** support +The following image tags are regularly built and published on Docker Hub: -There are also other, more subtle, optional features. Check the hook script `env.rc` if you are interested about them. - -You can build all possible variations of the images locally, but it would not be reasonable to publish all of them on the **Docker Hub**. - -Therefore only the following image tags will be regularly built and published on the **Docker Hub** (with [Node.js][nodejs] `LTS` by default): + - `latest` implements VNC and noVNC @@ -272,7 +49,7 @@ Therefore only the following image tags will be regularly built and published on ![badge_vscode-chromium_created][badge_vscode-chromium_created] [![badge_vscode-chromium_version-sticker][badge_vscode-chromium_version-sticker]][link_vscode-chromium_version-sticker-verbose] -- `vscode-firefox` adds [Visual Studio Code][vscode] and [Firefox][firefox] with **plus features** +- `vscode-firefox` adds [Visual Studio Code][vscode] and [Firefox][firefox] ![badge_vscode-firefox_created][badge_vscode-firefox_created] [![badge_vscode-firefox_version-sticker][badge_vscode-firefox_version-sticker]][link_vscode-firefox_version-sticker-verbose] @@ -282,125 +59,85 @@ Therefore only the following image tags will be regularly built and published on ![badge_current_created][badge_current_created] [![badge_current_version-sticker][badge_current_version-sticker]][link_current_version-sticker-verbose] -Clicking on the version sticker badge in the [README on Docker Hub][this-readme-dockerhub] reveals more information about the actual configuration of the image. - -### Ports - -Following **TCP** ports are exposed by default: - -- **5901** is used for access over **VNC** -- **6901** is used for access over [noVNC][novnc] -- **3000** is used by the [Node.js][nodejs] server - -The VNC/noVNC default ports and also some other parameters can be overridden several ways as it is described in the [sibling image README file][sibling-readme-xfce]. - -The [Node.js][nodejs] server default port can be overridden at the **image build-time** by the build argument `ARG_NODEJS_PORT` or at the **container startup-time** by the environment variable `NODEJS_PORT`. - -### Volumes - -The containers do not create or use any external volumes by default. - -Both **named volumes** and **bind mounts** can be used. More about volumes can be found in [Docker documentation][docker-doc] (e.g. [Manage data in Docker][docker-doc-managing-data]). - -However, the container's mounting point `/srv/projects/` is intended for sharing the projects between the container and the host computer: - -```shell -docker run -v /my_local_projects:/srv/projects ... - -### or using the newer syntax -docker run --mount source=/my_local_projects,target=/srv/projects ... -``` - -The container's directory `/srv/samples` already contains the following simple testing applications: + -- nodejs-test-app -- electron-test-app +**Hint:** Clicking the version sticker badge reveals more information about the particular build. -Note that they will be copied locally only if the local directory, you have mounted, has been empty. +### Features -**Tip** If you use an image containing [Visual Studio Code][vscode] and you want to make your settings and extensions persistent, then bind the following container folder to external volumes: - -```shell -/home/headless/.config/Code -/home/headless/.vscode/ -``` - -To keep the keyboard shortcuts consistent, change the keyboard layout to your preferred one before starting the [Visual Studio Code][vscode]. - -## Using headless containers +The main features and components of the images in the default configuration are: -More information about using headless containers can be found in the [full-length README][this-readme-full] file on GitHub. +- lightweight [Xfce][xfce] desktop environment (Debian distribution) +- [sudo][sudo] support +- utilities [curl][curl] and [git][git] (Debian distribution) +- current version of JSON processor [jq][jq] +- current version of high-performance [TigerVNC][tigervnc] server and client +- current version of [noVNC][novnc] HTML5 clients (full and lite) (TCP port **6901**) +- popular text editor [nano][nano] (Debian distribution) +- lite but advanced graphical editor [mousepad][mousepad] (Debian distribution) +- current version of [tini][tini] as the entry-point initial process (PID 1) +- support for overriding environment variables, VNC parameters, user and group (see [User guide][this-user-guide-using-containers]) +- support of **version sticker** (see [User guide][this-user-guide-version-sticker]) +- current version of [Chromium Browser][chromium] open-source web browser (Debian distribution) +- current version of [Firefox ESR (Extended Support Release)][firefox] web browser and also the additional **Firefox plus** feature (see [User guide][this-user-guide-firefox-plus]) +- current version of free open-source JavaScript runtime environment [Node.js][nodejs] with [npm][npm] (`LTS` or `current`) +- current version of free open-source programming editor [Visual Studio Code][vscode] -### Overriding VNC/noVNC parameters +The following **TCP** ports are exposed by default: -This image supports several ways of overriding the VNC/noVNV parameters. The [sibling image README file][sibling-readme-xfce] describes how to do it. +- **5901** for access over **VNC** (using VNC viewer) +- **6901** for access over [noVNC][novnc] (using web browser) -### Startup options and help +![container-screenshot][this-screenshot-container] -The startup options and help are also described in the [sibling image README file][sibling-readme-xfce]. +### Remarks -### More information +This is the **third generation** (G3) of my headless images. +The **second generation** (G2) contains the GitHub repository [accetto/xubuntu-vnc-novnc][accetto-github-xubuntu-vnc-novnc]. +The **first generation** (G1) contains the GitHub repository [accetto/ubuntu-vnc-xfce][accetto-github-ubuntu-vnc-xfce]. -More information about these images can be found in the [full-length README][this-readme-full] file on GitHub. +### Getting help -## Issues, Wiki and Discussions +If you've found a problem or you just have a question, please check the [User guide][this-user-guide], [Issues][this-issues] and [sibling Wiki][sibling-wiki] first. +Please do not overlook the closed issues. -If you have found a problem or you just have a question, please check the [Issues][this-issues], the [sibling Issues][sibling-issues] and the [sibling Wiki][sibling-wiki] first. Please do not overlook the closed issues. +If you do not find a solution, you can file a new issue. +The better you describe the problem, the bigger the chance it'll be solved soon. -If you do not find a solution, you can file a new issue. The better you describe the problem, the bigger the chance it'll be solved soon. +If you have a question or an idea and you don't want to open an issue, you can also use the [sibling Discussions][sibling-discussions]. -If you have a question or an idea and you don't want to open an issue, you can use the [sibling Discussions][sibling-discussions]. +*** -## Credits +[this-user-guide]: https://accetto.github.io/user-guide-g3/ -Credit goes to all the countless people and companies, who contribute to open source community and make so many dreamy things real. +[this-user-guide-version-sticker]: https://accetto.github.io/user-guide-g3/version-sticker/ -*** +[this-user-guide-using-containers]: https://accetto.github.io/user-guide-g3/using-containers/ - +[this-user-guide-firefox-plus]: https://accetto.github.io/user-guide-g3/firefox-plus/ [this-changelog]: https://github.com/accetto/headless-coding-g3/blob/master/CHANGELOG.md + [this-github]: https://github.com/accetto/headless-coding-g3/ -[this-issues]: https://github.com/accetto/headless-coding-g3/issues -[this-readme-dockerhub]: https://hub.docker.com/r/accetto/debian-vnc-xfce-nodejs-g3 -[this-readme-full]: https://github.com/accetto/headless-coding-g3/blob/master/docker/xfce-nodejs/README.md -[this-readme-project]: https://github.com/accetto/headless-coding-g3/blob/master/README.md -[this-builder-readme]: https://github.com/accetto/headless-coding-g3/blob/master/readme-builder.md -[this-readme-local-building-example]: https://github.com/accetto/headless-coding-g3/blob/master/readme-local-building-example.md +[this-issues]: https://github.com/accetto/headless-coding-g3/issues - +[this-readme-full]: https://github.com/accetto/headless-coding-g3/blob/master/docker/xfce-nodejs/README.md [sibling-discussions]: https://github.com/accetto/ubuntu-vnc-xfce-g3/discussions -[sibling-issues]: https://github.com/accetto/ubuntu-vnc-xfce-g3/issues -[sibling-readme-project]: https://github.com/accetto/ubuntu-vnc-xfce-g3/blob/master/README.md -[sibling-readme-xfce]: https://github.com/accetto/ubuntu-vnc-xfce-g3/blob/master/docker/xfce/README.md -[sibling-readme-xfce-firefox]: https://github.com/accetto/ubuntu-vnc-xfce-g3/blob/master/docker/xfce-firefox/README.md -[sibling-wiki]: https://github.com/accetto/ubuntu-vnc-xfce-g3/wiki - +[sibling-wiki]: https://github.com/accetto/ubuntu-vnc-xfce-g3/wiki -[this-docker]: https://hub.docker.com/r/accetto/debian-vnc-xfce-nodejs-g3/ [this-dockerfile]: https://github.com/accetto/headless-coding-g3/blob/master/docker/Dockerfile.xfce.nodejs -[this-screenshot-container]: https://raw.githubusercontent.com/accetto/headless-coding-g3/master/docker/doc/images/debian-vnc-xfce-nodejs.jpg - - +[this-screenshot-container]: https://raw.githubusercontent.com/accetto/headless-coding-g3/master/docker/doc/images/animation-headless-coding-nodejs-live.gif [accetto-github-xubuntu-vnc-novnc]: https://github.com/accetto/xubuntu-vnc-novnc/ -[accetto-github-ubuntu-vnc-xfce]: https://github.com/accetto/ubuntu-vnc-xfce -[that-wiki-firefox-multiprocess]: https://github.com/accetto/xubuntu-vnc/wiki/Firefox-multiprocess - - +[accetto-github-ubuntu-vnc-xfce]: https://github.com/accetto/ubuntu-vnc-xfce [docker-debian]: https://hub.docker.com/_/debian/ -[debian-packages-search]: https://packages.debian.org/index - -[docker-doc]: https://docs.docker.com/ -[docker-doc-managing-data]: https://docs.docker.com/storage/ - [angular]: https://angular.io/ [chromium]: https://www.chromium.org/Home [curl]: http://manpages.ubuntu.com/manpages/bionic/man1/curl.1.html @@ -413,22 +150,17 @@ Credit goes to all the countless people and companies, who contribute to open so [nano]: https://www.nano-editor.org/ [novnc]: https://github.com/kanaka/noVNC [npm]: https://www.npmjs.com/ +[sudo]: https://www.sudo.ws/ [tigervnc]: http://tigervnc.org [tini]: https://github.com/krallin/tini [typescript]: https://www.typescriptlang.org/ [vscode]: https://code.visualstudio.com/ [xfce]: http://www.xfce.org - - [badge-github-release]: https://badgen.net/github/release/accetto/headless-coding-g3?icon=github&label=release -[badge-github-release-date]: https://img.shields.io/github/release-date/accetto/headless-coding-g3?logo=github - - - [badge-docker-pulls]: https://badgen.net/docker/pulls/accetto/debian-vnc-xfce-nodejs-g3?icon=docker&label=pulls [badge-docker-stars]: https://badgen.net/docker/stars/accetto/debian-vnc-xfce-nodejs-g3?icon=docker&label=stars - + diff --git a/docker/xfce-nodejs/README.md b/docker/xfce-nodejs/README.md index 6ca669b..0c8821b 100644 --- a/docker/xfce-nodejs/README.md +++ b/docker/xfce-nodejs/README.md @@ -2,93 +2,15 @@ ## accetto/debian-vnc-xfce-nodejs-g3 -[Docker Hub][this-docker] - [Git Hub][this-github] - [Dockerfile][this-dockerfile] - [Docker Readme][this-readme-dockerhub] - [Changelog][this-changelog] - [Project Readme][this-readme-project] - -![badge-docker-pulls][badge-docker-pulls] -![badge-docker-stars][badge-docker-stars] -![badge-github-release][badge-github-release] -![badge-github-release-date][badge-github-release-date] - -*** - -- [Headless Debian/Xfce container with VNC/noVNC for `Node.js` development](#headless-debianxfce-container-with-vncnovnc-for-nodejs-development) - - [accetto/debian-vnc-xfce-nodejs-g3](#accettodebian-vnc-xfce-nodejs-g3) - - [Introduction](#introduction) - - [TL;DR](#tldr) - - [Installing packages](#installing-packages) - - [Shared memory size](#shared-memory-size) - - [Extending images](#extending-images) - - [Building images](#building-images) - - [Sharing devices](#sharing-devices) - - [Other examples](#other-examples) - - [Description](#description) - - [Image tags](#image-tags) - - [Ports](#ports) - - [Volumes](#volumes) - - [Version sticker](#version-sticker) - - [Using headless containers](#using-headless-containers) - - [Overriding environment variables](#overriding-environment-variables) - - [Overriding VNC/noVNC parameters](#overriding-vncnovnc-parameters) - - [Container user account](#container-user-account) - - [Running containers in background or foreground](#running-containers-in-background-or-foreground) - - [Startup options and help](#startup-options-and-help) - - [Issues, Wiki and Discussions](#issues-wiki-and-discussions) - - [Credits](#credits) - - [Diagrams](#diagrams) - - [Dockerfile.xfce.nodejs](#dockerfilexfcenodejs) +[User Guide][this-user-guide] - [Docker Hub][this-docker] - [Dockerfile][this-dockerfile] - [Readme][this-readme] - [Changelog][this-changelog] *** -### Introduction - -This repository contains resources for building Docker images based on [Debian 11][docker-debian] with [Xfce][xfce] desktop environment, [VNC][tigervnc]/[noVNC][novnc] servers for headless use, the JavaScript-based platform [Node.js][nodejs] with [npm][npm] and optionally other tools for programming (e.g. [Visual Studio Code][vscode]). - -All images can optionally include also the [Chromium][chromium] or [Firefox][firefox] web browsers. - -Adding more tools like [TypeScript][typescript], [Angular][angular] or [Electron][electron] usually requires only a single or just a few commands. The instructions are in the [provided README files](https://github.com/accetto/headless-coding-g3/tree/master/docker/xfce-nodejs/src/home) and some simple test applications are also already included. - -This is a sibling project to the project [accetto/debian-vnc-xfce-g3][accetto-github-debian-vnc-xfce-g3]. - -There is also the sibling project [accetto/ubuntu-vnc-xfce-g3][accetto-github-ubuntu-vnc-xfce-g3] containing similar images based on [Ubuntu 22.04 LTS and 20.04 LTS][docker-ubuntu]. - -### TL;DR +This GitHub project folder contains resources used by building Debian images available on Docker Hub in the repository [accetto/debian-vnc-xfce-nodejs-g3][this-docker]. -#### Installing packages +This [User guide][this-user-guide] describes the images and how to use them. -I try to keep the images slim. Consequently you can encounter missing dependencies while adding more applications yourself. You can track the missing libraries on the [Debian Packages Search][debian-packages-search] page and install them subsequently. - -You can also try to fix it by executing the following (the default `sudo` password is **headless**): - -```shell -### apt cache needs to be updated only once -sudo apt-get update - -sudo apt --fix-broken install -``` - -#### Shared memory size - -Note that some applications require larger shared memory than the default 64MB. Using 256MB usually solves crashes or strange behavior. - -You can check the current shared memory size by executing the following command inside the container: - -```shell -df -h /dev/shm -``` - -The older sibling Wiki page [Firefox multi-process][that-wiki-firefox-multiprocess] describes several ways, how to increase the shared memory size. - -#### Extending images - -The provided example file `Dockerfile.extend` shows how to use the images as the base for your own images. - -Your concrete `Dockerfile` may need more statements, but the concept should be clear. - -The compose file `example.yml` shows how to switch to another non-root user and how to set the VNC password and resolution. - -#### Building images - -The fastest way to build the images: +### Building images ```shell ### PWD = project root @@ -112,374 +34,62 @@ The fastest way to build the images: ./ci-builder.sh all group complete-nodejs ``` -You can still execute the individual hook scripts as before (see the folder `/docker/hooks/`). However, the provided utilities `builder.sh` and `ci-builder.sh` are more convenient. Before pushing the images to the **Docker Hub** you have to prepare and source the file `secrets.rc` (see `example-secrets.rc`). The script `builder.sh` builds the individual images. The script `ci-builder.sh` can build various groups of images or all of them at once. Check the [builder-utility-readme][this-builder-readme], [local-building-example][this-readme-local-building-example] and [sibling Wiki][sibling-wiki] for more information. - -Note that selected features that are enabled by default can be explicitly disabled via environment variables. This allows to build even smaller images by excluding, for example, `noVNC`. See the [local-building-example][this-readme-local-building-example] for more information. - -#### Sharing devices - -Sharing the audio device for video with sound works only with `Chromium` and only on Linux: - -```shell -docker run -it -P --rm \ - --device /dev/snd:/dev/snd:rw \ - --group-add audio \ -accetto/debian-vnc-xfce-nodejs-g3:chromium -``` - -Sharing the display with the host works only on Linux: - -```shell -xhost +local:$(whoami) - -docker run -it -P --rm \ - -e DISPLAY=${DISPLAY} \ - --device /dev/dri/card0 \ - -v /tmp/.X11-unix:/tmp/.X11-unix:rw \ - accetto/debian-vnc-xfce-nodejs-g3:latest --skip-vnc - -xhost -local:$(whoami) -``` - -Sharing the X11 socket with the host works only on Linux: - -```shell -xhost +local:$(whoami) - -docker run -it -P --rm \ - --device /dev/dri/card0 \ - -v /tmp/.X11-unix:/tmp/.X11-unix:rw \ - accetto/debian-vnc-xfce-nodejs-g3:latest - -xhost -local:$(whoami) -``` - -#### Other examples - -Making [Visual Studio Code][vscode] settings and extensions persistent: - -```shell -### bind these container folders to external volumes -/home/headless/.config/Code -/home/headless/.vscode/ - -### Tip: Keep keyboard shortcuts consistent by setting the keyboard layout -### before starting the Visual Studio Code. -``` - -Updating [npm][npm]: - -```shell -### globally -npm install -g npm - -### checking the versions -node -v -npm -v -npx -v -``` - -Installing [TypeScript][typescript]: - -```shell -### globally -npm install -g typescript - -### checking the version -tsc --version -``` - -Installing [Angular][angular]: - -```shell -### globally -npm install -g @angular/cli - -### checking the version -ng --version -``` - -Installing [Electron][electron]: - -```shell -### local installation inside a project works usually better -npm install --save-dev electron - -### apps need to be started with '--no-sandbox' option -electron-test-app --no-sandbox %U -``` - -### Description - -This is the **third generation** (G3) of my headless images. The **second generation** (G2) contains the GitHub repository [accetto/xubuntu-vnc-novnc][accetto-github-xubuntu-vnc-novnc]. The **first generation** (G1) contains the GitHub repository [accetto/ubuntu-vnc-xfce][accetto-github-ubuntu-vnc-xfce]. - -More information about the image generations can be found in the [sibling project README][sibling-readme-project] file and the [sibling Wiki][sibling-wiki]. - -**Attention:** If you will build an image containing the [Chromium Browser][chromium], then the browser will run in the `--no-sandbox` mode. You should be aware of the implications. The image is intended for testing and development. - -**Attention:** If you will build an image containing the [Firefox][firefox] browser, then the browser will run in the `multi-process` mode. Be aware, that this mode requires larger shared memory (`/dev/shm`). At least 256MB is recommended. Please check the **Firefox multi-process** page in this older [sibling Wiki][that-wiki-firefox-multiprocess] for more information and the instructions, how to set the shared memory size in different scenarios. - -The main features and components of the images in the default configuration are: - -- utilities **ping**, **wget**, **sudo** [curl][curl], [git][git] (Debian distribution) -- current version of JSON processor [jq][jq] -- light-weight [Xfce][xfce] desktop environment (Debian distribution) -- current version of high-performance [TigerVNC][tigervnc] server and client -- current version of [noVNC][novnc] HTML5 clients (full and lite) (TCP port **6901**) -- popular text editor [nano][nano] (Debian distribution) -- lite but advanced graphical editor [mousepad][mousepad] (Debian distribution) -- current version of [tini][tini] as the entry-point initial process (PID 1) -- support for overriding both the container user account and its group -- support of **version sticker** (see below) -- optionally the current version of [Chromium Browser][chromium] open-source web browser (Debian distribution) -- optionally the current version of [Firefox ESR (Extended Support Release)][firefox] web browser and optionally also some additional **plus features** described in the [sibling project README][sibling-readme-xfce-firefox] - -All images include the `LTS` or the `current` version of [Node.js][nodejs] with [npm][npm] and optionally also the current version of the free open-source developer editor [Visual Studio Code][vscode]. - -The history of notable changes is documented in the [CHANGELOG][this-changelog]. - -![container-screenshot][this-screenshot-container] - -### Image tags - -The included resources allow building of almost any combination of the following selectable features: +Refer to the main [README][this-readme] file for more information about the building subject. -- **VNC** server with optional **noVNC** access -- **LTS** or **current** version of **Node.js** -- optional **Visual Studio Code** editor -- optional **Chromium** or **Firefox** browser with optional **plus features** (described in the [sibling project README][sibling-readme-xfce-firefox]) -- optional **screenshooting** and **thumbnailing** support +### Remarks -There are also other, more subtle, optional features. Check the hook script `env.rc` if you are interested about them. - -You can build all possible variations of the images locally, but it would not be reasonable to publish all of them on the **Docker Hub**. - -Therefore only the following image tags will be regularly built and published on the **Docker Hub** (with `Node.js LTS` by default): - -- `latest` implements VNC and noVNC -- `chromium` adds [Chromium Browser][chromium] -- `vscode` adds [Visual Studio Code][vscode] -- `vscode-chromium` adds [Visual Studio Code][vscode] and [Chromium Browser][chromium] -- `vscode-firefox` adds [Visual Studio Code][vscode] and [Firefox][firefox] with the **plus features** (described in the sibling project README) -- `current` with [Node.js Current][nodejs], implements VNC and noVNC - -Clicking on the version sticker badge in the [README on Docker Hub][this-readme-dockerhub] reveals more information about the actual configuration of the image. - -### Ports - -Following **TCP** ports are exposed by default: - -- **5901** is used for access over **VNC** -- **6901** is used for access over [noVNC][novnc] -- **3000** is used by the [Node.js][nodejs] server - -The VNC/noVNC default ports and also some other parameters can be overridden several ways as it is described in the [sibling image README file][sibling-readme-xfce]. - -The [Node.js][nodejs] server default port can be overridden at the **image build-time** by the build argument `ARG_NODEJS_PORT` or at the **container startup-time** by the environment variable `NODEJS_PORT`. - -### Volumes - -The containers do not create or use any external volumes by default. - -Both **named volumes** and **bind mounts** can be used. More about volumes can be found in [Docker documentation][docker-doc] (e.g. [Manage data in Docker][docker-doc-managing-data]). - -However, the container's mounting point `/srv/projects/` is intended for sharing the projects between the container and the host computer: - -```shell -docker run -v /my_local_projects:/srv/projects ... - -### or using the newer syntax -docker run --mount source=/my_local_projects,target=/srv/projects ... -``` - -The container's directory `~/projects/samples` already contains the following simple testing applications: - -- nodejs-test-app -- electron-test-app - -Note that they will be copied locally only if the local directory, you have mounted, has been empty. - -**Tip** If you use an image containing [Visual Studio Code][vscode] and you want to make your settings and extensions persistent, then bind the following container folder to external volumes: - -```shell -/home/headless/.config/Code -/home/headless/.vscode/ -``` - -To keep the keyboard shortcuts consistent, change the keyboard layout to your preferred one before starting the [Visual Studio Code][vscode]. - -### Version sticker - -Version sticker serves multiple purposes that are closer described in the [sibling Wiki][sibling-wiki-version-stickers]. Note that the usage of the version sticker has changed between the generations of images. - -The **short version sticker value** describes the version of the image and it is persisted in its **label** during the build-time. It is also shown as its **badge** in the README file. - -The **verbose version sticker value** is used by the CI builder to decide if the image needs to be refreshed. It describes the actual configuration of the essential components of the image. It can be revealed by clicking on the version sticker badge in the README file. - -The version sticker values are generated by the script `version_sticker.sh`, which is deployed into the startup directory `/dockerstartup`. The script will show a short help if executed with the argument `-h`. There is also a convenient `Version Sticker` launcher on the container desktop. - -## Using headless containers - -There are two ways, how to use the containers created from this image. - -All containers are accessible by a VNC viewer (e.g. [TigerVNC][tigervnc] or [TightVNC][tightvnc]). - -The default `VNC_PORT` value is `5901`. The default `DISPLAY` value is `:1`. The default VNC password (`VNC_PW`) is `headless`. - -The containers that are created from the images built with the **noVNC feature** can be also accessed over [noVNC][noVNC] by any web browser supporting HTML5. - -The default `NOVNC_PORT` value is `6901`. The noVNC password is always identical to the VNC password. - -There are several ways of connecting to headless containers and the possibilities also differ between the Linux and Windows environments, but usually it is done by mapping the VNC/noVNC ports exposed by the container to some free TCP ports on its host system. - -For example, the following command would map the VNC/noVNC ports `5901/6901` of the container to the TCP ports `25901/26901` on the host: - -```shell -docker run -p 25901:5901 -p 26901:6901 ... -``` - -If the container would run on the local computer, then it would be accessible over **VNC** as `localhost:25901` and over **noVNC** as `http://localhost:26901`. - -If it would run on the remote server `mynas`, then it would be accessible over **VNC** as `mynas:25901` and over **noVNC** as `http://mynas:26901`. - -The image offers two [noVNC][novnc] clients - **lite client** and **full client**. Because the connection URL differs slightly in both cases, the container provides a **simple startup page**. - -The startup page offers two hyperlinks for both noVNC clients: - -- **noVNC Lite Client** (`http://mynas:26901/vnc_lite.html`) -- **noVNC Full Client** (`http://mynas:26901/vnc.html`) - -It is also possible to provide the password through the links: - -- `http://mynas:26901/vnc_lite.html?password=headless` -- `http://mynas:26901/vnc.html?password=headless` - -### Overriding environment variables - -If the environment variable `FEATURES_OVERRIDING_ENVV=1`, which is the case by default, then the container startup script will look for the file `$HOME/.override/.override_envv.rc` and source all the lines that begin with the string 'export ' at the first position and contain the '=' character. - -You can provide the overriding file from outside the container using *bind mounts* or *volumes*. - -This feature allows overriding or adding environment variables at the **container startup-time**. -It means, even after the container has already been created. - -You can disable this behavior by setting the variable `FEATURES_OVERRIDING_ENVV` to zero when the container is created or the image is built. - -The lines that have been actually sourced can be reported into the container's log if the startup parameter `--verbose` or `--debug` is provided. - -### Overriding VNC/noVNC parameters - -This image supports several ways of overriding the VNC/noVNV parameters. The [sibling image README file][sibling-readme-xfce] describes how to do it. - -### Container user account - -The [sibling README file][sibling-readme-xfce] describes how the container user account and its group are created and how they can be overridden. It also explains the user permissions and ownership. - -### Running containers in background or foreground - -The [sibling image README file][sibling-readme-xfce] describes how to run the containers in the background (detached) of foreground (interactively). - -### Startup options and help +This is a sibling project to the project [accetto/debian-vnc-xfce-g3][accetto-github-debian-vnc-xfce-g3]. -The startup options and help are also described in the [sibling image README file][sibling-readme-xfce]. +There is also another sibling project [accetto/ubuntu-vnc-xfce-g3][accetto-github-ubuntu-vnc-xfce-g3] containing images based on [Ubuntu 22.04 LTS and 20.04 LTS][docker-ubuntu]. -## Issues, Wiki and Discussions +This is the **third generation** (G3) of my headless images. +The **second generation** (G2) contains the GitHub repository [accetto/xubuntu-vnc-novnc][accetto-github-xubuntu-vnc-novnc]. +The **first generation** (G1) contains the GitHub repository [accetto/ubuntu-vnc-xfce][accetto-github-ubuntu-vnc-xfce]. -If you have found a problem or you just have a question, please check the [Issues][this-issues], the [sibling Issues][sibling-issues] and the [sibling Wiki][sibling-wiki] first. Please do not overlook the closed issues. +### Getting help -If you do not find a solution, you can file a new issue. The better you describe the problem, the bigger the chance it'll be solved soon. +If you've found a problem or you just have a question, please check the [User guide][this-user-guide], [Issues][this-issues] and [sibling Wiki][sibling-wiki] first. +Please do not overlook the closed issues. -If you have a question or an idea and you don't want to open an issue, you can use the [sibling Discussions][sibling-discussions]. +If you do not find a solution, you can file a new issue. +The better you describe the problem, the bigger the chance it'll be solved soon. -## Credits +If you have a question or an idea and you don't want to open an issue, you can also use the [sibling Discussions][sibling-discussions]. -Credit goes to all the countless people and companies, who contribute to open source community and make so many dreamy things real. +### Diagrams -## Diagrams +Diagram of the multi-staged Dockerfile used for building multiple images. -### Dockerfile.xfce.nodejs +The actual content of a particular image build is controlled by the *feature variables*. ![Dockerfile.xfce.nodejs stages][this-diagram-dockerfile-stages-nodejs] *** - +[this-user-guide]: https://accetto.github.io/user-guide-g3/ -[this-changelog]: https://github.com/accetto/headless-coding-g3/blob/master/CHANGELOG.md -[this-github]: https://github.com/accetto/headless-coding-g3/ -[this-issues]: https://github.com/accetto/headless-coding-g3/issues -[this-readme-dockerhub]: https://hub.docker.com/r/accetto/debian-vnc-xfce-nodejs-g3 -[this-readme-project]: https://github.com/accetto/headless-coding-g3/blob/master/README.md +[this-readme]: https://github.com/accetto/headless-coding-g3/blob/master/README.md -[this-builder-readme]: https://github.com/accetto/headless-coding-g3/blob/master/readme-builder.md -[this-readme-local-building-example]: https://github.com/accetto/headless-coding-g3/blob/master/readme-local-building-example.md +[this-changelog]: https://github.com/accetto/headless-coding-g3/blob/master/CHANGELOG.md - +[this-issues]: https://github.com/accetto/headless-coding-g3/issues [accetto-github-debian-vnc-xfce-g3]: https://github.com/accetto/debian-vnc-xfce-g3 + [accetto-github-ubuntu-vnc-xfce-g3]: https://github.com/accetto/ubuntu-vnc-xfce-g3 [sibling-discussions]: https://github.com/accetto/ubuntu-vnc-xfce-g3/discussions -[sibling-issues]: https://github.com/accetto/ubuntu-vnc-xfce-g3/issues -[sibling-readme-project]: https://github.com/accetto/ubuntu-vnc-xfce-g3/blob/master/README.md -[sibling-readme-xfce]: https://github.com/accetto/ubuntu-vnc-xfce-g3/blob/master/docker/xfce/README.md -[sibling-readme-xfce-firefox]: https://github.com/accetto/ubuntu-vnc-xfce-g3/blob/master/docker/xfce-firefox/README.md -[sibling-wiki]: https://github.com/accetto/ubuntu-vnc-xfce-g3/wiki -[sibling-wiki-version-stickers]: https://github.com/accetto/ubuntu-vnc-xfce-g3/wiki/Concepts-of-dockerfiles - +[sibling-wiki]: https://github.com/accetto/ubuntu-vnc-xfce-g3/wiki [this-docker]: https://hub.docker.com/r/accetto/debian-vnc-xfce-nodejs-g3/ + [this-dockerfile]: https://github.com/accetto/headless-coding-g3/blob/master/docker/Dockerfile.xfce.nodejs [this-diagram-dockerfile-stages-nodejs]: https://raw.githubusercontent.com/accetto/headless-coding-g3/master/docker/doc/images/Dockerfile.xfce.nodejs.png -[this-screenshot-container]: https://raw.githubusercontent.com/accetto/headless-coding-g3/master/docker/doc/images/debian-vnc-xfce-nodejs.jpg - - - [accetto-github-xubuntu-vnc-novnc]: https://github.com/accetto/xubuntu-vnc-novnc/ -[accetto-github-ubuntu-vnc-xfce]: https://github.com/accetto/ubuntu-vnc-xfce - -[that-wiki-firefox-multiprocess]: https://github.com/accetto/xubuntu-vnc/wiki/Firefox-multiprocess - +[accetto-github-ubuntu-vnc-xfce]: https://github.com/accetto/ubuntu-vnc-xfce -[docker-debian]: https://hub.docker.com/_/debian/ [docker-ubuntu]: https://hub.docker.com/_/ubuntu/ - -[debian-packages-search]: https://packages.debian.org/index - -[docker-doc]: https://docs.docker.com/ -[docker-doc-managing-data]: https://docs.docker.com/storage/ - -[angular]: https://angular.io/ -[chromium]: https://www.chromium.org/Home -[curl]: http://manpages.ubuntu.com/manpages/bionic/man1/curl.1.html -[electron]: https://www.electronjs.org/ -[firefox]: https://www.mozilla.org -[git]: https://git-scm.com/ -[nodejs]: https://www.nodejs.org/ -[jq]: https://stedolan.github.io/jq/ -[mousepad]: https://github.com/codebrainz/mousepad -[nano]: https://www.nano-editor.org/ -[novnc]: https://github.com/kanaka/noVNC -[npm]: https://www.npmjs.com/ -[tigervnc]: http://tigervnc.org -[tightvnc]: http://www.tightvnc.com -[tini]: https://github.com/krallin/tini -[typescript]: https://www.typescriptlang.org/ -[vscode]: https://code.visualstudio.com/ -[xfce]: http://www.xfce.org - - - -[badge-github-release]: https://badgen.net/github/release/accetto/headless-coding-g3?icon=github&label=release - -[badge-github-release-date]: https://img.shields.io/github/release-date/accetto/headless-coding-g3?logo=github - - - -[badge-docker-pulls]: https://badgen.net/docker/pulls/accetto/debian-vnc-xfce-nodejs-g3?icon=docker&label=pulls - -[badge-docker-stars]: https://badgen.net/docker/stars/accetto/debian-vnc-xfce-nodejs-g3?icon=docker&label=stars diff --git a/docker/xfce-postman/README-dockerhub.md b/docker/xfce-postman/README-dockerhub.md index 0e79335..b2f7c6b 100644 --- a/docker/xfce-postman/README-dockerhub.md +++ b/docker/xfce-postman/README-dockerhub.md @@ -2,186 +2,30 @@ ## accetto/debian-vnc-xfce-postman-g3 -[Docker Hub][this-docker] - [Git Hub][this-github] - [Dockerfile][this-dockerfile] - [Full Readme][this-readme-full] - [Changelog][this-changelog] - [Project Readme][this-readme-project] +[User Guide][this-user-guide] - [GitHub][this-github] - [Dockerfile][this-dockerfile] - [Readme][this-readme-full] - [Changelog][this-changelog] ![badge-docker-pulls][badge-docker-pulls] ![badge-docker-stars][badge-docker-stars] ![badge-github-release][badge-github-release] -![badge-github-release-date][badge-github-release-date] - -![badge_latest_created][badge_latest_created] -[![badge_latest_version-sticker][badge_latest_version-sticker]][link_latest_version-sticker-verbose] - -*** - -**Attention** The Postman company has decided to remove `Scratch Pad` from `Postman App` as of May 15, 2023. Therefore will these images from now on always include the version `10.13.6`, the last one that still contains `Scratch Pad`. *** -- [Headless Debian/Xfce container with VNC/noVNC and Postman desktop app](#headless-debianxfce-container-with-vncnovnc-and-postman-desktop-app) - - [accetto/debian-vnc-xfce-postman-g3](#accettodebian-vnc-xfce-postman-g3) - - [Introduction](#introduction) - - [TL;DR](#tldr) - - [Installing packages](#installing-packages) - - [Shared memory size](#shared-memory-size) - - [Extending images](#extending-images) - - [Building images](#building-images) - - [Sharing devices](#sharing-devices) - - [Description](#description) - - [Image tags](#image-tags) - - [Ports](#ports) - - [Volumes](#volumes) - - [Using headless containers](#using-headless-containers) - - [Overriding VNC/noVNC parameters](#overriding-vncnovnc-parameters) - - [Startup options and help](#startup-options-and-help) - - [More information](#more-information) - - [Issues, Wiki and Discussions](#issues-wiki-and-discussions) - - [Credits](#credits) - -*** - -### Introduction - -This repository contains resources for building Docker images based on [Debian 11][docker-debian] with [Xfce][xfce] desktop environment, [VNC][tigervnc]/[noVNC][novnc] servers for headless use and the [Postman][postman] desktop application. - -All images can optionally include also the [Chromium][chromium] or [Firefox][firefox] web browsers. - -Adding more tools like, for example, [Newman][newman] usually requires only a single or just a few commands. The instructions are in the [provided README file](https://github.com/accetto/headless-coding-g3/tree/master/docker/xfce-postman/src/home). - -This is the **short README** version for the **Docker Hub**. There is also the [full-length README][this-readme-full] on the **GitHub**. - -### TL;DR - -#### Installing packages - -I try to keep the images slim. Consequently you can encounter missing dependencies while adding more applications yourself. You can track the missing libraries on the [Debian Packages Search][debian-packages-search] page and install them subsequently. - -You can also try to fix it by executing the following (the default `sudo` password is **headless**): - -```shell -### apt cache needs to be updated only once -sudo apt-get update - -sudo apt --fix-broken install -``` - -#### Shared memory size - -Note that some applications require larger shared memory than the default 64MB. Using 256MB usually solves crashes or strange behavior. - -You can check the current shared memory size by executing the following command inside the container: - -```shell -df -h /dev/shm -``` - -The older sibling Wiki page [Firefox multi-process][that-wiki-firefox-multiprocess] describes several ways, how to increase the shared memory size. - -#### Extending images - -The provided example file `Dockerfile.extend` shows how to use the images as the base for your own images. - -Your concrete `Dockerfile` may need more statements, but the concept should be clear. - -The compose file `example.yml` shows how to switch to another non-root user and how to set the VNC password and resolution. - -#### Building images - -The fastest way to build the images: - -```shell -### PWD = project root -### prepare and source the 'secrets.rc' file first (see 'example-secrets.rc') - -### examples of building and publishing the individual images -./builder.sh postman all -./builder.sh postman-chromium all -./builder.sh postman-firefox all - -### just building the image, skipping the publishing and the version sticker update -./builder.sh postman build - -### examples of building and publishing the images as a group -./ci-builder.sh all group postman postman-chromium - -### or all the images featuring the Postman -./ci-builder.sh all group complete-postman -``` - -You can still execute the individual hook scripts as before (see the folder /docker/hooks/). However, the provided utilities builder.sh and ci-builder.sh are more convenient. Before pushing the images to the Docker Hub you have to prepare and source the file secrets.rc (see example-secrets.rc). The script builder.sh builds the individual images. The script ci-builder.sh can build various groups of images or all of them at once. Check the [builder-utility-readme][this-builder-readme], [local-building-example][this-readme-local-building-example] and [sibling Wiki][sibling-wiki] for more information. - -Note that selected features that are enabled by default can be explicitly disabled via environment variables. This allows to build even smaller images by excluding, for example, `noVNC`. See the [local-building-example][this-readme-local-building-example] for more information. - -#### Sharing devices - -Sharing the audio device for video with sound works only with `Chromium` and only on Linux: - -```shell -docker run -it -P --rm \ - --device /dev/snd:/dev/snd:rw \ - --group-add audio \ -accetto/debian-vnc-xfce-postman-g3:chromium -``` - -Sharing the display with the host works only on Linux: - -```shell -xhost +local:$(whoami) - -docker run -it -P --rm \ - -e DISPLAY=${DISPLAY} \ - --device /dev/dri/card0 \ - -v /tmp/.X11-unix:/tmp/.X11-unix:rw \ - accetto/debian-vnc-xfce-postman-g3:latest --skip-vnc - -xhost -local:$(whoami) -``` +This Docker Hub repository contains Docker images for headless working with the [Postman][postman] desktop application. -Sharing the X11 socket with the host works only on Linux: +The images are based on [Debian 11][docker-debian] and include [Xfce][xfce] desktop, [TigerVNC][tigervnc] server and [noVNC][novnc] client. -```shell -xhost +local:$(whoami) +The popular web browsers [Chromium][chromium] or [Firefox][firefox] are also included. -docker run -it -P --rm \ - --device /dev/dri/card0 \ - -v /tmp/.X11-unix:/tmp/.X11-unix:rw \ - accetto/debian-vnc-xfce-postman-g3:latest +Adding more tools like, for example, [Newman][newman] usually requires only a single or just a few commands. The instructions are in the [provided README file][this-readme-postman-newman]. -xhost -local:$(whoami) -``` +This [User guide][this-user-guide] describes the images and how to use them. -### Description +The related [GitHub project][this-github] contains image generators that image users generally don’t need, unless they want to build the images themselves. -This is the **third generation** (G3) of my headless images. More information about the image generations can be found in the [sibling project README][sibling-readme-project] file and the [sibling Wiki][sibling-wiki]. +### Tags -**Attention:** If you will build an image containing the [Chromium Browser][chromium], then the browser will run in the `--no-sandbox` mode. You should be aware of the implications. The image is intended for testing and development. - -**Attention:** If you will build an image containing the [Firefox][firefox] browser, then the browser will run in the `multi-process` mode. Be aware, that this mode requires larger shared memory (`/dev/shm`). At least 256MB is recommended. Please check the **Firefox multi-process** page in this older [sibling Wiki][that-wiki-firefox-multiprocess] for more information and the instructions, how to set the shared memory size in different scenarios. - -The main features and components of the images in the default configuration are: - -- utilities **ping**, **wget**, **sudo** (Debian distribution) -- current version of JSON processor [jq][jq] -- light-weight [Xfce][xfce] desktop environment (Debian distribution) -- current version of high-performance [TigerVNC][tigervnc] server and client -- current version of [noVNC][novnc] HTML5 clients (full and lite) (TCP port **6901**) -- popular text editor [nano][nano] (Debian distribution) -- lite but advanced graphical editor [mousepad][mousepad] (Debian distribution) -- current version of [tini][tini] as the entry-point initial process (PID 1) -- support for overriding both the container user account and its group -- support of **version sticker** (see the [full-length README][this-readme-full] on the **GitHub**) -- optionally the current version of [Chromium Browser][chromium] open-source web browser (Debian distribution) -- optionally the current version of [Firefox ESR (Extended Support Release)][firefox] web browser and optionally also some additional **plus features** described in the [sibling project README][sibling-readme-xfce-firefox] - -All images include the version `10.13.6` of the [Postman][postman] desktop application. This is the last version that still includes `Scratch Pad`. - -The history of notable changes is documented in the [CHANGELOG][this-changelog]. - -![container-screenshot][this-screenshot-container] - -### Image tags - -The following image tags on the **Docker Hub** are regularly rebuilt: +The following image tags are regularly built and published on Docker Hub: + - `latest` implements VNC and noVNC @@ -193,131 +37,117 @@ The following image tags on the **Docker Hub** are regularly rebuilt: ![badge_chromium_created][badge_chromium_created] [![badge_chromium_version-sticker][badge_chromium_version-sticker]][link_chromium_version-sticker-verbose] -- `firefox` adds [Firefox][firefox] with the **plus features** (described in the [sibling project README][sibling-readme-xfce-firefox]) +- `firefox` adds [Firefox][firefox] ![badge_firefox_created][badge_firefox_created] [![badge_firefox_version-sticker][badge_firefox_version-sticker]][link_firefox_version-sticker-verbose] -Clicking on the version sticker badge in the [README on Docker Hub][this-readme-dockerhub] reveals more information about the actual configuration of the image. + -### Ports +**Hint:** Clicking the version sticker badge reveals more information about the particular build. -Following **TCP** ports are exposed by default: +### Features -- **5901** is used for access over **VNC** -- **6901** is used for access over [noVNC][novnc] - -The VNC/noVNC default ports and also some other parameters can be overridden several ways as it is described in the [sibling image README file][sibling-readme-xfce]. - -### Volumes - -The containers do not create or use any external volumes by default. - -Both **named volumes** and **bind mounts** can be used. More about volumes can be found in [Docker documentation][docker-doc] (e.g. [Manage data in Docker][docker-doc-managing-data]). +The main features and components of the images in the default configuration are: -However, the container's mounting point `/srv/projects/` is intended for sharing the projects between the container and the host computer: +- lightweight [Xfce][xfce] desktop environment (Debian distribution) +- [sudo][sudo] support +- utilities [curl][curl] and [git][git] (Debian distribution) +- current version of JSON processor [jq][jq] +- current version of high-performance [TigerVNC][tigervnc] server and client +- current version of [noVNC][novnc] HTML5 clients (full and lite) (TCP port **6901**) +- popular text editor [nano][nano] (Debian distribution) +- lite but advanced graphical editor [mousepad][mousepad] (Debian distribution) +- current version of [tini][tini] as the entry-point initial process (PID 1) +- support for overriding environment variables, VNC parameters, user and group (see [User guide][this-user-guide-using-containers]) +- support of **version sticker** (see [User guide][this-user-guide-version-sticker]) +- current version of [Chromium Browser][chromium] open-source web browser (Debian distribution) +- current version of [Firefox ESR (Extended Support Release)][firefox] web browser and also the additional **Firefox plus** feature (see [User guide][this-user-guide-firefox-plus]) +- [Postman App][postman] desktop application (version `10.13.6`, the last one still including `Scratch Pad`) -```shell -docker run -v /my_local_projects:/srv/projects ... +The following **TCP** ports are exposed by default: -### or using the newer syntax -docker run --mount source=/my_local_projects,target=/srv/projects ... -``` +- **5901** for access over **VNC** (using VNC viewer) +- **6901** for access over [noVNC][novnc] (using web browser) -## Using headless containers +![container-screenshot][this-screenshot-container] -More information about using headless containers can be found in the [full-length README][this-readme-full] file on GitHub. +### Remarks -### Overriding VNC/noVNC parameters +The Postman company has decided to remove the `Scratch Pad` from the `Postman App` as of May 15, 2023. -This image supports several ways of overriding the VNC/noVNV parameters. The [sibling image README file][sibling-readme-xfce] describes how to do it. +Therefore will these images always contain the default version `10.13.6`. -### Startup options and help +That is the last `Postman App` version still including the `Scratch Pad` and supporting off-line usage. -The startup options and help are also described in the [sibling image README file][sibling-readme-xfce]. +However, you can easily update the `Postman App` to the latest version in the running container. -### More information +This is the **third generation** (G3) of my headless images. +The **second generation** (G2) contains the GitHub repository [accetto/xubuntu-vnc-novnc][accetto-github-xubuntu-vnc-novnc]. +The **first generation** (G1) contains the GitHub repository [accetto/ubuntu-vnc-xfce][accetto-github-ubuntu-vnc-xfce]. -More information about these images can be found in the [full-length README][this-readme-full] file on GitHub. +### Getting help -## Issues, Wiki and Discussions +If you've found a problem or you just have a question, please check the [User guide][this-user-guide], [Issues][this-issues] and [sibling Wiki][sibling-wiki] first. +Please do not overlook the closed issues. -If you have found a problem or you just have a question, please check the [Issues][this-issues], the [sibling Issues][sibling-issues] and the [sibling Wiki][sibling-wiki] first. Please do not overlook the closed issues. +If you do not find a solution, you can file a new issue. +The better you describe the problem, the bigger the chance it'll be solved soon. -If you do not find a solution, you can file a new issue. The better you describe the problem, the bigger the chance it'll be solved soon. +If you have a question or an idea and you don't want to open an issue, you can also use the [sibling Discussions][sibling-discussions]. -If you have a question or an idea and you don't want to open an issue, you can use the [sibling Discussions][sibling-discussions]. +*** -## Credits +[this-user-guide]: https://accetto.github.io/user-guide-g3/ -Credit goes to all the countless people and companies, who contribute to open source community and make so many dreamy things real. +[this-user-guide-version-sticker]: https://accetto.github.io/user-guide-g3/version-sticker/ -*** +[this-user-guide-using-containers]: https://accetto.github.io/user-guide-g3/using-containers/ - +[this-user-guide-firefox-plus]: https://accetto.github.io/user-guide-g3/firefox-plus/ [this-changelog]: https://github.com/accetto/headless-coding-g3/blob/master/CHANGELOG.md [this-github]: https://github.com/accetto/headless-coding-g3/ + [this-issues]: https://github.com/accetto/headless-coding-g3/issues -[this-readme-dockerhub]: https://hub.docker.com/r/accetto/debian-vnc-xfce-postman-g3 -[this-readme-full]: https://github.com/accetto/headless-coding-g3/blob/master/docker/xfce-postman/README.md -[this-readme-project]: https://github.com/accetto/headless-coding-g3/blob/master/README.md -[this-builder-readme]: https://github.com/accetto/headless-coding-g3/blob/master/readme-builder.md -[this-readme-local-building-example]: https://github.com/accetto/headless-coding-g3/blob/master/readme-local-building-example.md +[this-readme-full]: https://github.com/accetto/headless-coding-g3/blob/master/docker/xfce-postman/README.md - +[this-readme-postman-newman]: https://github.com/accetto/headless-coding-g3/blob/master/docker/xfce-postman/src/home/readme-postman-newman.md [sibling-discussions]: https://github.com/accetto/ubuntu-vnc-xfce-g3/discussions -[sibling-issues]: https://github.com/accetto/ubuntu-vnc-xfce-g3/issues -[sibling-readme-project]: https://github.com/accetto/ubuntu-vnc-xfce-g3/blob/master/README.md -[sibling-readme-xfce]: https://github.com/accetto/ubuntu-vnc-xfce-g3/blob/master/docker/xfce/README.md -[sibling-readme-xfce-firefox]: https://github.com/accetto/ubuntu-vnc-xfce-g3/blob/master/docker/xfce-firefox/README.md -[sibling-wiki]: https://github.com/accetto/ubuntu-vnc-xfce-g3/wiki - +[sibling-wiki]: https://github.com/accetto/ubuntu-vnc-xfce-g3/wiki -[this-docker]: https://hub.docker.com/r/accetto/debian-vnc-xfce-postman-g3/ [this-dockerfile]: https://github.com/accetto/headless-coding-g3/blob/master/docker/Dockerfile.xfce.postman -[this-screenshot-container]: https://raw.githubusercontent.com/accetto/headless-coding-g3/master/docker/doc/images/debian-vnc-xfce-postman.jpg - - +[this-screenshot-container]: https://raw.githubusercontent.com/accetto/headless-coding-g3/master/docker/doc/images/animation-headless-coding-postman-live.gif -[that-wiki-firefox-multiprocess]: https://github.com/accetto/xubuntu-vnc/wiki/Firefox-multiprocess +[accetto-github-xubuntu-vnc-novnc]: https://github.com/accetto/xubuntu-vnc-novnc/ - +[accetto-github-ubuntu-vnc-xfce]: https://github.com/accetto/ubuntu-vnc-xfce [docker-debian]: https://hub.docker.com/_/debian/ -[debian-packages-search]: https://packages.debian.org/index - -[docker-doc]: https://docs.docker.com/ -[docker-doc-managing-data]: https://docs.docker.com/storage/ - [chromium]: https://www.chromium.org/Home +[curl]: http://manpages.ubuntu.com/manpages/bionic/man1/curl.1.html [firefox]: https://www.mozilla.org +[git]: https://git-scm.com/ [jq]: https://stedolan.github.io/jq/ [mousepad]: https://github.com/codebrainz/mousepad [nano]: https://www.nano-editor.org/ [newman]: https://github.com/postmanlabs/newman [novnc]: https://github.com/kanaka/noVNC [postman]: https://www.postman.com/downloads/ +[sudo]: https://www.sudo.ws/ [tigervnc]: http://tigervnc.org -[tightvnc]: http://www.tightvnc.com [tini]: https://github.com/krallin/tini [xfce]: http://www.xfce.org - - [badge-github-release]: https://badgen.net/github/release/accetto/headless-coding-g3?icon=github&label=release -[badge-github-release-date]: https://img.shields.io/github/release-date/accetto/headless-coding-g3?logo=github - - - [badge-docker-pulls]: https://badgen.net/docker/pulls/accetto/debian-vnc-xfce-postman-g3?icon=docker&label=pulls [badge-docker-stars]: https://badgen.net/docker/stars/accetto/debian-vnc-xfce-postman-g3?icon=docker&label=stars - + diff --git a/docker/xfce-postman/README.md b/docker/xfce-postman/README.md index e2e9fd9..bcff362 100644 --- a/docker/xfce-postman/README.md +++ b/docker/xfce-postman/README.md @@ -2,96 +2,15 @@ ## accetto/debian-vnc-xfce-postman-g3 -[Docker Hub][this-docker] - [Git Hub][this-github] - [Dockerfile][this-dockerfile] - [Docker Readme][this-readme-dockerhub] - [Changelog][this-changelog] - [Project Readme][this-readme-project] - -![badge-docker-pulls][badge-docker-pulls] -![badge-docker-stars][badge-docker-stars] -![badge-github-release][badge-github-release] -![badge-github-release-date][badge-github-release-date] - -*** - -**Attention** The Postman company has decided to remove `Scratch Pad` from `Postman App` as of May 15, 2023. Therefore will these images from now on always include the version `10.13.6`, the last one that still contains `Scratch Pad`. - -**Important for builders**: Downloading `Postman` is prohibited. The file `postman-10.13.6-linux-x64.tar.gz` must be put into `g3-cache`. +[User Guide][this-user-guide] - [Docker Hub][this-docker] - [Dockerfile][this-dockerfile] - [Readme][this-readme] - [Changelog][this-changelog] *** -- [Headless Debian/Xfce container with VNC/noVNC and Postman desktop app](#headless-debianxfce-container-with-vncnovnc-and-postman-desktop-app) - - [accetto/debian-vnc-xfce-postman-g3](#accettodebian-vnc-xfce-postman-g3) - - [Introduction](#introduction) - - [TL;DR](#tldr) - - [Installing packages](#installing-packages) - - [Shared memory size](#shared-memory-size) - - [Extending images](#extending-images) - - [Building images](#building-images) - - [Sharing devices](#sharing-devices) - - [Description](#description) - - [Image tags](#image-tags) - - [Ports](#ports) - - [Volumes](#volumes) - - [Version sticker](#version-sticker) - - [Using headless containers](#using-headless-containers) - - [Overriding environment variables](#overriding-environment-variables) - - [Overriding VNC/noVNC parameters](#overriding-vncnovnc-parameters) - - [Container user account](#container-user-account) - - [Running containers in background or foreground](#running-containers-in-background-or-foreground) - - [Startup options and help](#startup-options-and-help) - - [Issues, Wiki and Discussions](#issues-wiki-and-discussions) - - [Credits](#credits) - - [Diagrams](#diagrams) - - [Dockerfile.xfce.postman](#dockerfilexfcepostman) - -### Introduction - -This repository contains resources for building Docker images based on [Debian 11][docker-debian] with [Xfce][xfce] desktop environment, [VNC][tigervnc]/[noVNC][novnc] servers for headless use and the [Postman][postman] desktop application. - -All images can optionally include also the [Chromium][chromium] or [Firefox][firefox] web browsers. - -Adding more tools like, for example, [Newman][newman] usually requires only a single or just a few commands. The instructions are in the [provided README file](https://github.com/accetto/headless-coding-g3/tree/master/docker/xfce-postman/src/home). - -This is a sibling project to the project [accetto/debian-vnc-xfce-g3][accetto-github-debian-vnc-xfce-g3]. - -There is also the sibling project [accetto/ubuntu-vnc-xfce-g3][accetto-github-ubuntu-vnc-xfce-g3] containing similar images based on [Ubuntu 22.04 LTS and 20.04 LTS][docker-ubuntu]. - -### TL;DR - -#### Installing packages - -I try to keep the images slim. Consequently you can encounter missing dependencies while adding more applications yourself. You can track the missing libraries on the [Debian Packages Search][debian-packages-search] page and install them subsequently. - -You can also try to fix it by executing the following (the default `sudo` password is **headless**): - -```shell -### apt cache needs to be updated only once -sudo apt-get update - -sudo apt --fix-broken install -``` - -#### Shared memory size - -Note that some applications require larger shared memory than the default 64MB. Using 256MB usually solves crashes or strange behavior. - -You can check the current shared memory size by executing the following command inside the container: - -```shell -df -h /dev/shm -``` - -The older sibling Wiki page [Firefox multi-process][that-wiki-firefox-multiprocess] describes several ways, how to increase the shared memory size. - -#### Extending images +This GitHub project folder contains resources used by building Debian images available on Docker Hub in the repository [accetto/debian-vnc-xfce-postman-g3][this-docker]. -The provided example file `Dockerfile.extend` shows how to use the images as the base for your own images. +This [User guide][this-user-guide] describes the images and how to use them. -Your concrete `Dockerfile` may need more statements, but the concept should be clear. - -The compose file `example.yml` shows how to switch to another non-root user and how to set the VNC password and resolution. - -#### Building images - -The fastest way to build the images: +### Building images ```shell ### PWD = project root @@ -112,276 +31,61 @@ The fastest way to build the images: ./ci-builder.sh all group complete-postman ``` -You can still execute the individual hook scripts as before (see the folder /docker/hooks/). However, the provided utilities builder.sh and ci-builder.sh are more convenient. Before pushing the images to the Docker Hub you have to prepare and source the file secrets.rc (see example-secrets.rc). The script builder.sh builds the individual images. The script ci-builder.sh can build various groups of images or all of them at once. Check the [builder-utility-readme][this-builder-readme], [local-building-example][this-readme-local-building-example] and [sibling Wiki][sibling-wiki] for more information. - -Note that selected features that are enabled by default can be explicitly disabled via environment variables. This allows to build even smaller images by excluding, for example, `noVNC`. See the [local-building-example][this-readme-local-building-example] for more information. - -#### Sharing devices - -Sharing the audio device for video with sound works only with `Chromium` and only on Linux: - -```shell -docker run -it -P --rm \ - --device /dev/snd:/dev/snd:rw \ - --group-add audio \ -accetto/debian-vnc-xfce-postman-g3:chromium -``` - -Sharing the display with the host works only on Linux: - -```shell -xhost +local:$(whoami) - -docker run -it -P --rm \ - -e DISPLAY=${DISPLAY} \ - --device /dev/dri/card0 \ - -v /tmp/.X11-unix:/tmp/.X11-unix:rw \ - accetto/debian-vnc-xfce-postman-g3:latest --skip-vnc - -xhost -local:$(whoami) -``` - -Sharing the X11 socket with the host works only on Linux: - -```shell -xhost +local:$(whoami) - -docker run -it -P --rm \ - --device /dev/dri/card0 \ - -v /tmp/.X11-unix:/tmp/.X11-unix:rw \ - accetto/debian-vnc-xfce-postman-g3:latest - -xhost -local:$(whoami) -``` - -### Description - -This is the **third generation** (G3) of my headless images. The **second generation** (G2) contains the GitHub repository [accetto/xubuntu-vnc-novnc][accetto-github-xubuntu-vnc-novnc]. The **first generation** (G1) contains the GitHub repository [accetto/ubuntu-vnc-xfce][accetto-github-ubuntu-vnc-xfce]. - -**Attention:** If you will build an image containing the [Chromium Browser][chromium], then the browser will run in the `--no-sandbox` mode. You should be aware of the implications. The image is intended for testing and development. - -**Attention:** If you will build an image containing the [Firefox][firefox] browser, then the browser will run in the `multi-process` mode. Be aware, that this mode requires larger shared memory (`/dev/shm`). At least 256MB is recommended. Please check the **Firefox multi-process** page in this older [sibling Wiki][that-wiki-firefox-multiprocess] for more information and the instructions, how to set the shared memory size in different scenarios. - -The main features and components of the images in the default configuration are: - -- utilities **ping**, **wget**, **sudo** (Debian distribution) -- current version of JSON processor [jq][jq] -- light-weight [Xfce][xfce] desktop environment (Debian distribution) -- current version of high-performance [TigerVNC][tigervnc] server and client -- current version of [noVNC][novnc] HTML5 clients (full and lite) (TCP port **6901**) -- popular text editor [nano][nano] (Debian distribution) -- lite but advanced graphical editor [mousepad][mousepad] (Debian distribution) -- current version of [tini][tini] as the entry-point initial process (PID 1) -- support for overriding both the container user account and its group -- support of **version sticker** (see below) -- optionally the current version of [Chromium Browser][chromium] open-source web browser (Debian distribution) -- optionally the current version of [Firefox ESR (Extended Support Release)][firefox] web browser and optionally also some additional **plus features** described in the [sibling project README][sibling-readme-xfce-firefox] - -All images include the version `10.13.6` of the [Postman][postman] desktop application. This is the last version that still includes `Scratch Pad`. - -The history of notable changes is documented in the [CHANGELOG][this-changelog]. - -![container-screenshot][this-screenshot-container] - -### Image tags - -The following image tags on the **Docker Hub** are regularly rebuilt: - -- `latest` implements VNC and noVNC -- `chromium` adds [Chromium Browser][chromium] -- `firefox` adds [Firefox][firefox] with the **plus features** (described in the [sibling project README][sibling-readme-xfce-firefox]) - -Clicking on the version sticker badge in the [README on Docker Hub][this-readme-dockerhub] reveals more information about the actual configuration of the image. - -### Ports - -Following **TCP** ports are exposed by default: - -- **5901** is used for access over **VNC** -- **6901** is used for access over [noVNC][novnc] - -The VNC/noVNC default ports and also some other parameters can be overridden several ways as it is described in the [sibling image README file][sibling-readme-xfce]. - -### Volumes - -The containers do not create or use any external volumes by default. - -Both **named volumes** and **bind mounts** can be used. More about volumes can be found in [Docker documentation][docker-doc] (e.g. [Manage data in Docker][docker-doc-managing-data]). - -However, the container's mounting point `/srv/projects/` is intended for sharing the projects between the container and the host computer: - -```shell -docker run -v /my_local_projects:/srv/projects ... - -### or using the newer syntax -docker run --mount source=/my_local_projects,target=/srv/projects ... -``` - -### Version sticker - -Version sticker serves multiple purposes that are closer described in the [sibling Wiki][sibling-wiki-version-stickers]. Note that the usage of the version sticker has changed between the generations of images. - -The **short version sticker value** describes the version of the image and it is persisted in its **label** during the build-time. It is also shown as its **badge** in the README file. - -The **verbose version sticker value** is used by the CI builder to decide if the image needs to be refreshed. It describes the actual configuration of the essential components of the image. It can be revealed by clicking on the version sticker badge in the README file. - -The version sticker values are generated by the script `version_sticker.sh`, which is deployed into the startup directory `/dockerstartup`. The script will show a short help if executed with the argument `-h`. There is also a convenient `Version Sticker` launcher on the container desktop. - -## Using headless containers - -There are two ways, how to use the containers created from this image. - -All containers are accessible by a VNC viewer (e.g. [TigerVNC][tigervnc] or [TightVNC][tightvnc]). - -The default `VNC_PORT` value is `5901`. The default `DISPLAY` value is `:1`. The default VNC password (`VNC_PW`) is `headless`. - -The containers that are created from the images built with the **noVNC feature** can be also accessed over [noVNC][noVNC] by any web browser supporting HTML5. - -The default `NOVNC_PORT` value is `6901`. The noVNC password is always identical to the VNC password. - -There are several ways of connecting to headless containers and the possibilities also differ between the Linux and Windows environments, but usually it is done by mapping the VNC/noVNC ports exposed by the container to some free TCP ports on its host system. - -For example, the following command would map the VNC/noVNC ports `5901/6901` of the container to the TCP ports `25901/26901` on the host: - -```shell -docker run -p 25901:5901 -p 26901:6901 ... -``` - -If the container would run on the local computer, then it would be accessible over **VNC** as `localhost:25901` and over **noVNC** as `http://localhost:26901`. - -If it would run on the remote server `mynas`, then it would be accessible over **VNC** as `mynas:25901` and over **noVNC** as `http://mynas:26901`. - -The image offers two [noVNC][novnc] clients - **lite client** and **full client**. Because the connection URL differs slightly in both cases, the container provides a **simple startup page**. - -The startup page offers two hyperlinks for both noVNC clients: - -- **noVNC Lite Client** (`http://mynas:26901/vnc_lite.html`) -- **noVNC Full Client** (`http://mynas:26901/vnc.html`) - -It is also possible to provide the password through the links: - -- `http://mynas:26901/vnc_lite.html?password=headless` -- `http://mynas:26901/vnc.html?password=headless` - -### Overriding environment variables - -If the environment variable `FEATURES_OVERRIDING_ENVV=1`, which is the case by default, then the container startup script will look for the file `$HOME/.override/.override_envv.rc` and source all the lines that begin with the string 'export ' at the first position and contain the '=' character. +Refer to the main [README][this-readme] file for more information about the building subject. -You can provide the overriding file from outside the container using *bind mounts* or *volumes*. +### Remarks -This feature allows overriding or adding environment variables at the **container startup-time**. -It means, even after the container has already been created. - -You can disable this behavior by setting the variable `FEATURES_OVERRIDING_ENVV` to zero when the container is created or the image is built. - -The lines that have been actually sourced can be reported into the container's log if the startup parameter `--verbose` or `--debug` is provided. - -### Overriding VNC/noVNC parameters - -This image supports several ways of overriding the VNC/noVNV parameters. The [sibling image README file][sibling-readme-xfce] describes how to do it. - -### Container user account - -The [sibling README file][sibling-readme-xfce] describes how the container user account and its group are created and how they can be overridden. It also explains the user permissions and ownership. - -### Running containers in background or foreground - -The [sibling image README file][sibling-readme-xfce] describes how to run the containers in the background (detached) of foreground (interactively). - -### Startup options and help +This is a sibling project to the project [accetto/debian-vnc-xfce-g3][accetto-github-debian-vnc-xfce-g3]. -The startup options and help are also described in the [sibling image README file][sibling-readme-xfce]. +There is also another sibling project [accetto/ubuntu-vnc-xfce-g3][accetto-github-ubuntu-vnc-xfce-g3] containing images based on [Ubuntu 22.04 LTS and 20.04 LTS][docker-ubuntu]. -## Issues, Wiki and Discussions +This is the **third generation** (G3) of my headless images. +The **second generation** (G2) contains the GitHub repository [accetto/xubuntu-vnc-novnc][accetto-github-xubuntu-vnc-novnc]. +The **first generation** (G1) contains the GitHub repository [accetto/ubuntu-vnc-xfce][accetto-github-ubuntu-vnc-xfce]. -If you have found a problem or you just have a question, please check the [Issues][this-issues], the [sibling Issues][sibling-issues] and the [sibling Wiki][sibling-wiki] first. Please do not overlook the closed issues. +### Getting help -If you do not find a solution, you can file a new issue. The better you describe the problem, the bigger the chance it'll be solved soon. +If you've found a problem or you just have a question, please check the [User guide][this-user-guide], [Issues][this-issues] and [sibling Wiki][sibling-wiki] first. +Please do not overlook the closed issues. -If you have a question or an idea and you don't want to open an issue, you can use the [sibling Discussions][sibling-discussions]. +If you do not find a solution, you can file a new issue. +The better you describe the problem, the bigger the chance it'll be solved soon. -## Credits +If you have a question or an idea and you don't want to open an issue, you can also use the [sibling Discussions][sibling-discussions]. -Credit goes to all the countless people and companies, who contribute to open source community and make so many dreamy things real. +### Diagrams -## Diagrams +Diagram of the multi-staged Dockerfile used for building multiple images. -### Dockerfile.xfce.postman +The actual content of a particular image build is controlled by the *feature variables*. ![Dockerfile.xfce.postman stages][this-diagram-dockerfile-stages-postman] *** - +[this-user-guide]: https://accetto.github.io/user-guide-g3/ -[this-changelog]: https://github.com/accetto/headless-coding-g3/blob/master/CHANGELOG.md -[this-github]: https://github.com/accetto/headless-coding-g3/ -[this-issues]: https://github.com/accetto/headless-coding-g3/issues -[this-readme-dockerhub]: https://hub.docker.com/r/accetto/debian-vnc-xfce-postman-g3 -[this-readme-project]: https://github.com/accetto/headless-coding-g3/blob/master/README.md +[this-readme]: https://github.com/accetto/headless-coding-g3/blob/master/README.md -[this-builder-readme]: https://github.com/accetto/headless-coding-g3/blob/master/readme-builder.md -[this-readme-local-building-example]: https://github.com/accetto/headless-coding-g3/blob/master/readme-local-building-example.md +[this-changelog]: https://github.com/accetto/headless-coding-g3/blob/master/CHANGELOG.md - +[this-issues]: https://github.com/accetto/headless-coding-g3/issues [accetto-github-debian-vnc-xfce-g3]: https://github.com/accetto/debian-vnc-xfce-g3 + [accetto-github-ubuntu-vnc-xfce-g3]: https://github.com/accetto/ubuntu-vnc-xfce-g3 [sibling-discussions]: https://github.com/accetto/ubuntu-vnc-xfce-g3/discussions -[sibling-issues]: https://github.com/accetto/ubuntu-vnc-xfce-g3/issues -[sibling-readme-xfce]: https://github.com/accetto/ubuntu-vnc-xfce-g3/blob/master/docker/xfce/README.md -[sibling-readme-xfce-firefox]: https://github.com/accetto/ubuntu-vnc-xfce-g3/blob/master/docker/xfce-firefox/README.md -[sibling-wiki]: https://github.com/accetto/ubuntu-vnc-xfce-g3/wiki -[sibling-wiki-version-stickers]: https://github.com/accetto/ubuntu-vnc-xfce-g3/wiki/Concepts-of-dockerfiles - +[sibling-wiki]: https://github.com/accetto/ubuntu-vnc-xfce-g3/wiki [this-docker]: https://hub.docker.com/r/accetto/debian-vnc-xfce-postman-g3/ + [this-dockerfile]: https://github.com/accetto/headless-coding-g3/blob/master/docker/Dockerfile.xfce.postman [this-diagram-dockerfile-stages-postman]: https://raw.githubusercontent.com/accetto/headless-coding-g3/master/docker/doc/images/Dockerfile.xfce.postman.png -[this-screenshot-container]: https://raw.githubusercontent.com/accetto/headless-coding-g3/master/docker/doc/images/debian-vnc-xfce-postman.jpg - - - [accetto-github-xubuntu-vnc-novnc]: https://github.com/accetto/xubuntu-vnc-novnc/ [accetto-github-ubuntu-vnc-xfce]: https://github.com/accetto/ubuntu-vnc-xfce -[that-wiki-firefox-multiprocess]: https://github.com/accetto/xubuntu-vnc/wiki/Firefox-multiprocess - - - -[docker-debian]: https://hub.docker.com/_/debian/ [docker-ubuntu]: https://hub.docker.com/_/ubuntu/ - -[debian-packages-search]: https://packages.debian.org/index - -[docker-doc]: https://docs.docker.com/ -[docker-doc-managing-data]: https://docs.docker.com/storage/ - -[chromium]: https://www.chromium.org/Home -[firefox]: https://www.mozilla.org -[jq]: https://stedolan.github.io/jq/ -[mousepad]: https://github.com/codebrainz/mousepad -[nano]: https://www.nano-editor.org/ -[newman]: https://github.com/postmanlabs/newman -[novnc]: https://github.com/kanaka/noVNC -[postman]: https://www.postman.com/downloads/ -[tigervnc]: http://tigervnc.org -[tightvnc]: http://www.tightvnc.com -[tini]: https://github.com/krallin/tini -[xfce]: http://www.xfce.org - - - -[badge-github-release]: https://badgen.net/github/release/accetto/headless-coding-g3?icon=github&label=release - -[badge-github-release-date]: https://img.shields.io/github/release-date/accetto/headless-coding-g3?logo=github - - - -[badge-docker-pulls]: https://badgen.net/docker/pulls/accetto/debian-vnc-xfce-postman-g3?icon=docker&label=pulls - -[badge-docker-stars]: https://badgen.net/docker/stars/accetto/debian-vnc-xfce-postman-g3?icon=docker&label=stars diff --git a/docker/xfce-python/README-dockerhub.md b/docker/xfce-python/README-dockerhub.md index 559d198..39479ce 100644 --- a/docker/xfce-python/README-dockerhub.md +++ b/docker/xfce-python/README-dockerhub.md @@ -2,212 +2,32 @@ ## accetto/debian-vnc-xfce-python-g3 -[Docker Hub][this-docker] - [Git Hub][this-github] - [Dockerfile][this-dockerfile] - [Full Readme][this-readme-full] - [Changelog][this-changelog] - [Project Readme][this-readme-project] +[User Guide][this-user-guide] - [GitHub][this-github] - [Dockerfile][this-dockerfile] - [Readme][this-readme-full] - [Changelog][this-changelog] ![badge-docker-pulls][badge-docker-pulls] ![badge-docker-stars][badge-docker-stars] ![badge-github-release][badge-github-release] -![badge-github-release-date][badge-github-release-date] - -![badge_latest_created][badge_latest_created] -[![badge_latest_version-sticker][badge_latest_version-sticker]][link_latest_version-sticker-verbose] - -*** - -- [Headless Debian/Xfce container with VNC/noVNC for `Python` development](#headless-debianxfce-container-with-vncnovnc-for-python-development) - - [accetto/debian-vnc-xfce-python-g3](#accettodebian-vnc-xfce-python-g3) - - [Introduction](#introduction) - - [TL;DR](#tldr) - - [Installing packages](#installing-packages) - - [Shared memory size](#shared-memory-size) - - [Extending images](#extending-images) - - [Building images](#building-images) - - [Sharing devices](#sharing-devices) - - [Other examples](#other-examples) - - [Description](#description) - - [Image tags](#image-tags) - - [Ports](#ports) - - [Volumes](#volumes) - - [Using headless containers](#using-headless-containers) - - [Overriding VNC/noVNC parameters](#overriding-vncnovnc-parameters) - - [Startup options and help](#startup-options-and-help) - - [More information](#more-information) - - [Issues, Wiki and Discussions](#issues-wiki-and-discussions) - - [Credits](#credits) *** -### Introduction - -This repository contains resources for building Docker images based on [Debian 11][docker-debian] with [Xfce][xfce] desktop environment, [VNC][tigervnc]/[noVNC][novnc] servers for headless use, [Python][python] programming language with its package installer [pip][pip] and optionally other tools for programming (e.g. [Visual Studio Code][vscode]). - -All images can optionally include also the [Chromium][chromium] or [Firefox][firefox] web browsers. - -Adding more tools like, for example, the most popular Python GUI frameworks [TKinter][tkinter], [PyQt5][pyqt5], [PyQT for Python][pyside] (`PySide2` or `PySide6`), [wxPython][wxpython] or [Kivy][kivy] usually requires only a single or just a few commands. The instructions are in the provided README files and some simple test applications are also already included. - -This is the **short README** version for the **Docker Hub**. There is also the [full-length README][this-readme-full] on the **GitHub**. - -### TL;DR - -#### Installing packages - -I try to keep the images slim. Consequently you can encounter missing dependencies while adding more applications yourself. You can track the missing libraries on the [Debian Packages Search][debian-packages-search] page and install them subsequently. - -You can also try to fix it by executing the following (the default `sudo` password is **headless**): - -```shell -### apt cache needs to be updated only once -sudo apt-get update - -sudo apt --fix-broken install -``` - -#### Shared memory size - -Note that some applications require larger shared memory than the default 64MB. Using 256MB usually solves crashes or strange behavior. - -You can check the current shared memory size by executing the following command inside the container: - -```shell -df -h /dev/shm -``` - -The older siblingWiki page [Firefox multi-process][that-wiki-firefox-multiprocess] describes several ways, how to increase the shared memory size. - -#### Extending images - -The provided example file `Dockerfile.extend` shows how to use the images as the base for your own images. - -Your concrete `Dockerfile` may need more statements, but the concept should be clear. - -The compose file `example.yml` shows how to switch to another non-root user and how to set the VNC password and resolution. - -#### Building images - -The fastest way to build the images: - -```shell -### PWD = project root -### prepare and source the 'secrets.rc' file first (see 'example-secrets.rc') +This Docker Hub repository contains Docker images for headless working with the popular programming language [Python][python] and its package installer [pip][pip]. -### examples of building and publishing the individual images -./builder.sh python all -./builder.sh python-chromium all -./builder.sh python-vscode all -./builder.sh python-vscode-chromium all -./builder.sh python-vscode-firefox all +The images are based on [Debian 11][docker-debian] and include [Xfce][xfce] desktop, [TigerVNC][tigervnc] server and [noVNC][novnc] client. -### just building the image, skipping the publishing and the version sticker update -./builder.sh python build +The free open-source programming editor [Visual Studio Code][vscode] and the popular web browsers [Chromium][chromium] or [Firefox][firefox] are also included. -### examples of building and publishing the images as a group -./ci-builder.sh all group python python-chromium python-vscode-chromium +Adding more tools like, for example, the most popular Python GUI frameworks [TKinter][tkinter], [PyQt5][pyqt5], [PyQT for Python][pyside] (`PySide2` or `PySide6`), [wxPython][wxpython] or [Kivy][kivy] usually requires only a single or just a few commands. +The instructions are in the provided README files and some simple test applications are also already included. -### or all the images featuring Python -./ci-builder.sh all group complete-python -``` +This [User guide][this-user-guide] describes the images and how to use them. -You can still execute the individual hook scripts as before (see the folder `/docker/hooks/`). However, the provided utilities `builder.sh` and `ci-builder.sh` are more convenient. Before pushing the images to the **Docker Hub** you have to prepare and source the file `secrets.rc` (see `example-secrets.rc`). The script `builder.sh` builds the individual images. The script `ci-builder.sh` can build various groups of images or all of them at once. Check the [builder-utility-readme][this-builder-readme], [local-building-example][this-readme-local-building-example] and [sibling Wiki][sibling-wiki] for more information. +The related [GitHub project][this-github] contains image generators that image users generally don’t need, unless they want to build the images themselves. -Note that selected features that are enabled by default can be explicitly disabled via environment variables. This allows to build even smaller images by excluding, for example, `noVNC`. See the [local-building-example][this-readme-local-building-example] for more information. +### Tags -#### Sharing devices +The following image tags are regularly built and published on Docker Hub: -Sharing the audio device for video with sound works only with `Chromium` and only on Linux: - -```shell -docker run -it -P --rm \ - --device /dev/snd:/dev/snd:rw \ - --group-add audio \ -accetto/debian-vnc-xfce-python-g3:chromium -``` - -Sharing the display with the host works only on Linux: - -```shell -xhost +local:$(whoami) - -docker run -it -P --rm \ - -e DISPLAY=${DISPLAY} \ - --device /dev/dri/card0 \ - -v /tmp/.X11-unix:/tmp/.X11-unix:rw \ - accetto/debian-vnc-xfce-python-g3:latest --skip-vnc - -xhost -local:$(whoami) -``` - -Sharing the X11 socket with the host works only on Linux: - -```shell -xhost +local:$(whoami) - -docker run -it -P --rm \ - --device /dev/dri/card0 \ - -v /tmp/.X11-unix:/tmp/.X11-unix:rw \ - accetto/debia-vnc-xfce-python-g3:latest - -xhost -local:$(whoami) -``` - -#### Other examples - -The [python-readme][this-readme-python] describes how to install additional Python modules and GUI frameworks. The simple test applications are in `/srv/samples/`. - -Making [Visual Studio Code][vscode] settings and extensions persistent: - -```shell -### bind these container folders to external volumes -/home/headless/.config/Code -/home/headless/.vscode/ - -### Tip: Keep keyboard shortcuts consistent by setting the keyboard layout -### before starting the Visual Studio Code. -``` - -### Description - -This is the **third generation** (G3) of my headless images. The **second generation** (G2) contains the GitHub repository [accetto/xubuntu-vnc-novnc][accetto-github-xubuntu-vnc-novnc]. The **first generation** (G1) contains the GitHub repository [accetto/ubuntu-vnc-xfce][accetto-github-ubuntu-vnc-xfce]. - -**Attention:** If you will build an image containing the [Chromium Browser][chromium], then the browser will run in the `--no-sandbox` mode. You should be aware of the implications. The image is intended for testing and development. - -**Attention:** If you will build an image containing the [Firefox][firefox] browser, then the browser will run in the `multi-process` mode. Be aware, that this mode requires larger shared memory (`/dev/shm`). At least 256MB is recommended. Please check the **Firefox multi-process** page in this older [sibling Wiki][that-wiki-firefox-multiprocess] for more information and the instructions, how to set the shared memory size in different scenarios. - -The main features and components of the images in the default configuration are: - -- utilities **ping**, **wget**, **sudo**, [curl][curl], [git][git] (Debian distribution) -- current version of JSON processor [jq][jq] -- light-weight [Xfce][xfce] desktop environment (Debian distribution) -- current version of high-performance [TigerVNC][tigervnc] server and client -- current version of [noVNC][novnc] HTML5 clients (full and lite) (TCP port **6901**) -- popular text editor [nano][nano] (Debian distribution) -- lite but advanced graphical editor [mousepad][mousepad] (Debian distribution) -- current version of [tini][tini] as the entry-point initial process (PID 1) -- support for overriding both the container user account and its group -- support of **version sticker** (see the [full-length README][this-readme-full] on the **GitHub**) -- optionally the current version of [Chromium Browser][chromium] open-source web browser (Debian distribution) -- optionally the current version of [Firefox ESR (Extended Support Release)][firefox] web browser and optionally also some additional **plus features** described in the [sibling project README][sibling-readme-xfce-firefox] - -All images include [Python][python] with [pip][pip] package installer (Debian distribution) and optionally also the current version of the free open-source developer editor [Visual Studio Code][vscode]. - -The history of notable changes is documented in the [CHANGELOG][this-changelog]. - -![container-screenshot][this-screenshot-container] - -### Image tags - -The included resources allow building of almost any combination of the following selectable features: - -- **VNC** server with optional **noVNC** access -- **Python** with **pip** package installer -- optional **Visual Studio Code** editor -- optional **Chromium** or **Firefox** browser with optional **plus features** (described in the [sibling project README][sibling-readme-xfce-firefox]) -- optional **screenshooting** and **thumbnailing** support - -There are also other, more subtle, optional features. Check the hook script `env.rc` if you are interested about them. - -You can build all possible variations of the images locally, but it would not be reasonable to publish all of them on the **Docker Hub**. - -Therefore only the following image tags will be regularly built and published on the **Docker Hub**: + - `latest` implements VNC and noVNC @@ -229,134 +49,91 @@ Therefore only the following image tags will be regularly built and published on ![badge_vscode-chromium_created][badge_vscode-chromium_created] [![badge_vscode-chromium_version-sticker][badge_vscode-chromium_version-sticker]][link_vscode-chromium_version-sticker-verbose] -- `vscode-firefox` adds [Visual Studio Code][vscode] and [Firefox][firefox] with **plus features** +- `vscode-firefox` adds [Visual Studio Code][vscode] and [Firefox][firefox] ![badge_vscode-firefox_created][badge_vscode-firefox_created] [![badge_vscode-firefox_version-sticker][badge_vscode-firefox_version-sticker]][link_vscode-firefox_version-sticker-verbose] -The [source repository][this-github] contains also the branch `bonus-images-python-gui-frameworks`, which allows building images already including the most popular Python GUI frameworks (see above). Those images could be occasionally pushed to Docker Hub, but there will be no effort to do it regularly. However, you can built them locally any time. - -Clicking on the version sticker badge in the [README on Docker Hub][this-readme-dockerhub] reveals more information about the actual configuration of the image. - -### Ports - -Following **TCP** ports are exposed by default: - -- **5901** is used for access over **VNC** -- **6901** is used for access over [noVNC][novnc] - -The VNC/noVNC default ports and also some other parameters can be overridden several ways as it is described in the [sibling image README file][sibling-readme-xfce]. - -### Volumes - -The containers do not create or use any external volumes by default. - -Both **named volumes** and **bind mounts** can be used. More about volumes can be found in [Docker documentation][docker-doc] (e.g. [Manage data in Docker][docker-doc-managing-data]). - -However, the container's mounting point `/srv/projects/` is intended for sharing the projects between the container and the host computer: - -```shell -docker run -v /my_local_projects:/srv/projects ... - -### or using the newer syntax -docker run --mount source=/my_local_projects,target=/srv/projects ... -``` - -The container's directory `/srv/samples` already contains the following simple testing applications: - -- loguru-test-app -- typer-cli-test-app -- tkinter-test-app -- wx-test-app -- pyqt-test-app -- pyside-test-app -- kivy-test-app - -Note that they will be copied locally only if the local directory, you have mounted, has been empty. - -**Tip** If you use an image containing [Visual Studio Code][vscode] and you want to make your settings and extensions persistent, then bind the following container folder to external volumes: +**Hint:** Clicking the version sticker badge reveals more information about the particular build. -```shell -/home/headless/.config/Code -/home/headless/.vscode/ -``` +### Features -To keep the keyboard shortcuts consistent, change the keyboard layout to your preferred one before starting the [Visual Studio Code][vscode]. +The main features and components of the images in the default configuration are: -## Using headless containers +- lightweight [Xfce][xfce] desktop environment (Debian distribution) +- [sudo][sudo] support +- utilities [curl][curl] and [git][git] (Debian distribution) +- current version of JSON processor [jq][jq] +- current version of high-performance [TigerVNC][tigervnc] server and client +- current version of [noVNC][novnc] HTML5 clients (full and lite) (TCP port **6901**) +- popular text editor [nano][nano] (Debian distribution) +- lite but advanced graphical editor [mousepad][mousepad] (Debian distribution) +- current version of [tini][tini] as the entry-point initial process (PID 1) +- support for overriding environment variables, VNC parameters, user and group (see [User guide][this-user-guide-using-containers]) +- support of **version sticker** (see [User guide][this-user-guide-version-sticker]) +- current version of [Chromium Browser][chromium] open-source web browser (Debian distribution) +- current version of [Firefox ESR (Extended Support Release)][firefox] web browser and also the additional **Firefox plus** feature (see [User guide][this-user-guide-firefox-plus]) +- programming language [Python][python] with [pip][pip] package installer (Debian distribution) +- current version of free open-source programming editor [Visual Studio Code][vscode] -More information about using headless containers can be found in the [full-length README][this-readme-full] file on GitHub. +The following **TCP** ports are exposed by default: -### Overriding VNC/noVNC parameters +- **5901** for access over **VNC** (using VNC viewer) +- **6901** for access over [noVNC][novnc] (using web browser) -This image supports several ways of overriding the VNC/noVNV parameters. The [sibling image README file][sibling-readme-xfce] describes how to do it. +![container-screenshot][this-screenshot-container] -### Startup options and help +### Remarks -The startup options and help are also described in the [sibling image README file][sibling-readme-xfce]. +The related [GitHub project][this-github] contains also the branch `bonus-images-python-gui-frameworks`, which allows building images already including the most popular Python GUI frameworks (see above). +Those images could be occasionally pushed to Docker Hub, but there will be no effort to do it regularly. +However, you can built them yourself. -### More information +This is the **third generation** (G3) of my headless images. +The **second generation** (G2) contains the GitHub repository [accetto/xubuntu-vnc-novnc][accetto-github-xubuntu-vnc-novnc]. +The **first generation** (G1) contains the GitHub repository [accetto/ubuntu-vnc-xfce][accetto-github-ubuntu-vnc-xfce]. -More information about these images can be found in the [full-length README][this-readme-full] file on GitHub. +### Getting help -## Issues, Wiki and Discussions +If you've found a problem or you just have a question, please check the [User guide][this-user-guide], [Issues][this-issues] and [sibling Wiki][sibling-wiki] first. +Please do not overlook the closed issues. -If you have found a problem or you just have a question, please check the [Issues][this-issues], the [sibling Issues][sibling-issues] and the [sibling Wiki][sibling-wiki] first. Please do not overlook the closed issues. +If you do not find a solution, you can file a new issue. +The better you describe the problem, the bigger the chance it'll be solved soon. -If you do not find a solution, you can file a new issue. The better you describe the problem, the bigger the chance it'll be solved soon. +If you have a question or an idea and you don't want to open an issue, you can also use the [sibling Discussions][sibling-discussions]. -If you have a question or an idea and you don't want to open an issue, you can use the [sibling Discussions][sibling-discussions]. +*** -## Credits +[this-user-guide]: https://accetto.github.io/user-guide-g3/ -Credit goes to all the countless people and companies, who contribute to open source community and make so many dreamy things real. +[this-user-guide-version-sticker]: https://accetto.github.io/user-guide-g3/version-sticker/ -*** +[this-user-guide-using-containers]: https://accetto.github.io/user-guide-g3/using-containers/ - +[this-user-guide-firefox-plus]: https://accetto.github.io/user-guide-g3/firefox-plus/ [this-changelog]: https://github.com/accetto/headless-coding-g3/blob/master/CHANGELOG.md + [this-github]: https://github.com/accetto/headless-coding-g3/ -[this-issues]: https://github.com/accetto/headless-coding-g3/issues -[this-readme-dockerhub]: https://hub.docker.com/r/accetto/debian-vnc-xfce-python-g3 -[this-readme-full]: https://github.com/accetto/headless-coding-g3/blob/master/docker/xfce-python/README.md -[this-readme-project]: https://github.com/accetto/headless-coding-g3/blob/master/README.md -[this-readme-python]: https://github.com/accetto/headless-coding-g3/blob/master/docker/xfce-python/src/home/readme-python.md -[this-builder-readme]: https://github.com/accetto/headless-coding-g3/blob/master/readme-builder.md -[this-readme-local-building-example]: https://github.com/accetto/headless-coding-g3/blob/master/readme-local-building-example.md +[this-issues]: https://github.com/accetto/headless-coding-g3/issues - +[this-readme-full]: https://github.com/accetto/headless-coding-g3/blob/master/docker/xfce-python/README.md [sibling-discussions]: https://github.com/accetto/ubuntu-vnc-xfce-g3/discussions -[sibling-issues]: https://github.com/accetto/ubuntu-vnc-xfce-g3/issues -[sibling-readme-xfce]: https://github.com/accetto/ubuntu-vnc-xfce-g3/blob/master/docker/xfce/README.md -[sibling-readme-xfce-firefox]: https://github.com/accetto/ubuntu-vnc-xfce-g3/blob/master/docker/xfce-firefox/README.md -[sibling-wiki]: https://github.com/accetto/ubuntu-vnc-xfce-g3/wiki - +[sibling-wiki]: https://github.com/accetto/ubuntu-vnc-xfce-g3/wiki -[this-docker]: https://hub.docker.com/r/accetto/debian-vnc-xfce-python-g3/ [this-dockerfile]: https://github.com/accetto/headless-coding-g3/blob/master/docker/Dockerfile.xfce.python -[this-screenshot-container]: https://raw.githubusercontent.com/accetto/headless-coding-g3/master/docker/doc/images/debian-vnc-xfce-python.jpg - - +[this-screenshot-container]: https://raw.githubusercontent.com/accetto/headless-coding-g3/master/docker/doc/images/animation-headless-coding-python-live.gif [accetto-github-xubuntu-vnc-novnc]: https://github.com/accetto/xubuntu-vnc-novnc/ [accetto-github-ubuntu-vnc-xfce]: https://github.com/accetto/ubuntu-vnc-xfce -[that-wiki-firefox-multiprocess]: https://github.com/accetto/xubuntu-vnc/wiki/Firefox-multiprocess - - - [docker-debian]: https://hub.docker.com/_/debian/ -[debian-packages-search]: https://packages.debian.org/index - -[docker-doc]: https://docs.docker.com/ -[docker-doc-managing-data]: https://docs.docker.com/storage/ - [chromium]: https://www.chromium.org/Home [curl]: http://manpages.ubuntu.com/manpages/bionic/man1/curl.1.html [firefox]: https://www.mozilla.org @@ -370,6 +147,7 @@ Credit goes to all the countless people and companies, who contribute to open so [pyqt5]: https://www.riverbankcomputing.com/software/pyqt/ [pyside]: https://doc.qt.io/qtforpython/ [python]: https://www.python.org/ +[sudo]: https://www.sudo.ws/ [tigervnc]: http://tigervnc.org [tini]: https://github.com/krallin/tini [tkinter]: https://wiki.python.org/moin/TkInter @@ -377,16 +155,10 @@ Credit goes to all the countless people and companies, who contribute to open so [wxpython]: https://wxpython.org/ [xfce]: http://www.xfce.org - - [badge-github-release]: https://badgen.net/github/release/accetto/headless-coding-g3?icon=github&label=release -[badge-github-release-date]: https://img.shields.io/github/release-date/accetto/headless-coding-g3?logo=github - - - [badge-docker-pulls]: https://badgen.net/docker/pulls/accetto/debian-vnc-xfce-python-g3?icon=docker&label=pulls [badge-docker-stars]: https://badgen.net/docker/stars/accetto/debian-vnc-xfce-python-g3?icon=docker&label=stars - + diff --git a/docker/xfce-python/README.md b/docker/xfce-python/README.md index d3d7a74..a7dd061 100644 --- a/docker/xfce-python/README.md +++ b/docker/xfce-python/README.md @@ -1,95 +1,16 @@ # Headless Debian/Xfce container with VNC/noVNC for `Python` development -## accetto/debiab-vnc-xfce-python-g3 +## accetto/debian-vnc-xfce-python-g3 -[Docker Hub][this-docker] - [Git Hub][this-github] - [Dockerfile][this-dockerfile] - [Docker Readme][this-readme-dockerhub] - [Changelog][this-changelog] - [Project Readme][this-readme-project] - -![badge-docker-pulls][badge-docker-pulls] -![badge-docker-stars][badge-docker-stars] -![badge-github-release][badge-github-release] -![badge-github-release-date][badge-github-release-date] +[User Guide][this-user-guide] - [Docker Hub][this-docker] - [Dockerfile][this-dockerfile] - [Readme][this-readme] - [Changelog][this-changelog] *** -- [Headless Debian/Xfce container with VNC/noVNC for `Python` development](#headless-debianxfce-container-with-vncnovnc-for-python-development) - - [accetto/debiab-vnc-xfce-python-g3](#accettodebiab-vnc-xfce-python-g3) - - [Introduction](#introduction) - - [TL;DR](#tldr) - - [Installing packages](#installing-packages) - - [Shared memory size](#shared-memory-size) - - [Extending images](#extending-images) - - [Building images](#building-images) - - [Sharing devices](#sharing-devices) - - [Other examples](#other-examples) - - [Description](#description) - - [Image tags](#image-tags) - - [Ports](#ports) - - [Volumes](#volumes) - - [Version sticker](#version-sticker) - - [Using headless containers](#using-headless-containers) - - [Overriding environment variables](#overriding-environment-variables) - - [Overriding VNC/noVNC parameters](#overriding-vncnovnc-parameters) - - [Container user account](#container-user-account) - - [Running containers in background or foreground](#running-containers-in-background-or-foreground) - - [Startup options and help](#startup-options-and-help) - - [Issues, Wiki and Discussions](#issues-wiki-and-discussions) - - [Credits](#credits) - - [Diagrams](#diagrams) - - [Dockerfile.xfce.python](#dockerfilexfcepython) - - [Dockerfile.xfce.python (bonus branch)](#dockerfilexfcepython-bonus-branch) - -*** - -### Introduction - -This repository contains resources for building Docker images based on [Debian 11][docker-debian] with [Xfce][xfce] desktop environment, [VNC][tigervnc]/[noVNC][novnc] servers for headless use, [Python][python] programming language with its package installer [pip][pip] and optionally other tools for programming (e.g. [Visual Studio Code][vscode]). - -All images can optionally include also the [Chromium][chromium] or [Firefox][firefox] web browsers. - -Adding more tools like, for example, the web frameworks [Flask][flask] and [Bottle][bottle] or the most popular Python GUI frameworks [TKinter][tkinter], [PyQt5][pyqt5], [PyQT for Python][pyside] (`PySide2` or `PySide6`), [wxPython][wxpython] or [Kivy][kivy] usually requires only a single or just a few commands. The instructions are in the [provided README file](https://github.com/accetto/headless-coding-g3/blob/master/docker/xfce-python/src/home/) and some simple test applications are also already included. - -This is a sibling project to the project [accetto/debian-vnc-xfce-g3][accetto-github-debian-vnc-xfce-g3]. - -There is also the sibling project [accetto/ubuntu-vnc-xfce-g3][accetto-github-ubuntu-vnc-xfce-g3] containing similar images based on [Ubuntu 22.04 LTS and 20.04 LTS][docker-ubuntu]. - -### TL;DR - -#### Installing packages +This GitHub project folder contains resources used by building Debian images available on Docker Hub in the repository [accetto/debian-vnc-xfce-python-g3][this-docker]. -I try to keep the images slim. Consequently you can encounter missing dependencies while adding more applications yourself. You can track the missing libraries on the [Debian Packages Search][debian-packages-search] page and install them subsequently. +This [User guide][this-user-guide] describes the images and how to use them. -You can also try to fix it by executing the following (the default `sudo` password is **headless**): - -```shell -### apt cache needs to be updated only once -sudo apt-get update - -sudo apt --fix-broken install -``` - -#### Shared memory size - -Note that some applications require larger shared memory than the default 64MB. Using 256MB usually solves crashes or strange behavior. - -You can check the current shared memory size by executing the following command inside the container: - -```shell -df -h /dev/shm -``` - -The older sibling Wiki page [Firefox multi-process][that-wiki-firefox-multiprocess] describes several ways, how to increase the shared memory size. - -#### Extending images - -The provided example file `Dockerfile.extend` shows how to use the images as the base for your own images. - -Your concrete `Dockerfile` may need more statements, but the concept should be clear. - -The compose file `example.yml` shows how to switch to another non-root user and how to set the VNC password and resolution. - -#### Building images - -The fastest way to build the images: +### Building images ```shell ### PWD = project root @@ -112,143 +33,13 @@ The fastest way to build the images: ./ci-builder.sh all group complete-python ``` -You can still execute the individual hook scripts as before (see the folder `/docker/hooks/`). However, the provided utilities `builder.sh` and `ci-builder.sh` are more convenient. Before pushing the images to the **Docker Hub** you have to prepare and source the file `secrets.rc` (see `example-secrets.rc`). The script `builder.sh` builds the individual images. The script `ci-builder.sh` can build various groups of images or all of them at once. Check the [builder-utility-readme][this-builder-readme], [local-building-example][this-readme-local-building-example] and [sibling Wiki][sibling-wiki] for more information. - -Note that selected features that are enabled by default can be explicitly disabled via environment variables. This allows to build even smaller images by excluding, for example, `noVNC`. See the [local-building-example][this-readme-local-building-example] for more information. - -#### Sharing devices - -Sharing the audio device for video with sound works only with `Chromium` and only on Linux: - -```shell -docker run -it -P --rm \ - --device /dev/snd:/dev/snd:rw \ - --group-add audio \ -accetto/debian-vnc-xfce-python-g3:chromium -``` - -Sharing the display with the host works only on Linux: - -```shell -xhost +local:$(whoami) - -docker run -it -P --rm \ - -e DISPLAY=${DISPLAY} \ - --device /dev/dri/card0 \ - -v /tmp/.X11-unix:/tmp/.X11-unix:rw \ - accetto/debian-vnc-xfce-python-g3:latest --skip-vnc - -xhost -local:$(whoami) -``` - -Sharing the X11 socket with the host works only on Linux: - -```shell -xhost +local:$(whoami) - -docker run -it -P --rm \ - --device /dev/dri/card0 \ - -v /tmp/.X11-unix:/tmp/.X11-unix:rw \ - accetto/debian-vnc-xfce-python-g3:latest - -xhost -local:$(whoami) -``` - -#### Other examples - -The [python-readme][this-readme-python] describes how to install additional Python modules and GUI frameworks. The simple test applications are in `/srv/samples/`. - -Making [Visual Studio Code][vscode] settings and extensions persistent: - -```shell -### bind these container folders to external volumes -/home/headless/.config/Code -/home/headless/.vscode/ - -### Tip: Keep keyboard shortcuts consistent by setting the keyboard layout -### before starting the Visual Studio Code. -``` - -### Description - -This is the **third generation** (G3) of my headless images. The **second generation** (G2) contains the GitHub repository [accetto/xubuntu-vnc-novnc][accetto-github-xubuntu-vnc-novnc]. The **first generation** (G1) contains the GitHub repository [accetto/ubuntu-vnc-xfce][accetto-github-ubuntu-vnc-xfce]. - -**Attention:** If you will build an image containing the [Chromium Browser][chromium], then the browser will run in the `--no-sandbox` mode. You should be aware of the implications. The image is intended for testing and development. - -**Attention:** If you will build an image containing the [Firefox][firefox] browser, then the browser will run in the `multi-process` mode. Be aware, that this mode requires larger shared memory (`/dev/shm`). At least 256MB is recommended. Please check the **Firefox multi-process** page in this older [sibling Wiki][that-wiki-firefox-multiprocess] for more information and the instructions, how to set the shared memory size in different scenarios. - -The main features and components of the images in the default configuration are: - -- utilities **ping**, **wget**, **sudo**, [curl][curl], [git][git] (Debian distribution) -- current version of JSON processor [jq][jq] -- light-weight [Xfce][xfce] desktop environment (Debian distribution) -- current version of high-performance [TigerVNC][tigervnc] server and client -- current version of [noVNC][novnc] HTML5 clients (full and lite) (TCP port **6901**) -- popular text editor [nano][nano] (Debian distribution) -- lite but advanced graphical editor [mousepad][mousepad] (Debian distribution) -- current version of [tini][tini] as the entry-point initial process (PID 1) -- support for overriding both the container user account and its group -- support of **version sticker** (see below) -- optionally the current version of [Chromium Browser][chromium] open-source web browser (Debian distribution) -- optionally the current version of [Firefox ESR (Extended Support Release)][firefox] web browser and optionally also some additional **plus features** described in the [sibling project README][sibling-readme-xfce-firefox] - -All images include [Python][python] with [pip][pip] package installer (Debian distribution) and optionally also the current version of the free open-source developer editor [Visual Studio Code][vscode]. - -The history of notable changes is documented in the [CHANGELOG][this-changelog]. - -![container-screenshot][this-screenshot-container] - -### Image tags - -The included resources allow building of almost any combination of the following selectable features: - -- **VNC** server with optional **noVNC** access -- **Python** with **pip** package installer -- optional **Visual Studio Code** editor -- optional **Chromium** or **Firefox** browser with optional **plus features** (described in the [sibling project README][sibling-readme-xfce-firefox]) -- optional **screenshooting** and **thumbnailing** support - -There are also other, more subtle, optional features. Check the hook script `env.rc` if you are interested about them. - -You can build all possible variations of the images locally, but it would not be reasonable to publish all of them on the **Docker Hub**. - -Therefore only the following image tags will be regularly built and published on the **Docker Hub**: - -- `latest` implements VNC and noVNC -- `chromium` adds [Chromium Browser][chromium] -- `vscode` adds [Visual Studio Code][vscode] -- `vscode-chromium` adds [Visual Studio Code][vscode] and [Chromium Browser][chromium] -- `vscode-firefox` adds [Visual Studio Code][vscode] and [Firefox][firefox] with **plus features** +Refer to the main [README][this-readme] file for more information about the building subject. -The [source repository][this-github] contains also the branch `bonus-images-python-gui-frameworks`, which allows building images already including the most popular Python GUI frameworks (see above). Those images could be occasionally pushed to Docker Hub, but there will be no effort to do it regularly. However, you can built them locally any time. +### Remarks -Clicking on the version sticker badge in the [README on Docker Hub][this-readme-dockerhub] reveals more information about the actual configuration of the image. +The [python-readme][this-readme-python] describes how to install additional Python modules and GUI frameworks. -### Ports - -Following **TCP** ports are exposed by default: - -- **5901** is used for access over **VNC** -- **6901** is used for access over [noVNC][novnc] - -The VNC/noVNC default ports and also some other parameters can be overridden several ways as it is described in the [sibling image README file][sibling-readme-xfce]. - -### Volumes - -The containers do not create or use any external volumes by default. - -Both **named volumes** and **bind mounts** can be used. More about volumes can be found in [Docker documentation][docker-doc] (e.g. [Manage data in Docker][docker-doc-managing-data]). - -However, the container's mounting point `/srv/projects/` is intended for sharing the projects between the container and the host computer: - -```shell -docker run -v /my_local_projects:/srv/projects ... - -### or using the newer syntax -docker run --mount source=/my_local_projects,target=/srv/projects ... -``` - -The container's directory `/srv/samples` already contains the following simple testing applications: +The container folder `$HOME/projects/samples/` already contains the following simple applications for testing: - loguru-test-app - typer-cli-test-app @@ -258,198 +49,68 @@ The container's directory `/srv/samples` already contains the following simple t - pyside-test-app - kivy-test-app -Note that they will be copied locally only if the local directory, you have mounted, has been empty. - -**Tip** If you use an image containing [Visual Studio Code][vscode] and you want to make your settings and extensions persistent, then bind the following container folder to external volumes: - -```shell -/home/headless/.config/Code -/home/headless/.vscode/ -``` - -To keep the keyboard shortcuts consistent, change the keyboard layout to your preferred one before starting the [Visual Studio Code][vscode]. - -### Version sticker - -Version sticker serves multiple purposes that are closer described in the [sibling Wiki][sibling-wiki-version-stickers]. Note that the usage of the version sticker has changed between the generations of images. - -The **short version sticker value** describes the version of the image and it is persisted in its **label** during the build-time. It is also shown as its **badge** in the README file. - -The **verbose version sticker value** is used by the CI builder to decide if the image needs to be refreshed. It describes the actual configuration of the essential components of the image. It can be revealed by clicking on the version sticker badge in the README file. - -The version sticker values are generated by the script `version_sticker.sh`, which is deployed into the startup directory `/dockerstartup`. The script will show a short help if executed with the argument `-h`. There is also a convenient `Version Sticker` launcher on the container desktop. - -## Using headless containers - -There are two ways, how to use the containers created from this image. - -All containers are accessible by a VNC viewer (e.g. [TigerVNC][tigervnc] or [TightVNC][tightvnc]). - -The default `VNC_PORT` value is `5901`. The default `DISPLAY` value is `:1`. The default VNC password (`VNC_PW`) is `headless`. - -The containers that are created from the images built with the **noVNC feature** can be also accessed over [noVNC][noVNC] by any web browser supporting HTML5. - -The default `NOVNC_PORT` value is `6901`. The noVNC password is always identical to the VNC password. - -There are several ways of connecting to headless containers and the possibilities also differ between the Linux and Windows environments, but usually it is done by mapping the VNC/noVNC ports exposed by the container to some free TCP ports on its host system. - -For example, the following command would map the VNC/noVNC ports `5901/6901` of the container to the TCP ports `25901/26901` on the host: - -```shell -docker run -p 25901:5901 -p 26901:6901 ... -``` - -If the container would run on the local computer, then it would be accessible over **VNC** as `localhost:25901` and over **noVNC** as `http://localhost:26901`. - -If it would run on the remote server `mynas`, then it would be accessible over **VNC** as `mynas:25901` and over **noVNC** as `http://mynas:26901`. +There is also the branch `bonus-images-python-gui-frameworks`, which allows building images already including the most popular Python GUI frameworks (see above). +Those images could be occasionally pushed to Docker Hub, but there will be no effort to do it regularly. +However, you can built them yourself any time. -The image offers two [noVNC][novnc] clients - **lite client** and **full client**. Because the connection URL differs slightly in both cases, the container provides a **simple startup page**. - -The startup page offers two hyperlinks for both noVNC clients: - -- **noVNC Lite Client** (`http://mynas:26901/vnc_lite.html`) -- **noVNC Full Client** (`http://mynas:26901/vnc.html`) - -It is also possible to provide the password through the links: - -- `http://mynas:26901/vnc_lite.html?password=headless` -- `http://mynas:26901/vnc.html?password=headless` - -### Overriding environment variables - -If the environment variable `FEATURES_OVERRIDING_ENVV=1`, which is the case by default, then the container startup script will look for the file `$HOME/.override/.override_envv.rc` and source all the lines that begin with the string 'export ' at the first position and contain the '=' character. - -You can provide the overriding file from outside the container using *bind mounts* or *volumes*. - -This feature allows overriding or adding environment variables at the **container startup-time**. -It means, even after the container has already been created. - -You can disable this behavior by setting the variable `FEATURES_OVERRIDING_ENVV` to zero when the container is created or the image is built. - -The lines that have been actually sourced can be reported into the container's log if the startup parameter `--verbose` or `--debug` is provided. - -### Overriding VNC/noVNC parameters - -This image supports several ways of overriding the VNC/noVNV parameters. The [sibling image README file][sibling-readme-xfce] describes how to do it. - -### Container user account - -The [sibling README file][sibling-readme-xfce] describes how the container user account and its group are created and how they can be overridden. It also explains the user permissions and ownership. - -### Running containers in background or foreground - -The [sibling image README file][sibling-readme-xfce] describes how to run the containers in the background (detached) of foreground (interactively). - -### Startup options and help +This is a sibling project to the project [accetto/debian-vnc-xfce-g3][accetto-github-debian-vnc-xfce-g3]. -The startup options and help are also described in the [sibling image README file][sibling-readme-xfce]. +There is also another sibling project [accetto/ubuntu-vnc-xfce-g3][accetto-github-ubuntu-vnc-xfce-g3] containing images based on [Ubuntu 22.04 LTS and 20.04 LTS][docker-ubuntu]. -## Issues, Wiki and Discussions +This is the **third generation** (G3) of my headless images. +The **second generation** (G2) contains the GitHub repository [accetto/xubuntu-vnc-novnc][accetto-github-xubuntu-vnc-novnc]. +The **first generation** (G1) contains the GitHub repository [accetto/ubuntu-vnc-xfce][accetto-github-ubuntu-vnc-xfce]. -If you have found a problem or you just have a question, please check the [Issues][this-issues], the [sibling Issues][sibling-issues] and the [sibling Wiki][sibling-wiki] first. Please do not overlook the closed issues. +### Getting help -If you do not find a solution, you can file a new issue. The better you describe the problem, the bigger the chance it'll be solved soon. +If you've found a problem or you just have a question, please check the [User guide][this-user-guide], [Issues][this-issues] and [sibling Wiki][sibling-wiki] first. +Please do not overlook the closed issues. -If you have a question or an idea and you don't want to open an issue, you can use the [sibling Discussions][sibling-discussions]. +If you do not find a solution, you can file a new issue. +The better you describe the problem, the bigger the chance it'll be solved soon. -## Credits +If you have a question or an idea and you don't want to open an issue, you can also use the [sibling Discussions][sibling-discussions]. -Credit goes to all the countless people and companies, who contribute to open source community and make so many dreamy things real. +### Diagrams -## Diagrams +Diagrams of the multi-staged Dockerfiles used for building multiple images. -### Dockerfile.xfce.python +The actual content of a particular image build is controlled by the *feature variables*. ![Dockerfile.xfce.python stages][this-diagram-dockerfile-stages-python] -### Dockerfile.xfce.python (bonus branch) - ![Dockerfile.xfce.python (bonus) stages][this-diagram-dockerfile-stages-python-bonus] *** - +[this-user-guide]: https://accetto.github.io/user-guide-g3/ + +[this-readme]: https://github.com/accetto/headless-coding-g3/blob/master/README.md [this-changelog]: https://github.com/accetto/headless-coding-g3/blob/master/CHANGELOG.md + [this-github]: https://github.com/accetto/headless-coding-g3/ [this-issues]: https://github.com/accetto/headless-coding-g3/issues -[this-readme-dockerhub]: https://hub.docker.com/r/accetto/debian-vnc-xfce-python-g3 -[this-readme-project]: https://github.com/accetto/headless-coding-g3/blob/master/README.md -[this-readme-python]: https://github.com/accetto/headless-coding-g3/blob/master/docker/xfce-python/src/home/readme-python.md -[this-builder-readme]: https://github.com/accetto/headless-coding-g3/blob/master/readme-builder.md -[this-readme-local-building-example]: https://github.com/accetto/headless-coding-g3/blob/master/readme-local-building-example.md - - +[this-readme-python]: https://github.com/accetto/headless-coding-g3/blob/master/docker/xfce-python/src/home/readme-python.md [accetto-github-debian-vnc-xfce-g3]: https://github.com/accetto/debian-vnc-xfce-g3 + [accetto-github-ubuntu-vnc-xfce-g3]: https://github.com/accetto/ubuntu-vnc-xfce-g3 [sibling-discussions]: https://github.com/accetto/ubuntu-vnc-xfce-g3/discussions -[sibling-issues]: https://github.com/accetto/ubuntu-vnc-xfce-g3/issues -[sibling-readme-xfce]: https://github.com/accetto/ubuntu-vnc-xfce-g3/blob/master/docker/xfce/README.md -[sibling-readme-xfce-firefox]: https://github.com/accetto/ubuntu-vnc-xfce-g3/blob/master/docker/xfce-firefox/README.md -[sibling-wiki]: https://github.com/accetto/ubuntu-vnc-xfce-g3/wiki -[sibling-wiki-version-stickers]: https://github.com/accetto/ubuntu-vnc-xfce-g3/wiki/Concepts-of-dockerfiles - +[sibling-wiki]: https://github.com/accetto/ubuntu-vnc-xfce-g3/wiki [this-docker]: https://hub.docker.com/r/accetto/debian-vnc-xfce-python-g3/ + [this-dockerfile]: https://github.com/accetto/headless-coding-g3/blob/master/docker/Dockerfile.xfce.python [this-diagram-dockerfile-stages-python]: https://raw.githubusercontent.com/accetto/headless-coding-g3/master/docker/doc/images/Dockerfile.xfce.python.png -[this-diagram-dockerfile-stages-python-bonus]: https://raw.githubusercontent.com/accetto/headless-coding-g3/master/docker/doc/images/Dockerfile.xfce.python-bonus.png - -[this-screenshot-container]: https://raw.githubusercontent.com/accetto/headless-coding-g3/master/docker/doc/images/debian-vnc-xfce-python.jpg - +[this-diagram-dockerfile-stages-python-bonus]: https://raw.githubusercontent.com/accetto/headless-coding-g3/master/docker/doc/images/Dockerfile.xfce.python-bonus.png [accetto-github-xubuntu-vnc-novnc]: https://github.com/accetto/xubuntu-vnc-novnc/ [accetto-github-ubuntu-vnc-xfce]: https://github.com/accetto/ubuntu-vnc-xfce -[that-wiki-firefox-multiprocess]: https://github.com/accetto/xubuntu-vnc/wiki/Firefox-multiprocess - - - -[docker-debian]: https://hub.docker.com/_/debian/ [docker-ubuntu]: https://hub.docker.com/_/ubuntu/ - -[debian-packages-search]: https://packages.debian.org/index - -[docker-doc]: https://docs.docker.com/ -[docker-doc-managing-data]: https://docs.docker.com/storage/ - -[bottle]: https://bottlepy.org/ -[chromium]: https://www.chromium.org/Home -[curl]: http://manpages.ubuntu.com/manpages/bionic/man1/curl.1.html -[firefox]: https://www.mozilla.org -[flask]: https://palletsprojects.com/p/flask/ -[git]: https://git-scm.com/ -[jq]: https://stedolan.github.io/jq/ -[kivy]: https://kivy.org/#home -[mousepad]: https://github.com/codebrainz/mousepad -[nano]: https://www.nano-editor.org/ -[novnc]: https://github.com/kanaka/noVNC -[pip]: https://pip.pypa.io/en/stable/ -[pyqt5]: https://www.riverbankcomputing.com/software/pyqt/ -[pyside]: https://doc.qt.io/qtforpython/ -[python]: https://www.python.org/ -[tigervnc]: http://tigervnc.org -[tightvnc]: http://www.tightvnc.com -[tini]: https://github.com/krallin/tini -[tkinter]: https://wiki.python.org/moin/TkInter -[vscode]: https://code.visualstudio.com/ -[wxpython]: https://wxpython.org/ -[xfce]: http://www.xfce.org - - - -[badge-github-release]: https://badgen.net/github/release/accetto/headless-coding-g3?icon=github&label=release - -[badge-github-release-date]: https://img.shields.io/github/release-date/accetto/headless-coding-g3?logo=github - - - -[badge-docker-pulls]: https://badgen.net/docker/pulls/accetto/debian-vnc-xfce-python-g3?icon=docker&label=pulls - -[badge-docker-stars]: https://badgen.net/docker/stars/accetto/debian-vnc-xfce-python-g3?icon=docker&label=stars diff --git a/docker/xfce-vscode/README-dockerhub.md b/docker/xfce-vscode/README-dockerhub.md index c6cdf39..8adeee3 100644 --- a/docker/xfce-vscode/README-dockerhub.md +++ b/docker/xfce-vscode/README-dockerhub.md @@ -2,180 +2,29 @@ ## accetto/debian-vnc-xfce-vscode-g3 -[Docker Hub][this-docker] - [Git Hub][this-github] - [Dockerfile][this-dockerfile] - [Full Readme][this-readme-full] - [Changelog][this-changelog] - [Project Readme][this-readme-project] +[User Guide][this-user-guide] - [GitHub][this-github] - [Dockerfile][this-dockerfile] - [Readme][this-readme-full] - [Changelog][this-changelog] ![badge-docker-pulls][badge-docker-pulls] ![badge-docker-stars][badge-docker-stars] ![badge-github-release][badge-github-release] -![badge-github-release-date][badge-github-release-date] - -![badge_latest_created][badge_latest_created] -[![badge_latest_version-sticker][badge_latest_version-sticker]][link_latest_version-sticker-verbose] - -*** - -- [Headless Debian/Xfce container with VNC/noVNC and and Visual Studio Code](#headless-debianxfce-container-with-vncnovnc-and-and-visual-studio-code) - - [accetto/debian-vnc-xfce-vscode-g3](#accettodebian-vnc-xfce-vscode-g3) - - [Introduction](#introduction) - - [TL;DR](#tldr) - - [Installing packages](#installing-packages) - - [Shared memory size](#shared-memory-size) - - [Extending images](#extending-images) - - [Building images](#building-images) - - [Sharing devices](#sharing-devices) - - [Description](#description) - - [Image tags](#image-tags) - - [Ports](#ports) - - [Volumes](#volumes) - - [Using headless containers](#using-headless-containers) - - [Overriding VNC/noVNC parameters](#overriding-vncnovnc-parameters) - - [Startup options and help](#startup-options-and-help) - - [More information](#more-information) - - [Issues, Wiki and Discussions](#issues-wiki-and-discussions) - - [Credits](#credits) *** -### Introduction - -This repository contains resources for building Docker images based on [Debian 11][docker-debian] with [Xfce][xfce] desktop environment, [VNC][tigervnc]/[noVNC][novnc] servers for headless use and the free open-source programming editor [Visual Studio Code][vscode]. - -All images can optionally include also the [Chromium][chromium] or [Firefox][firefox] web browsers. - -This is the **short README** version for the **Docker Hub**. There is also the [full-length README][this-readme-full] on the **GitHub**. - -### TL;DR - -#### Installing packages - -I try to keep the images slim. Consequently you can encounter missing dependencies while adding more applications yourself. You can track the missing libraries on the [Debian Packages Search][debian-packages-search] page and install them subsequently. - -You can also try to fix it by executing the following (the default `sudo` password is **headless**): - -```shell -### apt cache needs to be updated only once -sudo apt-get update - -sudo apt --fix-broken install -``` - -#### Shared memory size - -Note that some applications require larger shared memory than the default 64MB. Using 256MB usually solves crashes or strange behavior. - -You can check the current shared memory size by executing the following command inside the container: - -```shell -df -h /dev/shm -``` - -The older sibling Wiki page [Firefox multi-process][that-wiki-firefox-multiprocess] describes several ways, how to increase the shared memory size. - -#### Extending images - -The provided example file `Dockerfile.extend` shows how to use the images as the base for your own images. - -Your concrete `Dockerfile` may need more statements, but the concept should be clear. - -The compose file `example.yml` shows how to switch to another non-root user and how to set the VNC password and resolution. +This Docker Hub repository contains Docker images for headless working with the the free open-source programming editor [Visual Studio Code][vscode]. -#### Building images +The images are based on [Debian 11][docker-debian] and include [Xfce][xfce] desktop, [TigerVNC][tigervnc] server and [noVNC][novnc] client. -The fastest way to build the images: +The popular web browsers [Chromium][chromium] or [Firefox][firefox] are also included. -```shell -### PWD = project root -### prepare and source the 'secrets.rc' file first (see 'example-secrets.rc') +This [User guide][this-user-guide] describes the images and how to use them. -### examples of building and publishing the individual images -./builder.sh vscode all -./builder.sh vscode-chromium all -./builder.sh vscode-firefox all +The related [GitHub project][this-github] contains image generators that image users generally don’t need, unless they want to build the images themselves. -### just building the image, skipping the publishing and the version sticker update -./builder.sh vscode build +### Tags -### examples of building and publishing the images as a group -./ci-builder.sh all group vscode vscode-chromium +The following image tags are regularly built and published on Docker Hub: -### or all the images featuring the Visual Studio Code -./ci-builder.sh all group complete-vscode -``` - -You can still execute the individual hook scripts as before (see the folder /docker/hooks/). However, the provided utilities builder.sh and ci-builder.sh are more convenient. Before pushing the images to the Docker Hub you have to prepare and source the file secrets.rc (see example-secrets.rc). The script builder.sh builds the individual images. The script ci-builder.sh can build various groups of images or all of them at once. Check the [builder-utility-readme][this-builder-readme], [local-building-example][this-readme-local-building-example] and [sibling Wiki][sibling-wiki] for more information. - -Note that selected features that are enabled by default can be explicitly disabled via environment variables. This allows to build even smaller images by excluding, for example, `noVNC`. See the [local-building-example][this-readme-local-building-example] for more information. - -#### Sharing devices - -Sharing the audio device for video with sound works only with `Chromium` and only on Linux: - -```shell -docker run -it -P --rm \ - --device /dev/snd:/dev/snd:rw \ - --group-add audio \ -accetto/debian-vnc-xfce-vscode-g3:chromium -``` - -Sharing the display with the host works only on Linux: - -```shell -xhost +local:$(whoami) - -docker run -it -P --rm \ - -e DISPLAY=${DISPLAY} \ - --device /dev/dri/card0 \ - -v /tmp/.X11-unix:/tmp/.X11-unix:rw \ - accetto/debian-vnc-xfce-vscode-g3:latest --skip-vnc - -xhost -local:$(whoami) -``` - -Sharing the X11 socket with the host works only on Linux: - -```shell -xhost +local:$(whoami) - -docker run -it -P --rm \ - --device /dev/dri/card0 \ - -v /tmp/.X11-unix:/tmp/.X11-unix:rw \ - accetto/debian-vnc-xfce-vscode-g3:latest - -xhost -local:$(whoami) -``` - -### Description - -This is the **third generation** (G3) of my headless images. More information about the image generations can be found in the [sibling project README][sibling-readme-project] file and the [sibling Wiki][sibling-wiki]. - -**Attention:** If you will build an image containing the [Chromium Browser][chromium], then the browser will run in the `--no-sandbox` mode. You should be aware of the implications. The image is intended for testing and development. - -**Attention:** If you will build an image containing the [Firefox][firefox] browser, then the browser will run in the `multi-process` mode. Be aware, that this mode requires larger shared memory (`/dev/shm`). At least 256MB is recommended. Please check the **Firefox multi-process** page in this older [sibling Wiki][that-wiki-firefox-multiprocess] for more information and the instructions, how to set the shared memory size in different scenarios. - -The main features and components of the images in the default configuration are: - -- utilities **ping**, **wget**, **sudo** (Debian distribution) -- current version of JSON processor [jq][jq] -- light-weight [Xfce][xfce] desktop environment (Debian distribution) -- current version of high-performance [TigerVNC][tigervnc] server and client -- current version of [noVNC][novnc] HTML5 clients (full and lite) (TCP port **6901**) -- popular text editor [nano][nano] (Debian distribution) -- lite but advanced graphical editor [mousepad][mousepad] (Debian distribution) -- current version of [tini][tini] as the entry-point initial process (PID 1) -- support for overriding both the container user account and its group -- support of **version sticker** (see the [full-length README][this-readme-full] on the **GitHub**) -- optionally the current version of [Chromium Browser][chromium] open-source web browser (Debian distribution) -- optionally the current version of [Firefox ESR (Extended Support Release)][firefox] web browser and optionally also some additional **plus features** described in the [sibling project README][sibling-readme-xfce-firefox] - -All images include the current version of the free open-source programming editor [Visual Studio Code][vscode]. - -The history of notable changes is documented in the [CHANGELOG][this-changelog]. - -![container-screenshot][this-screenshot-container] - -### Image tags - -The following image tags on the **Docker Hub** are regularly rebuilt: + - `latest` implements VNC and noVNC @@ -187,130 +36,102 @@ The following image tags on the **Docker Hub** are regularly rebuilt: ![badge_chromium_created][badge_chromium_created] [![badge_chromium_version-sticker][badge_chromium_version-sticker]][link_chromium_version-sticker-verbose] -- `firefox` adds [Firefox][firefox] with the **plus features** (described in the [sibling project README][sibling-readme-xfce-firefox]) +- `firefox` adds [Firefox][firefox] ![badge_firefox_created][badge_firefox_created] [![badge_firefox_version-sticker][badge_firefox_version-sticker]][link_firefox_version-sticker-verbose] -Clicking on the version sticker badge in the [README on Docker Hub][this-readme-dockerhub] reveals more information about the actual configuration of the image. +**Hint:** Clicking the version sticker badge reveals more information about the particular build. -### Ports +### Features -Following **TCP** ports are exposed by default: - -- **5901** is used for access over **VNC** -- **6901** is used for access over [noVNC][novnc] - -The VNC/noVNC default ports and also some other parameters can be overridden several ways as it is described in the [sibling image README file][sibling-readme-xfce]. - -### Volumes - -The containers do not create or use any external volumes by default. - -Both **named volumes** and **bind mounts** can be used. More about volumes can be found in [Docker documentation][docker-doc] (e.g. [Manage data in Docker][docker-doc-managing-data]). - -However, the container's mounting point `/srv/projects/` is intended for sharing the projects between the container and the host computer: - -```shell -docker run -v /my_local_projects:/srv/projects ... - -### or using the newer syntax -docker run --mount source=/my_local_projects,target=/srv/projects ... -``` - -## Using headless containers +The main features and components of the images in the default configuration are: -More information about using headless containers can be found in the [full-length README][this-readme-full] file on GitHub. +- lightweight [Xfce][xfce] desktop environment (Debian distribution) +- [sudo][sudo] support +- utilities [curl][curl] and [git][git] (Debian distribution) +- current version of JSON processor [jq][jq] +- current version of high-performance [TigerVNC][tigervnc] server and client +- current version of [noVNC][novnc] HTML5 clients (full and lite) (TCP port **6901**) +- popular text editor [nano][nano] (Debian distribution) +- lite but advanced graphical editor [mousepad][mousepad] (Debian distribution) +- current version of [tini][tini] as the entry-point initial process (PID 1) +- support for overriding environment variables, VNC parameters, user and group (see [User guide][this-user-guide-using-containers]) +- support of **version sticker** (see [User guide][this-user-guide-version-sticker]) +- current version of [Chromium Browser][chromium] open-source web browser (Debian distribution) +- current version of [Firefox ESR (Extended Support Release)][firefox] web browser and also the additional **Firefox plus** feature (see [User guide][this-user-guide-firefox-plus]) +- current version of free open-source programming editor [Visual Studio Code][vscode] -### Overriding VNC/noVNC parameters +The following **TCP** ports are exposed by default: -This image supports several ways of overriding the VNC/noVNV parameters. The [sibling image README file][sibling-readme-xfce] describes how to do it. +- **5901** for access over **VNC** (using VNC viewer) +- **6901** for access over [noVNC][novnc] (using web browser) -### Startup options and help +![container-screenshot][this-screenshot-container] -The startup options and help are also described in the [sibling image README file][sibling-readme-xfce]. +### Remarks -### More information +This is the **third generation** (G3) of my headless images. +The **second generation** (G2) contains the GitHub repository [accetto/xubuntu-vnc-novnc][accetto-github-xubuntu-vnc-novnc]. +The **first generation** (G1) contains the GitHub repository [accetto/ubuntu-vnc-xfce][accetto-github-ubuntu-vnc-xfce]. -More information about these images can be found in the [full-length README][this-readme-full] file on GitHub. +### Getting help -## Issues, Wiki and Discussions +If you've found a problem or you just have a question, please check the [User guide][this-user-guide], [Issues][this-issues] and [sibling Wiki][sibling-wiki] first. +Please do not overlook the closed issues. -If you have found a problem or you just have a question, please check the [Issues][this-issues], the [sibling Issues][sibling-issues] and the [sibling Wiki][sibling-wiki] first. Please do not overlook the closed issues. +If you do not find a solution, you can file a new issue. +The better you describe the problem, the bigger the chance it'll be solved soon. -If you do not find a solution, you can file a new issue. The better you describe the problem, the bigger the chance it'll be solved soon. +If you have a question or an idea and you don't want to open an issue, you can also use the [sibling Discussions][sibling-discussions]. -If you have a question or an idea and you don't want to open an issue, you can use the [sibling Discussions][sibling-discussions]. +*** -## Credits +[this-user-guide]: https://accetto.github.io/user-guide-g3/ -Credit goes to all the countless people and companies, who contribute to open source community and make so many dreamy things real. +[this-user-guide-version-sticker]: https://accetto.github.io/user-guide-g3/version-sticker/ -*** +[this-user-guide-using-containers]: https://accetto.github.io/user-guide-g3/using-containers/ - +[this-user-guide-firefox-plus]: https://accetto.github.io/user-guide-g3/firefox-plus/ [this-changelog]: https://github.com/accetto/headless-coding-g3/blob/master/CHANGELOG.md [this-github]: https://github.com/accetto/headless-coding-g3/ [this-issues]: https://github.com/accetto/headless-coding-g3/issues -[this-readme-dockerhub]: https://hub.docker.com/r/accetto/debian-vnc-xfce-vscode-g3 -[this-readme-full]: https://github.com/accetto/headless-coding-g3/blob/master/docker/xfce-vscode/README.md -[this-readme-project]: https://github.com/accetto/headless-coding-g3/blob/master/README.md - -[this-builder-readme]: https://github.com/accetto/headless-coding-g3/blob/master/readme-builder.md -[this-readme-local-building-example]: https://github.com/accetto/headless-coding-g3/blob/master/readme-local-building-example.md - +[this-readme-full]: https://github.com/accetto/headless-coding-g3/blob/master/docker/xfce-vscode/README.md [sibling-discussions]: https://github.com/accetto/ubuntu-vnc-xfce-g3/discussions -[sibling-issues]: https://github.com/accetto/ubuntu-vnc-xfce-g3/issues -[sibling-readme-project]: https://github.com/accetto/ubuntu-vnc-xfce-g3/blob/master/README.md -[sibling-readme-xfce]: https://github.com/accetto/ubuntu-vnc-xfce-g3/blob/master/docker/xfce/README.md -[sibling-readme-xfce-firefox]: https://github.com/accetto/ubuntu-vnc-xfce-g3/blob/master/docker/xfce-firefox/README.md -[sibling-wiki]: https://github.com/accetto/ubuntu-vnc-xfce-g3/wiki - +[sibling-wiki]: https://github.com/accetto/ubuntu-vnc-xfce-g3/wiki -[this-docker]: https://hub.docker.com/r/accetto/debian-vnc-xfce-vscode-g3/ [this-dockerfile]: https://github.com/accetto/headless-coding-g3/blob/master/docker/Dockerfile.xfce.vscode -[this-screenshot-container]: https://raw.githubusercontent.com/accetto/headless-coding-g3/master/docker/doc/images/debian-vnc-xfce-vscode.jpg - - - -[that-wiki-firefox-multiprocess]: https://github.com/accetto/xubuntu-vnc/wiki/Firefox-multiprocess +[this-screenshot-container]: https://raw.githubusercontent.com/accetto/headless-coding-g3/master/docker/doc/images/animation-headless-coding-vscode-live.gif +[accetto-github-xubuntu-vnc-novnc]: https://github.com/accetto/xubuntu-vnc-novnc/ - +[accetto-github-ubuntu-vnc-xfce]: https://github.com/accetto/ubuntu-vnc-xfce [docker-debian]: https://hub.docker.com/_/debian/ -[debian-packages-search]: https://packages.debian.org/index - -[docker-doc]: https://docs.docker.com/ -[docker-doc-managing-data]: https://docs.docker.com/storage/ - [chromium]: https://www.chromium.org/Home +[curl]: http://manpages.ubuntu.com/manpages/bionic/man1/curl.1.html [firefox]: https://www.mozilla.org +[git]: https://git-scm.com/ [jq]: https://stedolan.github.io/jq/ [mousepad]: https://github.com/codebrainz/mousepad [nano]: https://www.nano-editor.org/ [novnc]: https://github.com/kanaka/noVNC [tigervnc]: http://tigervnc.org -[tightvnc]: http://www.tightvnc.com [tini]: https://github.com/krallin/tini +[sudo]: https://www.sudo.ws/ [vscode]: https://code.visualstudio.com/ [xfce]: http://www.xfce.org - - [badge-github-release]: https://badgen.net/github/release/accetto/headless-coding-g3?icon=github&label=release -[badge-github-release-date]: https://img.shields.io/github/release-date/accetto/headless-coding-g3?logo=github - - - [badge-docker-pulls]: https://badgen.net/docker/pulls/accetto/debian-vnc-xfce-vscode-g3?icon=docker&label=pulls [badge-docker-stars]: https://badgen.net/docker/stars/accetto/debian-vnc-xfce-vscode-g3?icon=docker&label=stars - + diff --git a/docker/xfce-vscode/README.md b/docker/xfce-vscode/README.md index 4e7a269..78253fd 100644 --- a/docker/xfce-vscode/README.md +++ b/docker/xfce-vscode/README.md @@ -2,88 +2,15 @@ ## accetto/debian-vnc-xfce-vscode-g3 -[Docker Hub][this-docker] - [Git Hub][this-github] - [Dockerfile][this-dockerfile] - [Docker Readme][this-readme-dockerhub] - [Changelog][this-changelog] - [Project Readme][this-readme-project] - -![badge-docker-pulls][badge-docker-pulls] -![badge-docker-stars][badge-docker-stars] -![badge-github-release][badge-github-release] -![badge-github-release-date][badge-github-release-date] +[User Guide][this-user-guide] - [Docker Hub][this-docker] - [Dockerfile][this-dockerfile] - [Readme][this-readme] - [Changelog][this-changelog] *** -- [Headless Debian/Xfce container with VNC/noVNC and Visual Studio Code](#headless-debianxfce-container-with-vncnovnc-and-visual-studio-code) - - [accetto/debian-vnc-xfce-vscode-g3](#accettodebian-vnc-xfce-vscode-g3) - - [Introduction](#introduction) - - [TL;DR](#tldr) - - [Installing packages](#installing-packages) - - [Shared memory size](#shared-memory-size) - - [Extending images](#extending-images) - - [Building images](#building-images) - - [Sharing devices](#sharing-devices) - - [Description](#description) - - [Image tags](#image-tags) - - [Ports](#ports) - - [Volumes](#volumes) - - [Version sticker](#version-sticker) - - [Using headless containers](#using-headless-containers) - - [Overriding environment variables](#overriding-environment-variables) - - [Overriding VNC/noVNC parameters](#overriding-vncnovnc-parameters) - - [Container user account](#container-user-account) - - [Running containers in background or foreground](#running-containers-in-background-or-foreground) - - [Startup options and help](#startup-options-and-help) - - [Issues, Wiki and Discussions](#issues-wiki-and-discussions) - - [Credits](#credits) - - [Diagrams](#diagrams) - - [Dockerfile.xfce.vscode](#dockerfilexfcevscode) - -### Introduction - -This repository contains resources for building Docker images based on [Debian 11][docker-debian] with [Xfce][xfce] desktop environment, [VNC][tigervnc]/[noVNC][novnc] servers for headless use and the free open-source programming editor [Visual Studio Code][vscode]. - -All images can optionally include also the [Chromium][chromium] or [Firefox][firefox] web browsers. - -This is a sibling project to the project [accetto/debian-vnc-xfce-g3][accetto-github-debian-vnc-xfce-g3]. - -There is also the sibling project [accetto/ubuntu-vnc-xfce-g3][accetto-github-ubuntu-vnc-xfce-g3] containing similar images based on [Ubuntu 22.04 LTS and 20.04 LTS][docker-ubuntu]. - -### TL;DR - -#### Installing packages - -I try to keep the images slim. Consequently you can encounter missing dependencies while adding more applications yourself. You can track the missing libraries on the [Debian Packages Search][debian-packages-search] page and install them subsequently. - -You can also try to fix it by executing the following (the default `sudo` password is **headless**): +This GitHub project folder contains resources used by building Debian images available on Docker Hub in the repository [accetto/debian-vnc-xfce-vscode-g3][this-docker]. -```shell -### apt cache needs to be updated only once -sudo apt-get update - -sudo apt --fix-broken install -``` - -#### Shared memory size +This [User guide][this-user-guide] describes the images and how to use them. -Note that some applications require larger shared memory than the default 64MB. Using 256MB usually solves crashes or strange behavior. - -You can check the current shared memory size by executing the following command inside the container: - -```shell -df -h /dev/shm -``` - -The older sibling Wiki page [Firefox multi-process][that-wiki-firefox-multiprocess] describes several ways, how to increase the shared memory size. - -#### Extending images - -The provided example file `Dockerfile.extend` shows how to use the images as the base for your own images. - -Your concrete `Dockerfile` may need more statements, but the concept should be clear. - -The compose file `example.yml` shows how to switch to another non-root user and how to set the VNC password and resolution. - -#### Building images - -The fastest way to build the images: +### Building images ```shell ### PWD = project root @@ -104,275 +31,61 @@ The fastest way to build the images: ./ci-builder.sh all group complete-vscode ``` -You can still execute the individual hook scripts as before (see the folder /docker/hooks/). However, the provided utilities builder.sh and ci-builder.sh are more convenient. Before pushing the images to the Docker Hub you have to prepare and source the file secrets.rc (see example-secrets.rc). The script builder.sh builds the individual images. The script ci-builder.sh can build various groups of images or all of them at once. Check the [builder-utility-readme][this-builder-readme], [local-building-example][this-readme-local-building-example] and [sibling Wiki][sibling-wiki] for more information. - -Note that selected features that are enabled by default can be explicitly disabled via environment variables. This allows to build even smaller images by excluding, for example, `noVNC`. See the [local-building-example][this-readme-local-building-example] for more information. - -#### Sharing devices - -Sharing the audio device for video with sound works only with `Chromium` and only on Linux: - -```shell -docker run -it -P --rm \ - --device /dev/snd:/dev/snd:rw \ - --group-add audio \ -accetto/debian-vnc-xfce-vscode-g3:chromium -``` - -Sharing the display with the host works only on Linux: - -```shell -xhost +local:$(whoami) - -docker run -it -P --rm \ - -e DISPLAY=${DISPLAY} \ - --device /dev/dri/card0 \ - -v /tmp/.X11-unix:/tmp/.X11-unix:rw \ - accetto/debian-vnc-xfce-vscode-g3:latest --skip-vnc - -xhost -local:$(whoami) -``` - -Sharing the X11 socket with the host works only on Linux: - -```shell -xhost +local:$(whoami) - -docker run -it -P --rm \ - --device /dev/dri/card0 \ - -v /tmp/.X11-unix:/tmp/.X11-unix:rw \ - accetto/debian-vnc-xfce-vscode-g3:latest - -xhost -local:$(whoami) -``` - -### Description - -This is the **third generation** (G3) of my headless images. The **second generation** (G2) contains the GitHub repository [accetto/xubuntu-vnc-novnc][accetto-github-xubuntu-vnc-novnc]. The **first generation** (G1) contains the GitHub repository [accetto/ubuntu-vnc-xfce][accetto-github-ubuntu-vnc-xfce]. - -**Attention:** If you will build an image containing the [Chromium Browser][chromium], then the browser will run in the `--no-sandbox` mode. You should be aware of the implications. The image is intended for testing and development. - -**Attention:** If you will build an image containing the [Firefox][firefox] browser, then the browser will run in the `multi-process` mode. Be aware, that this mode requires larger shared memory (`/dev/shm`). At least 256MB is recommended. Please check the **Firefox multi-process** page in this older [sibling Wiki][that-wiki-firefox-multiprocess] for more information and the instructions, how to set the shared memory size in different scenarios. - -The main features and components of the images in the default configuration are: - -- utilities **ping**, **wget**, **sudo** (Debian distribution) -- current version of JSON processor [jq][jq] -- light-weight [Xfce][xfce] desktop environment (Debian distribution) -- current version of high-performance [TigerVNC][tigervnc] server and client -- current version of [noVNC][novnc] HTML5 clients (full and lite) (TCP port **6901**) -- popular text editor [nano][nano] (Debian distribution) -- lite but advanced graphical editor [mousepad][mousepad] (Debian distribution) -- current version of [tini][tini] as the entry-point initial process (PID 1) -- support for overriding both the container user account and its group -- support of **version sticker** (see below) -- optionally the current version of [Chromium Browser][chromium] open-source web browser (Debian distribution) -- optionally the current version of [Firefox ESR (Extended Support Release)][firefox] web browser and optionally also some additional **plus features** described in the [sibling project README][sibling-readme-xfce-firefox] - -All images include the current version of the free open-source programming editor [Visual Studio Code][vscode]. - -The history of notable changes is documented in the [CHANGELOG][this-changelog]. - -![container-screenshot][this-screenshot-container] - -### Image tags - -The following image tags on the **Docker Hub** are regularly rebuilt: - -- `latest` implements VNC and noVNC -- `chromium` adds [Chromium Browser][chromium] -- `firefox` adds [Firefox][firefox] with the **plus features** (described in the [sibling project README][sibling-readme-xfce-firefox]) - -Clicking on the version sticker badge in the [README on Docker Hub][this-readme-dockerhub] reveals more information about the actual configuration of the image. - -### Ports - -Following **TCP** ports are exposed by default: - -- **5901** is used for access over **VNC** -- **6901** is used for access over [noVNC][novnc] - -The VNC/noVNC default ports and also some other parameters can be overridden several ways as it is described in the [sibling image README file][sibling-readme-xfce]. - -### Volumes - -The containers do not create or use any external volumes by default. - -Both **named volumes** and **bind mounts** can be used. More about volumes can be found in [Docker documentation][docker-doc] (e.g. [Manage data in Docker][docker-doc-managing-data]). - -However, the container's mounting point `/srv/projects/` is intended for sharing the projects between the container and the host computer: - -```shell -docker run -v /my_local_projects:/srv/projects ... - -### or using the newer syntax -docker run --mount source=/my_local_projects,target=/srv/projects ... -``` - -### Version sticker - -Version sticker serves multiple purposes that are closer described in the [sibling Wiki][sibling-wiki-version-stickers]. Note that the usage of the version sticker has changed between the generations of images. - -The **short version sticker value** describes the version of the image and it is persisted in its **label** during the build-time. It is also shown as its **badge** in the README file. - -The **verbose version sticker value** is used by the CI builder to decide if the image needs to be refreshed. It describes the actual configuration of the essential components of the image. It can be revealed by clicking on the version sticker badge in the README file. - -The version sticker values are generated by the script `version_sticker.sh`, which is deployed into the startup directory `/dockerstartup`. The script will show a short help if executed with the argument `-h`. There is also a convenient `Version Sticker` launcher on the container desktop. - -## Using headless containers - -There are two ways, how to use the containers created from this image. - -All containers are accessible by a VNC viewer (e.g. [TigerVNC][tigervnc] or [TightVNC][tightvnc]). - -The default `VNC_PORT` value is `5901`. The default `DISPLAY` value is `:1`. The default VNC password (`VNC_PW`) is `headless`. - -The containers that are created from the images built with the **noVNC feature** can be also accessed over [noVNC][noVNC] by any web browser supporting HTML5. - -The default `NOVNC_PORT` value is `6901`. The noVNC password is always identical to the VNC password. - -There are several ways of connecting to headless containers and the possibilities also differ between the Linux and Windows environments, but usually it is done by mapping the VNC/noVNC ports exposed by the container to some free TCP ports on its host system. - -For example, the following command would map the VNC/noVNC ports `5901/6901` of the container to the TCP ports `25901/26901` on the host: - -```shell -docker run -p 25901:5901 -p 26901:6901 ... -``` - -If the container would run on the local computer, then it would be accessible over **VNC** as `localhost:25901` and over **noVNC** as `http://localhost:26901`. - -If it would run on the remote server `mynas`, then it would be accessible over **VNC** as `mynas:25901` and over **noVNC** as `http://mynas:26901`. - -The image offers two [noVNC][novnc] clients - **lite client** and **full client**. Because the connection URL differs slightly in both cases, the container provides a **simple startup page**. - -The startup page offers two hyperlinks for both noVNC clients: - -- **noVNC Lite Client** (`http://mynas:26901/vnc_lite.html`) -- **noVNC Full Client** (`http://mynas:26901/vnc.html`) - -It is also possible to provide the password through the links: - -- `http://mynas:26901/vnc_lite.html?password=headless` -- `http://mynas:26901/vnc.html?password=headless` - -### Overriding environment variables - -If the environment variable `FEATURES_OVERRIDING_ENVV=1`, which is the case by default, then the container startup script will look for the file `$HOME/.override/.override_envv.rc` and source all the lines that begin with the string 'export ' at the first position and contain the '=' character. - -You can provide the overriding file from outside the container using *bind mounts* or *volumes*. +Refer to the main [README][this-readme] file for more information about the building subject. -This feature allows overriding or adding environment variables at the **container startup-time**. -It means, even after the container has already been created. +### Remarks -You can disable this behavior by setting the variable `FEATURES_OVERRIDING_ENVV` to zero when the container is created or the image is built. - -The lines that have been actually sourced can be reported into the container's log if the startup parameter `--verbose` or `--debug` is provided. - -### Overriding VNC/noVNC parameters - -This image supports several ways of overriding the VNC/noVNV parameters. The [sibling image README file][sibling-readme-xfce] describes how to do it. - -### Container user account - -The [sibling README file][sibling-readme-xfce] describes how the container user account and its group are created and how they can be overridden. It also explains the user permissions and ownership. - -### Running containers in background or foreground - -The [sibling image README file][sibling-readme-xfce] describes how to run the containers in the background (detached) of foreground (interactively). - -### Startup options and help +This is a sibling project to the project [accetto/debian-vnc-xfce-g3][accetto-github-debian-vnc-xfce-g3]. -The startup options and help are also described in the [sibling image README file][sibling-readme-xfce]. +There is also another sibling project [accetto/ubuntu-vnc-xfce-g3][accetto-github-ubuntu-vnc-xfce-g3] containing images based on [Ubuntu 22.04 LTS and 20.04 LTS][docker-ubuntu]. -## Issues, Wiki and Discussions +This is the **third generation** (G3) of my headless images. +The **second generation** (G2) contains the GitHub repository [accetto/xubuntu-vnc-novnc][accetto-github-xubuntu-vnc-novnc]. +The **first generation** (G1) contains the GitHub repository [accetto/ubuntu-vnc-xfce][accetto-github-ubuntu-vnc-xfce]. -If you have found a problem or you just have a question, please check the [Issues][this-issues], the [sibling Issues][sibling-issues] and the [sibling Wiki][sibling-wiki] first. Please do not overlook the closed issues. +### Getting help -If you do not find a solution, you can file a new issue. The better you describe the problem, the bigger the chance it'll be solved soon. +If you've found a problem or you just have a question, please check the [User guide][this-user-guide], [Issues][this-issues] and [sibling Wiki][sibling-wiki] first. +Please do not overlook the closed issues. -If you have a question or an idea and you don't want to open an issue, you can use the [sibling Discussions][sibling-discussions]. +If you do not find a solution, you can file a new issue. +The better you describe the problem, the bigger the chance it'll be solved soon. -## Credits +If you have a question or an idea and you don't want to open an issue, you can also use the [sibling Discussions][sibling-discussions]. -Credit goes to all the countless people and companies, who contribute to open source community and make so many dreamy things real. +### Diagrams -## Diagrams +Diagram of the multi-staged Dockerfile used for building multiple images. -### Dockerfile.xfce.vscode +The actual content of a particular image build is controlled by the *feature variables*. ![Dockerfile.xfce.vscode stages][this-diagram-dockerfile-stages-vscode] *** - +[this-user-guide]: https://accetto.github.io/user-guide-g3/ -[this-changelog]: https://github.com/accetto/headless-coding-g3/blob/master/CHANGELOG.md -[this-github]: https://github.com/accetto/headless-coding-g3/ -[this-issues]: https://github.com/accetto/headless-coding-g3/issues -[this-readme-dockerhub]: https://hub.docker.com/r/accetto/debian-vnc-xfce-vscode-g3 -[this-readme-project]: https://github.com/accetto/headless-coding-g3/blob/master/README.md +[this-readme]: https://github.com/accetto/headless-coding-g3/blob/master/README.md -[this-builder-readme]: https://github.com/accetto/headless-coding-g3/blob/master/readme-builder.md -[this-readme-local-building-example]: https://github.com/accetto/headless-coding-g3/blob/master/readme-local-building-example.md +[this-changelog]: https://github.com/accetto/headless-coding-g3/blob/master/CHANGELOG.md - +[this-issues]: https://github.com/accetto/headless-coding-g3/issues [accetto-github-debian-vnc-xfce-g3]: https://github.com/accetto/debian-vnc-xfce-g3 + [accetto-github-ubuntu-vnc-xfce-g3]: https://github.com/accetto/ubuntu-vnc-xfce-g3 [sibling-discussions]: https://github.com/accetto/ubuntu-vnc-xfce-g3/discussions -[sibling-issues]: https://github.com/accetto/ubuntu-vnc-xfce-g3/issues -[sibling-readme-xfce]: https://github.com/accetto/ubuntu-vnc-xfce-g3/blob/master/docker/xfce/README.md -[sibling-readme-xfce-firefox]: https://github.com/accetto/ubuntu-vnc-xfce-g3/blob/master/docker/xfce-firefox/README.md -[sibling-wiki]: https://github.com/accetto/ubuntu-vnc-xfce-g3/wiki -[sibling-wiki-version-stickers]: https://github.com/accetto/ubuntu-vnc-xfce-g3/wiki/Concepts-of-dockerfiles - +[sibling-wiki]: https://github.com/accetto/ubuntu-vnc-xfce-g3/wiki [this-docker]: https://hub.docker.com/r/accetto/debian-vnc-xfce-vscode-g3/ + [this-dockerfile]: https://github.com/accetto/headless-coding-g3/blob/master/docker/Dockerfile.xfce.vscode [this-diagram-dockerfile-stages-vscode]: https://raw.githubusercontent.com/accetto/headless-coding-g3/master/docker/doc/images/Dockerfile.xfce.vscode.png -[this-screenshot-container]: https://raw.githubusercontent.com/accetto/headless-coding-g3/master/docker/doc/images/debian-vnc-xfce-vscode.jpg - - - [accetto-github-xubuntu-vnc-novnc]: https://github.com/accetto/xubuntu-vnc-novnc/ [accetto-github-ubuntu-vnc-xfce]: https://github.com/accetto/ubuntu-vnc-xfce -[that-wiki-firefox-multiprocess]: https://github.com/accetto/xubuntu-vnc/wiki/Firefox-multiprocess - - - -[docker-debian]: https://hub.docker.com/_/debian/ [docker-ubuntu]: https://hub.docker.com/_/ubuntu/ - -[debian-packages-search]: https://packages.debian.org/index - -[docker-doc]: https://docs.docker.com/ -[docker-doc-managing-data]: https://docs.docker.com/storage/ - -[chromium]: https://www.chromium.org/Home -[firefox]: https://www.mozilla.org -[jq]: https://stedolan.github.io/jq/ -[mousepad]: https://github.com/codebrainz/mousepad -[nano]: https://www.nano-editor.org/ -[novnc]: https://github.com/kanaka/noVNC -[tigervnc]: http://tigervnc.org -[tightvnc]: http://www.tightvnc.com -[tini]: https://github.com/krallin/tini -[vscode]: https://code.visualstudio.com/ -[xfce]: http://www.xfce.org - - - -[badge-github-release]: https://badgen.net/github/release/accetto/headless-coding-g3?icon=github&label=release - -[badge-github-release-date]: https://img.shields.io/github/release-date/accetto/headless-coding-g3?logo=github - - - -[badge-docker-pulls]: https://badgen.net/docker/pulls/accetto/debian-vnc-xfce-vscode-g3?icon=docker&label=pulls - -[badge-docker-stars]: https://badgen.net/docker/stars/accetto/debian-vnc-xfce-vscode-g3?icon=docker&label=stars diff --git a/readme-builder.md b/readme-builder.md index df7fcb8..853c86e 100644 --- a/readme-builder.md +++ b/readme-builder.md @@ -13,7 +13,8 @@ ## Introduction -This utility script can build and publish individual images. It can also execute the individual hook scripts of the building pipeline (`docker/hooks` folder). +This utility script can build and publish individual images. +It can also execute the individual hook scripts of the building pipeline (`docker/hooks` folder). Common usage pattern: @@ -34,7 +35,7 @@ Usage: ./builder.sh [] blend := (((nodejs|nodejs-vscode|postman|python|python-vscode)[-(chromium|firefox)]))|nodejs-current) command := (all|all-no-push)|(pre_build|build|push|post_push|cache) -The (e.g. '--no-cache') are passed to the Docker CLI commands used internally. +The (e.g. '--no-cache') are passed to the Docker CLI commands used internally. The script creates a complete execution log. ``` @@ -116,9 +117,12 @@ You can also use other ways to set the variables. ### Ensure `wget` utility -If you are on Windows, you can encounter the problem of missing `wget` utility. It is used by refreshing the `g3-cache` and it's available on Linux by default. +If you are on Windows, you can encounter the problem of missing `wget` utility. +It is used by refreshing the `g3-cache` and it's available on Linux by default. -On Windows you have generally two choices. You can build your images inside the `WSL` environment or you can download the `wget.exe` application for Windows. Make sure to update also the `PATH` environment variable appropriately. +On Windows you have generally two choices. +You can build your images inside the `WSL` environment or you can download the `wget.exe` application for Windows. +Make sure to update also the `PATH` environment variable appropriately. ## Executing complete pipeline @@ -143,7 +147,8 @@ You can skip the publishing to the **Docker Hub** by replacing the command `all` ./builder.sh postman all-no-push ``` -You can also provide additional parameters for the internally used Docker `build` command. For example: +You can also provide additional parameters for the internally used Docker `build` command. +For example: ```shell ./builder.sh postman all-no-push --no-cache @@ -152,7 +157,8 @@ You can also provide additional parameters for the internally used Docker `build ### docker build --no-cache ... ``` -The optional `` are passed only to the `pre_build` hook script, which passes them to the internally used `docker build` command. The `cache` hook script, however, doesn't use any Docker CLI commands. +The optional `` are passed only to the `pre_build` hook script, which passes them to the internally used `docker build` command. +The `cache` hook script, however, doesn't use any Docker CLI commands. ## Executing individual pipeline steps @@ -179,11 +185,14 @@ The building pipeline consists of the following steps, that can be executed also ./builder.sh postman post_push ``` -The optional `` are passed to the each individual hook script, which can pass them to the internally used Docker CLI command. The `cache` hook script, however, doesn't use any Docker CLI commands. +The optional `` are passed to the each individual hook script, which can pass them to the internally used Docker CLI command. +The `cache` hook script, however, doesn't use any Docker CLI commands. ### What about the 'cache' helper script -The `cache` hook script has been introduced in the **second version** (G3v2) of the building pipeline in the sibling project [accetto/ubuntu-vnc-xfce-g3][accetto-github-ubuntu-vnc-xfce-g3]. It refreshes the local `g3-cache`, which must be always placed inside the Docker build context. The script is also used by the `pre_build` and `build` hook scripts. +The `cache` hook script has been introduced in the **second version** (G3v2) of the building pipeline in the sibling project [accetto/ubuntu-vnc-xfce-g3][accetto-github-ubuntu-vnc-xfce-g3]. +It refreshes the local `g3-cache`, which must be always placed inside the Docker build context. +The script is also used by the `pre_build` and `build` hook scripts. The `g3-cache` and the rules for its refreshing are described separately. diff --git a/readme-ci-builder.md b/readme-ci-builder.md index c6bddac..1145c41 100644 --- a/readme-ci-builder.md +++ b/readme-ci-builder.md @@ -20,7 +20,8 @@ ## Introduction -This utility script can build and publish sets of images. It can also extract selected information from the building log. +This utility script can build and publish sets of images. +It can also extract selected information from the building log. The common usage pattern @@ -71,7 +72,8 @@ The script creates a complete execution log. The optional parameter `--no-cache` will be passed to the internally used script `builder.sh`. -The optional parameter `--log-all` will cause that the script's output will be written into the log file in all cases. Normally the command line errors or the **log processing mode** commands are not logged. +The optional parameter `--log-all` will cause that the script's output will be written into the log file in all cases. +Normally the command line errors or the **log processing mode** commands are not logged. ## Preparation @@ -148,9 +150,12 @@ You can also use other ways to set the variables. ### Ensure `wget` utility -If you are on Windows, you can encounter the problem of missing `wget` utility. It is used by refreshing the `g3-cache` and it's available on Linux by default. +If you are on Windows, you can encounter the problem of missing `wget` utility. +It is used by refreshing the `g3-cache` and it's available on Linux by default. -On Windows you have generally two choices. You can build your images inside the `WSL` environment or you can download the `wget.exe` application for Windows. Make sure to update also the `PATH` environment variable appropriately. +On Windows you have generally two choices. +You can build your images inside the `WSL` environment or you can download the `wget.exe` application for Windows. +Make sure to update also the `PATH` environment variable appropriately. ## Usage modes @@ -166,7 +171,8 @@ The **group mode** usage pattern: #### Group mode examples -The image tags can be listed in the command line. For example, all these images will be built independently of each other. +The image tags can be listed in the command line. +For example, all these images will be built independently of each other. ```shell ./ci-builder.sh all group nodejs-vscode postman-firefox python-vscode-chromium @@ -202,13 +208,16 @@ You can also use one of the **named groups**: The **family mode** is intended for an efficient building of the sets of dependent images. -**Remark:** Since the version G3v3 of the sibling project [accetto/ubuntu-vnc-xfce-g3][accetto-github-ubuntu-vnc-xfce-g3] is this mode for advanced use only. The previous images `accetto/ubuntu-vnc-xfce-g3:latest-fugo` and `accetto/ubuntu-vnc-xfce-firefox-g3:latest-plus` that used it are not published any more. The image `accetto/ubuntu-vnc-xfce-firefox-g3:latest-plus` has been renamed to `accetto/ubuntu-vnc-xfce-firefox-g3:latest`. +**Remark:** Since the version G3v3 of the sibling project [accetto/ubuntu-vnc-xfce-g3][accetto-github-ubuntu-vnc-xfce-g3] is this mode for advanced use only. +The previous images `accetto/ubuntu-vnc-xfce-g3:latest-fugo` and `accetto/ubuntu-vnc-xfce-firefox-g3:latest-plus` that used it are not published any more. +The image `accetto/ubuntu-vnc-xfce-firefox-g3:latest-plus` has been renamed to `accetto/ubuntu-vnc-xfce-firefox-g3:latest`. The dependency in this context is meant more technically than conceptually. The following example will help to understand the concept. -This project currently does not include any images that are in such a relation. Therefore it will be explained using the images from the sibling project [accetto/ubuntu-vnc-xfce-g3][accetto-github-ubuntu-vnc-xfce-g3]. +This project currently does not include any images that are in such a relation. +Therefore it will be explained using the images from the sibling project [accetto/ubuntu-vnc-xfce-g3][accetto-github-ubuntu-vnc-xfce-g3]. The image `accetto/ubuntu-vnc-xfce-firefox-g3:latest-plus` added some additional features to the image `accetto/ubuntu-vnc-xfce-firefox-g3:latest`, but otherwise were both images identical. @@ -244,7 +253,8 @@ The following command can also be used, but there would be no benefit comparing ./ci-builder.sh all family latest-chromium ``` -You can also skip the publishing to the **Docker Hub** by replacing the `all` command by the `all-no-push` one. For example: +You can also skip the publishing to the **Docker Hub** by replacing the `all` command by the `all-no-push` one. +For example: ```shell ### image 'latest-fugo' will be skipped if the 'latest' image doesn't need a re-build @@ -253,7 +263,8 @@ You can also skip the publishing to the **Docker Hub** by replacing the `all` co ### Log processing -The **log processing** mode is intended for evaluating the outcome of the latest image building session. The result are extracted from the **ci-builder log** by `grep` utility. +The **log processing** mode is intended for evaluating the outcome of the latest image building session. +The result are extracted from the **ci-builder log** by `grep` utility. The **log processing mode** usage pattern: @@ -284,7 +295,8 @@ Built new 'headless-coding-g3:postman-firefox'. #### Stickers command -The `stickers` command extracts the information about the **version stickers** of the ephemeral helper images that have been built by the `pre_build` hook script. That does not mean that the final persistent images have also been built (and optionally also published). +The `stickers` command extracts the information about the **version stickers** of the ephemeral helper images that have been built by the `pre_build` hook script. +That does not mean that the final persistent images have also been built (and optionally also published). ```shell ./ci-builder.sh log get stickers diff --git a/readme-g3-cache.md b/readme-g3-cache.md index be11a33..acf0dce 100644 --- a/readme-g3-cache.md +++ b/readme-g3-cache.md @@ -21,9 +21,12 @@ You can learn more about the concept on the sibling Wiki page ["Concepts of `g3- ### Ensure `wget` utility -If you are on Windows, you can encounter the problem of missing `wget` utility. It is used by refreshing the `g3-cache` and it's available on Linux by default. +If you are on Windows, you can encounter the problem of missing `wget` utility. +It is used by refreshing the `g3-cache` and it's available on Linux by default. -On Windows you have generally two choices. You can build your images inside the `WSL` environment or you can download the `wget.exe` application for Windows. Make sure to update also the `PATH` environment variable appropriately. +On Windows you have generally two choices. +You can build your images inside the `WSL` environment or you can download the `wget.exe` application for Windows. +Make sure to update also the `PATH` environment variable appropriately. ## Local `g3-cache` @@ -47,9 +50,11 @@ The same shared `g3-cache` is usually used also by the sibling projects, for exa ## Helper script `cache` -Both `g3-caches` are refreshed by the helper script `cache`, which is stored in the folder `docker/hooks/`. Therefore it's sometimes referenced as a hook script. +Both `g3-caches` are refreshed by the helper script `cache`, which is stored in the folder `docker/hooks/`. +Therefore it's sometimes referenced as a hook script. -The script is used by the hook scripts `pre_build` and `build`. However, it can be executed also stand-alone. +The script is used by the hook scripts `pre_build` and `build`. +However, it can be executed also stand-alone. **Remark**: The current implementation of the cache refreshing code is not thread safe and it is not intended for parallel building of multiple images. diff --git a/readme-local-building-example.md b/readme-local-building-example.md index 85eab44..b4cbeb1 100644 --- a/readme-local-building-example.md +++ b/readme-local-building-example.md @@ -105,9 +105,12 @@ You can also use other ways to set the variables. ### Ensure `wget` utility -If you are on Windows, you can encounter the problem of missing `wget` utility. It is used by refreshing the `g3-cache` and it's available on Linux by default. +If you are on Windows, you can encounter the problem of missing `wget` utility. +It is used by refreshing the `g3-cache` and it's available on Linux by default. -On Windows you have generally two choices. You can build your images inside the `WSL` environment or you can download the `wget.exe` application for Windows. Make sure to update also the `PATH` environment variable appropriately. +On Windows you have generally two choices. +You can build your images inside the `WSL` environment or you can download the `wget.exe` application for Windows. +Make sure to update also the `PATH` environment variable appropriately. ## Building pipeline @@ -120,11 +123,14 @@ The actual building pipeline consists of the following hook scripts stored in th The hook scripts are executed exactly in that order. -The **second version** (G3v2) of the pipeline introduced in the sibling project [accetto/ubuntu-vnc-xfce-g3][accetto-github-ubuntu-vnc-xfce-g3] has added also the helper script `cache`, which ist stored in the same folder. It is used by the hook scripts `pre_build` and `build` and it refreshes the local `g3-cache`. It can be also executed stand-alone. +The **second version** (G3v2) of the pipeline introduced in the sibling project [accetto/ubuntu-vnc-xfce-g3][accetto-github-ubuntu-vnc-xfce-g3] has added also the helper script `cache`, which ist stored in the same folder. +It is used by the hook scripts `pre_build` and `build` and it refreshes the local `g3-cache`. +It can be also executed stand-alone. Utilizing the local `g3-cache` brings a significant boost in the building performance and much shorter building times. -There is also the helper script `util-readme.sh`, stored in the folder `utils/`. This script can be used for preparing the `README` file for the **Docker Hub**. +There is also the helper script `util-readme.sh`, stored in the folder `utils/`. +This script can be used for preparing the `README` file for the **Docker Hub**. ## Three ways of building images @@ -138,7 +144,9 @@ Since the **second version** (G3v2) of the building pipeline introduced in the s ### Building and publishing sets of images -Building and publishing of sets of images is pretty easy. Let's say that we want to refresh the images that feature the `Postman`. We can do that by executing the following command: +Building and publishing of sets of images is pretty easy. +Let's say that we want to refresh the images that feature the `Postman`. +We can do that by executing the following command: ```shell ### PWD = project's root directory @@ -159,7 +167,9 @@ You can find more information and examples in the separate `readme` file, descri ### Building and publishing individual images -Building and publishing of individual images is also very easy. Let's say we wan to refresh the image `accetto/debian-vnc-xfce-nodejs-g3:latest`. We could execute the following command: +Building and publishing of individual images is also very easy. +Let's say we wan to refresh the image `accetto/debian-vnc-xfce-nodejs-g3:latest`. +We could execute the following command: ```shell ### PWD = project's root directory @@ -178,7 +188,8 @@ You can find more information and examples in the separate `readme` file, descri ### Step-by-step building and publishing -The building pipeline can executed also step-by-step. The hook scripts in the folder `docker/hooks/` can be executed directly or also by using the utility script `builder.sh`. +The building pipeline can executed also step-by-step. +The hook scripts in the folder `docker/hooks/` can be executed directly or also by using the utility script `builder.sh`. The script `builder.sh` is using the individual hook scripts internally. @@ -204,7 +215,9 @@ This step builds the temporary helper image and creates the following temporary - `scrap-version_sticker-verbose_previous.tmp` - `scrap-demand-stop-building` -The file `scrap-demand-stop-building` is created only if the verbose version sticker hasn't changed since the last time it has been published on the builder repository's **GitHub Gist** and if the environment variable `FORCE_BUILDING` is not set to `1`. **Its presence will block** the next hook script `build` from building a new persistent image. If you want to force the image building, you can delete this file manually. +The file `scrap-demand-stop-building` is created only if the verbose version sticker hasn't changed since the last time it has been published on the builder repository's **GitHub Gist** and if the environment variable `FORCE_BUILDING` is not set to `1`. +**Its presence will block** the next hook script `build` from building a new persistent image. +If you want to force the image building, you can delete this file manually. The other option is to set the environment variable `FORCE_BUILDING=1` **before** executing the `pre_build` script.