remove entry barriers

[markus2330]

• shell recorder link on website, more examples
• restructure web site (Docu/Dev split does not make sense as it is)
• intro dev tutorials in README.md of tutorials
• GETTINGSTARTED for devs? Collection of links to get overview
• advertise run_env, dev container and run_all_tests via Docker more (TESTING.md?, dev pages)
• rework main README.md (philosophical stuff later)
• search for doxygen https://www.doxygen.nl/manual/extsearch.html
• how to write bindings
• architecture.md
• improve big picture
• cover why writing to system needs root
• first step tutorial (get/set) with TOML
• rewrite doc/COMPILE.md to a problem-oriented tutorial (like installing without root)
• doc/TESTING.md: describe how to run kdb run_all without root
• advertisement/overview tutorial AsciiNema improvements #2742
• + video of this tutorial
• METADATA.ini tutorial
• Java beginners tutorial with maven
• run tests without root
• API docu main page

[robaerd]

For me it was the installing of elektra without root.
Installing without root requires a few cmake flags (KDB_DB_SYSTEM, CMAKE_INSTALL_PREFIX, ...) and env variables (LD_LIBRARY_PATH, ..) to be set. Although CMAKE_INSTALL_PREFIX is described in doc/COMPILE, it wasn't obvious to me which cmake flags and envs need to be set for this.
In doc/Testing.md in the section "You have some options to avoid running them as root:", following example cmake invocation is referenced: scripts/configure-home (should btw actually be scripts/dev/configure-home). This example only covers compiling and not installing (CMAKE_INSTALL_PREFIX flag is missing). Since kdb run_all is also described in doc/TESTING.md, it should, at least in my opinion, be also mentioned how to get this working without root.

The steps in doc/tutorials/run_all_tests_with_docker.md - which is actually referenced in doc/TESTING.md - describe how to install it as non-root user, but it is not mentioned that the docker images are run as non-root. So it was in the beginning a little unclear to me why these things needed to be set only here.

I would propose to:

• add a description that the docker images are run as non-root (and maybe also the reason for this).
• add a point to doc/INSTALL.md and/or doc/TESTING.md on how to install elektra without root privileges.

[markus2330]

Thank you very much for this very helpful input!

Although CMAKE_INSTALL_PREFIX is described in doc/COMPILE

Yes, I fully agree, this docu must be rewritten to a style where concrete problems are solved (like installing without root). The sole description of what the flags do is better done within the CMake-cache-variable-docu.

but it is not mentioned that the docker images are run as non-root

I hope you can improve the tutorials about Docker images 💖, you need to adapt them anyway with the changes you make (like removing the need for the Jenkins user).

docker images are run as non-root (and maybe also the reason for this).

Do you mean the reason why they run as non-root? It is best practice to run something with the minimal amount of privileges as possible.

In general: It is good if we do not assume too much knowledge about Docker or Jenkins in our docu, as many people do not have it. So I agree, that such rationale should be given.

[robaerd]

I hope you can improve the tutorials about Docker images 💖, you need to adapt them anyway with the changes you make (like removing the need for the Jenkins user).

Yes of course I will improve the tutorials about the Docker images.

[marvin-the-parrot]

[FLOSS H1]
Is the documentation label appropriate here? Or is it the case that tutorial are not considered part of the documentation?

All of the tasks in this issue will need comprehensive knowledge of the areas which the tutorials/doc is featuring.

[markus2330]

Is the documentation label appropriate here?

Yes, it is fine!

As this is the T3 task (for people that did not find something else), no assignment is necessary.

[github-actions]

I mark this stale as it did not have any activity for one year. I'll close it in two weeks if no further activity occurs. If you want it to be alive again, ping by writing a message here or create a new issue with the remainder of this issue.
Thank you for your contributions 💖

[github-actions]

I closed this now because it has been inactive for more than one year. If I closed it by mistake, please do not hesitate to reopen it or create a new issue with the remainder of this issue.
Thank you for your contributions 💖