From 43a91f3105f18e6c808d09e3c363c43de6db3900 Mon Sep 17 00:00:00 2001 From: Olivier Benz Date: Sat, 25 Feb 2023 12:04:58 +0100 Subject: [PATCH] Add README, NOTES and code of conduct --- CODE_OF_CONDUCT.md | 128 ++++++++++++++++++++++++++++++++++++ NOTES.md | 157 +++++++++++++++++++++++++++++++++++++++++++++ README.md | 115 +++++++++++++++++++++++++++++++++ 3 files changed, 400 insertions(+) create mode 100644 CODE_OF_CONDUCT.md create mode 100644 NOTES.md create mode 100644 README.md diff --git a/CODE_OF_CONDUCT.md b/CODE_OF_CONDUCT.md new file mode 100644 index 0000000..1dd8992 --- /dev/null +++ b/CODE_OF_CONDUCT.md @@ -0,0 +1,128 @@ +# Contributor Covenant Code of Conduct + +## Our Pledge + +We as members, contributors, and leaders pledge to make participation in our +community a harassment-free experience for everyone, regardless of age, body +size, visible or invisible disability, ethnicity, sex characteristics, gender +identity and expression, level of experience, education, socio-economic status, +nationality, personal appearance, race, religion, or sexual identity +and orientation. + +We pledge to act and interact in ways that contribute to an open, welcoming, +diverse, inclusive, and healthy community. + +## Our Standards + +Examples of behavior that contributes to a positive environment for our +community include: + +* Demonstrating empathy and kindness toward other people +* Being respectful of differing opinions, viewpoints, and experiences +* Giving and gracefully accepting constructive feedback +* Accepting responsibility and apologizing to those affected by our mistakes, + and learning from the experience +* Focusing on what is best not just for us as individuals, but for the + overall community + +Examples of unacceptable behavior include: + +* The use of sexualized language or imagery, and sexual attention or + advances of any kind +* Trolling, insulting or derogatory comments, and personal or political attacks +* Public or private harassment +* Publishing others' private information, such as a physical or email + address, without their explicit permission +* Other conduct which could reasonably be considered inappropriate in a + professional setting + +## Enforcement Responsibilities + +Community leaders are responsible for clarifying and enforcing our standards of +acceptable behavior and will take appropriate and fair corrective action in +response to any behavior that they deem inappropriate, threatening, offensive, +or harmful. + +Community leaders have the right and responsibility to remove, edit, or reject +comments, commits, code, wiki edits, issues, and other contributions that are +not aligned to this Code of Conduct, and will communicate reasons for +moderation decisions when appropriate. + +## Scope + +This Code of Conduct applies within all community spaces, and also applies when +an individual is officially representing the community in public spaces. +Examples of representing our community include using an official e-mail +address, posting via an official social media account, or acting as an +appointed representative at an online or offline event. + +## Enforcement + +Instances of abusive, harassing, or otherwise unacceptable behavior may be +reported to the community leaders responsible for enforcement at +. All complaints will be reviewed and investigated +promptly and fairly. + +All community leaders are obligated to respect the privacy and security of the +reporter of any incident. + +## Enforcement Guidelines + +Community leaders will follow these Community Impact Guidelines in determining +the consequences for any action they deem in violation of this Code of Conduct: + +### 1. Correction + +**Community Impact**: Use of inappropriate language or other behavior deemed +unprofessional or unwelcome in the community. + +**Consequence**: A private, written warning from community leaders, providing +clarity around the nature of the violation and an explanation of why the +behavior was inappropriate. A public apology may be requested. + +### 2. Warning + +**Community Impact**: A violation through a single incident or series +of actions. + +**Consequence**: A warning with consequences for continued behavior. No +interaction with the people involved, including unsolicited interaction with +those enforcing the Code of Conduct, for a specified period of time. This +includes avoiding interactions in community spaces as well as external channels +like social media. Violating these terms may lead to a temporary or +permanent ban. + +### 3. Temporary Ban + +**Community Impact**: A serious violation of community standards, including +sustained inappropriate behavior. + +**Consequence**: A temporary ban from any sort of interaction or public +communication with the community for a specified period of time. No public or +private interaction with the people involved, including unsolicited interaction +with those enforcing the Code of Conduct, is allowed during this period. +Violating these terms may lead to a permanent ban. + +### 4. Permanent Ban + +**Community Impact**: Demonstrating a pattern of violation of community +standards, including sustained inappropriate behavior, harassment of an +individual, or aggression toward or disparagement of classes of individuals. + +**Consequence**: A permanent ban from any sort of public interaction within +the community. + +## Attribution + +This Code of Conduct is adapted from the [Contributor Covenant][homepage], +version 2.0, available at +https://www.contributor-covenant.org/version/2/0/code_of_conduct.html. + +Community Impact Guidelines were inspired by [Mozilla's code of conduct +enforcement ladder](https://github.com/mozilla/diversity). + +[homepage]: https://www.contributor-covenant.org + +For answers to common questions about this code of conduct, see the FAQ at +https://www.contributor-covenant.org/faq. Translations are available at +https://www.contributor-covenant.org/translations. diff --git a/NOTES.md b/NOTES.md new file mode 100644 index 0000000..58363c4 --- /dev/null +++ b/NOTES.md @@ -0,0 +1,157 @@ +# Notes + +This docker stack uses modified startup scripts from +[jupyter/docker-stacks](https://github.com/jupyter/docker-stacks). +:information_source: Nevertheless, all [Docker Options](https://github.com/jupyter/docker-stacks/blob/main/docs/using/common.md#docker-options) +and [Permission-specific configurations](https://github.com/jupyter/docker-stacks/blob/main/docs/using/common.md#permission-specific-configurations) +can be used for the images of this docker stack. + +## Tweaks + +In comparison to +[pangeo-data/jupyter-earth](https://github.com/pangeo-data/jupyter-earth), these +images are tweaked as follows: + +### Jupyter startup scripts + +Shell script [/usr/local/bin/start.sh](base/scripts/usr/local/bin/start.sh) is +modified to + +* allow *bind mounting* of a home directory. + +### Jupyter startup hooks + +The following startup hooks are put in place: + +* [/usr/local/bin/start-notebook.d/populate.sh](base/scripts/usr/local/bin/start-notebook.d/populate.sh) + to populate a *bind mounted* home directory `/home/jovyan`. +* [/usr/local/bin/before-notebook.d/init.sh](base/scripts/usr/local/bin/before-notebook.d/init.sh) to + * update timezone according to environment variable `TZ`. + * add locales according to environment variable `LANGS`. + * set locale according to environment variable `LANG`. + * use custom xinitrc (Xfce). + * set font to MesloLGS NF (Xfce Terminal). + * put inital settings in place (QGIS Desktop). + * copy plugin 'Processing Saga NextGen Provider' (QGIS Desktop). + +### Custom scripts + +[/usr/local/bin/busy](base/scripts/usr/local/bin/busy) is executed during +`screen`/`tmux` sessions to update the last-activity timestamps on JupyterHub. +:information_source: This prevents the [JupyterHub Idle Culler Service](https://github.com/jupyterhub/jupyterhub-idle-culler) +from shutting down idle or long-running Jupyter Notebook servers, allowing for +unattended computations. + +### Environment variables + +**Versions** + +* `QGIS_VERSION` +* `JUPYTERHUB_VERSION` +* `JUPYTERLAB_VERSION` +* `PYTHON_VERSION` +* `GIT_VERSION` +* `OTB_VERSION` +* `TURBOVNC_VERSION` + +**GRASS GIS** + +* `GRASS_PYTHON`: Set to `/usr/bin/python3` + +Otherwise, `grass` would use `/user/local/bin/python3`. +:information_source: `grass` was built against Python and packages from the distro's package repository. + +**Orfeo Toolbox** + +* `GDAL_DRIVER_PATH`: Set to `disable` (amd64 only) +* `OTB_APPLICATION_PATH`: Set to `/usr/local/lib/otb/applications` (amd64 only) +* `PYTHONPATH`: Set to `/usr/local/lib/otb/python` (amd64 only) + +A subset of the environment variables used in [`otbenv.profile`](https://github.com/orfeotoolbox/OTB/blob/develop/Packaging/Files/otbenv.profile). + +**Miscellaneous** + +* `BASE_IMAGE`: Its very base, a [Docker Official Image](https://hub.docker.com/search?q=&type=image&image_filter=official). +* `PARENT_IMAGE`: The image it was derived from. +* `BUILD_DATE`: The date it was built (ISO 8601 format). + +### Shell + +The default shell is Zsh, further enhanced with + +* Framework: [Oh My Zsh](https://ohmyz.sh/) +* Theme: [Powerlevel10k](https://github.com/romkatv/powerlevel10k#oh-my-zsh) +* Font: [MesloLGS NF](https://github.com/romkatv/powerlevel10k#fonts) + +## Settings + +### Default + +* [Terminal IPython](base/conf/ipython/usr/local/etc/ipython/ipython_config.py): + * Only enable figure formats `svg` and `pdf` for Terminal IPython. +* [IPython kernel](base/conf/ipython/usr/local/etc/ipython/ipython_kernel_config.py): + * Only enable figure formats `svg` and `pdf` for IPython Kernel (Jupyter + Notebooks). +* [JupyterLab](base/conf/jupyterlab/usr/local/share/jupyter/lab/settings/overrides.json): + * Theme > Selected Theme: JupyterLab Dark + * Terminal > Font family: MesloLGS NF + * Python LSP Server: Example settings according to [jupyter-lsp/jupyterlab-lsp > Installation > Configuring the servers](https://github.com/jupyter-lsp/jupyterlab-lsp#configuring-the-servers) +* [Xfce xinitrc](base/conf/user/var/backups/skel/.config/xfce4/xinitrc): + * Allow users to set `LANG` in `~/.i18n` to change the system language. +* [Xfce Panel](base/conf/xfce/etc/xdg/xfce4/xfconf/xfce-perchannel-xml/xfce4-panel.xml): + * Hide 'Lock Screen' and 'Log Out...' because those kill the session. + (Removed: 'Log Out' from Applications) + (Disabled: Ctrl+Alt+Del to trigger session logout) +* [Xfce Terminal](base/conf/user/var/backups/skel/.config/xfce4/terminal/terminalrc): + * Set `FontName=MesloLGS NF 12` and `Encoding=UTF-8`. +* [QGIS Desktop](base/conf/user/var/backups/skel/.local/share/QGIS/QGIS3/profiles/default/QGIS/QGIS3.ini): + * Append `/usr/lib/python3/dist-packages` to `PYTHONPATH`. + :information_source: One distro refused to find the Python bindings to QGIS (at `/usr/lib/python3/dist-packages/qgis`)... +* Zsh + * Oh My Zsh: `~/.zshrc` + * Set PATH so it includes user's private bin if it exists + * Update last-activity timestamps while in screen/tmux session + * [Powerlevel10k](base/conf/user/var/backups/skel/.p10k.zsh): `p10k configure` + * Does this look like a diamond (rotated square)?: (y) Yes. + * Does this look like a lock?: (y) Yes. + * Does this look like a Debian logo (swirl/spiral)?: (y) Yes. + * Do all these icons fit between the crosses?: (y) Yes. + * Prompt Style: (3) Rainbow. + * Character Set: (1) Unicode. + * Show current time?: (2) 24-hour format. + * Prompt Separators: (1) Angled. + * Prompt Heads: (1) Sharp. + * Prompt Tails: (1) Flat. + * Prompt Height: (2) Two lines. + * Prompt Connection: (2) Dotted. + * Prompt Frame: (2) Left. + * Connection & Frame Color: (2) Light. + * Prompt Spacing: (2) Sparse. + * Icons: (2) Many icons. + * Prompt Flow: (1) Concise. + * Enable Transient Prompt?: (n) No. + * Instant Prompt Mode: (3) Off. + +### Customise + +* Terminal IPython: Create file `~/.ipython/profile_default/ipython_config.py` + * Valid figure formats: `png`, `retina`, `jpeg`, `svg`, `pdf`. +* IPython kernel: Create file + `~/.ipython/profile_default/ipython_kernel_config.py` + * Valid figure formats: `png`, `retina`, `jpeg`, `svg`, `pdf`. +* JupyterLab: Settings > Advanced Settings Editor +* code-server: Manage > Settings + +* Zsh + * Oh My Zsh: Edit `~/.zshrc`. + * Powerlevel10k: Run `p10k configure` or edit `~/.p10k.zsh`. + * Update command: + `git -C ${ZSH_CUSTOM:-$HOME/.oh-my-zsh/custom}/themes/powerlevel10k pull` + +## Python + +The Python version is selected as follows: + +* The latest [Python version numba is compatible with](https://numba.readthedocs.io/en/stable/user/installing.html#compatibility). + +This Python version is installed at `/user/local/bin`. diff --git a/README.md b/README.md new file mode 100644 index 0000000..5781505 --- /dev/null +++ b/README.md @@ -0,0 +1,115 @@ +[![minimal-readme compliant](https://img.shields.io/badge/readme%20style-minimal-brightgreen.svg)](https://github.com/RichardLitt/standard-readme/blob/master/example-readmes/minimal-readme.md) [![Project Status: Active – The project has reached a stable, usable state and is being actively developed.](https://www.repostatus.org/badges/latest/active.svg)](https://www.repostatus.org/#active) Donate using Liberapay + +# JupyterLab QGIS docker stack + +Multi-arch (`linux/amd64`, `linux/arm64/v8`) images: + +* [`registry.gitlab.b-data.ch/jupyterlab/qgis/base`](https://gitlab.b-data.ch/jupyterlab/qgis/base/container_registry) + +**Features** + +* **JupyterLab**: A web-based interactive development environment for Jupyter + notebooks, code, and data. The images include + * **Xfce (via noVNC + TurboVNC)**: A lightweight desktop environment for UNIX-like operating systems. + * **GRASS GIS**: A free and open source Geographic Information System (GIS). + * **Orfeo Toolbox**: An open-source project for state-of-the-art remote sensing. + :information_source: amd64 only + * **QGIS**: A free, open source, cross platform (lin/win/mac) geographical information system (GIS). + * **SAGA GIS**: A Geographic Information System (GIS) software with immense capabilities for geodata processing and analysis. + * **Git**: A distributed version-control system for tracking changes in source + code. + * **Python**: An interpreted, object-oriented, high-level programming language + with dynamic semantics. + * **Zsh**: A shell designed for interactive use, although it is also a + powerful scripting language. + +Images considered stable for QGIS versions ≥ 3.28.3 and ≥ 3.22.16 (LTR). + +**Subtags** + +* `{QGIS_VERSION,latest,ltr}-root`: Container runs as `root` + +## Table of Contents + +* [Prerequisites](#prerequisites) +* [Install](#install) +* [Usage](#usage) +* [Similar project](#similar-project) +* [Contributing](#contributing) +* [License](#license) + +## Prerequisites + +This projects requires an installation of docker. + +## Install + +To install docker, follow the instructions for your platform: + +* [Install Docker Engine | Docker Documentation > Supported platforms](https://docs.docker.com/engine/install/#supported-platforms) +* [Post-installation steps for Linux](https://docs.docker.com/engine/install/linux-postinstall/) + +## Usage + +### Build image (base) + +latest: + +```bash +cd base && docker build \ + --build-arg QGIS_VERSION=3.28.3 \ + --build-arg PYTHON_VERSION=3.10.10 \ + --build-arg GIT_VERSION=2.39.2 \ + --build-arg OTB_VERSION=8.1.1 \ + -t jupyterlab/qgis/base \ + -f Dockerfile . +``` + +### Run container + +self built: + +```bash +docker run -it --rm \ + -p 8888:8888 \ + -v $PWD:/home/jovyan \ + jupyterlab/qgis/base +``` + +from the project's GitLab Container Registries: + +* [`jupyterlab/qgis/base`](https://gitlab.b-data.ch/jupyterlab/qgis/base/container_registry) + ```bash + docker run -it --rm \ + -p 8888:8888 \ + -v $PWD:/home/jovyan \ + registry.gitlab.b-data.ch/jupyterlab/qgis/base[:MAJOR[.MINOR[.PATCH]]] + ``` + +The use of the `-v` flag in the command mounts the current working directory on +the host (`$PWD` in the example command) as `/home/jovyan` in the container. +The server logs appear in the terminal. + +## Similar project + +* [pangeo-data/jupyter-earth](https://github.com/pangeo-data/jupyter-earth) + +What makes this project different: + +1. Multi-arch: `linux/amd64`, `linux/arm64/v8` +1. Base image: [Debian](https://hub.docker.com/_/debian) instead of + [Ubuntu](https://hub.docker.com/_/ubuntu) +1. Just Python – no [Conda](https://github.com/conda/conda) / + [Mamba](https://github.com/mamba-org/mamba) + +## Contributing + +PRs accepted. + +This project follows the +[Contributor Covenant](https://www.contributor-covenant.org) +[Code of Conduct](CODE_OF_CONDUCT.md). + +## License + +[MIT](LICENSE) © 2023 b-data GmbH