Icinga Web Development Guide

[lippserd]

Hi,

Since we're heavily lacking documentation on how Icinga Web works and how to get started with module development, I want to elaborate what's necessary for a useful guide. I think it makes sense that we settle on the index here and create the contents in a new repository, e.g. Icinga/web-development.

The following is an abstract of the main topics the guide should cover. Please add your feedback.
What's missing? What is not necessary? What should be explained in detail? ...

Icinga Web Development Guide

Introduction

We should start off with a little explanation on how Icinga web development looks like and which layers are necessary in order to build a web application:

• Explain frontend development (client-side)
• Explain backend development (server-side)
• Explain storage features (files, database)

Programming, Markup and Database Languages

The guide should explain our used languages, i.e.

Sever-side

• PHP 5.6+, preferably PHP7

Client-side

• JavaScript: ES5 (ES6 once we updated our code base)

Markup

• HTML5
• CSS3

Storage

• INI and JSON files
• MySQL
• PostgreSQL

Browser, OS and Web Server Support

The guide should state which browsers, operating systems and web servers the Icinga web ecosystem supports.

PHP and JavaScript Style Guide

Of course, it is never bad to mention the style guides somewhere.

Basics and Technologies

Before deep diving into writing code, we should explain necessary basics and technologies:

• HTTP protocol
  • This may include an explanation for our special HTTP headers and their handling, but there may also be an extra chapter for this
• Cookies
  • This may include information about our cookies and their handling, but there may also be an extra chapter for this
• Ajax
• MVC
• JavaScript and CSS delivery
• X-column layout
• URL handling
• Form redirects
• Flow of requests, i.e. first request is a full-page load including the delivery of JavaScript and CSS and every subsequent request is AJAX
• Convention over configuration
• Translation

Git

This chapter should cover branch naming conventions and workflows, commit message anatomy and provide a cheat sheet for common Git magic that we use every day, e.g. squash, rebase, interactive rebase, git add -p.

SQL

We follow some conventions when designing databases and learned best practices during our developments which are definitely worth sharing.

Development Environment

We should have a dedicated chapter for setting up a dev environment also integrating XDebug. I do think that this will be a docker setup.

Development

This is an incomplete list of topics which the development chapter should cover, and it also only lists the main topics for the moment:

• Conventions, e.g. naming, directory structure, meta information
• Controllers
• Auto-refresh
• Views
• Custom CSS
• Forms
• Configuration
• Menu
• Dashboards
• Database access
• Permissions and restrictions
• Hooks
• Translation
• Custom JS
• CLI

/cc @nbuchwitz @Mikesch-mp @mcktr @patrickpr @nunofernandes @archandha @cstegm @LordHepipud @friesoft @plsatin @b0e @attachmentgenie @wols @tobias-urdin

[attachmentgenie]

great initiative, seems like a comprehensive list already

[nbuchwitz]

Thanks for taking the initiative! The lists looks already very compressive. Maybe it's worth mentioning which frameworks and libraries already exist in the Icinga ecosystem (IPL, react, JS frameworks etc.)

[lippserd]

Thanks for taking the initiative! The lists looks already very compressive. Maybe it's worth mentioning which frameworks and libraries already exist in the Icinga ecosystem (IPL, react, JS frameworks etc.)

Yeah, absolutely makes sense. Thx. I wanted to add the IPL (Icinga PHP Library) to the list anyway since we'll add docs, guides and blog posts over the next weeks as well.

[patrickpr]

Hi, Nice idea. For now I don't see anything to add. For the dev environment, I prefer using virtual machines instead of docker and I can provide description/process/VM  of my environment. Regards, Patrick Proy Le 23/03/2020 à 22:12, Eric Lippmann a écrit :

…

Hi, Since we're heavily lacking documentation on how Icinga Web works and how to get started with module development, I want to elaborate what's necessary for a useful guide. I think it makes sense that we settle on the index here and create the contents in a new repository, e.g. *Icinga/web-development*. The following is an abstract of the main topics the guide should cover. Please add your feedback. What's missing? What is not necessary? What should be explained in detail? ... Icinga Web Development Guide Introduction We should start off with a little explanation on how Icinga web development looks like and which layers are necessary in order to build a web application: * Explain frontend development (client-side) * Explain backend development (server-side) * Explain storage features (files, database) Programming, Markup and Database Languages The guide should explain our used languages, i.e. *Sever-side* * PHP 5.6+, preferably PHP7 *Client-side* * JavaScript: ES5 (ES6 once we updated our code base) *Markup* * HTML5 * CSS3 *Storage* * INI and JSON files * MySQL * PostgreSQL Browser, OS and Web Server Support The guide should state which browsers, operating systems and web servers the Icinga web ecosystem supports. PHP and JavaScript Style Guide Of course, it is never bad to mention the style guides somewhere. Basics and Technologies Before deep diving into writing code, we should explain necessary basics and technologies: * HTTP protocol o This may include an explanation for our special HTTP headers and their handling, but there may also be an extra chapter for this * Cookies o This may include information about our cookies and their handling, but there may also be an extra chapter for this * Ajax * MVC * JavaScript and CSS delivery * X-column layout * URL handling * Form redirects * Flow of requests, i.e. first request is a full-page load including the delivery of JavaScript and CSS and every subsequent request is AJAX * Convention over configuration * Translation Git This chapter should cover branch naming conventions and workflows, commit message anatomy and provide a cheat sheet for common Git magic that we use every day, e.g. squash, rebase, interactive rebase, git add -p. SQL We follow some conventions when designing databases and learned best practices during our developments which are definitely worth sharing. Development Environment We should have a dedicated chapter for setting up a dev environment also integrating XDebug. I do think that this will be a docker setup. Development This is an incomplete list of topics which the development chapter should cover, and it also only lists the main topics for the moment: * Conventions, e.g. naming, directory structure, meta information * Controllers * Auto-refresh * Views * Custom CSS * Forms * Configuration * Menu * Dashboards * Database access * Permissions and restrictions * Hooks * Translation * Custom JS * CLI /cc @nbuchwitz <https://github.com/nbuchwitz> @Mikesch-mp <https://github.com/Mikesch-mp> @mcktr <https://github.com/mcktr> @patrickpr <https://github.com/patrickpr> @nunofernandes <https://github.com/nunofernandes> @archandha <https://github.com/archandha> @cstegm <https://github.com/cstegm> @LordHepipud <https://github.com/LordHepipud> @friesoft <https://github.com/friesoft> @plsatin <https://github.com/plsatin> @b0e <https://github.com/b0e> @attachmentgenie <https://github.com/attachmentgenie> @wols <https://github.com/wols> @tobias-urdin <https://github.com/tobias-urdin> — You are receiving this because you were mentioned. Reply to this email directly, view it on GitHub <#4109>, or unsubscribe <https://github.com/notifications/unsubscribe-auth/AAWHIMWSJOBHEHYTBCY4OZDRI7GC7ANCNFSM4LSFU3LQ>.

[Mikesch-mp]

This is AWESOME

[K0nne]

That's exactly what some colleagues of me are waiting for 🙏

[mcktr]

Hi,

thanks for opening this issue and also for inviting community members for discussion. I think together with the community we establish a good development documentation.

I think it makes sense that we settle on the index here and create the contents in a new repository, e.g. Icinga/web-development.

Can we reconsider this? I would like to have the development documentation included in this repository, like it is in the repository of the core Icinga 2. I also think we should use the same approach in every project repository. Thereby new contributors know that they will always find the development documentation at a specific place, the repository where the contributor is working on.

I understand that the web repositories may differ from the core and they share a big amount of development documentation which then needs double maintenance. To tackle this problem I suggest that the main development documentation is located here, the modules than only contains documentation for their specialities and for all other they refer to the main web development documentation.

I am not against the first suggestion per se, this is only what is floating around in my head while reading with an eye on new contributors and how they search for documentation. I am open for counter opinions maybe I have one aspect not on my radar.

Best regards
Michael

[LordHepipud]

It's not as complex as an Icinga Web 2 module, but for the new Icinga for Windows tool I tried to start with a step-by-step developer guide to give some ideas on how for example a custom background daemon can be written from scratch and some function explanations.

The documentation for that is already online: Icinga for Windows Developer Guide

It is far from finished and more hands-on guides are hopefully following soon, but at least I hope this is a good start for this certain project.

Maybe We can approach Icinga Web 2 modules in a similar way?

[nilmerg]

We should try to avoid explaining topics in too much detail which are already well documented externally. This applies to the following:

• Used languages
  • That's e.g. PHP, besides mentioning its name (with a link php.org), its ecosystem (composer, packagist, etc), wanted style guide and a short description of how it's used should be enough.
  • I really don't want to explain syntax elements here.
• Basics and Technologies
  • HTTP, Cookies, XHR, MVC, etc. Yes we use them, yes we have customizations which need mentioning, but there are hopefully still more external links than actual documentation.

Things I'd like to see added:

• Custom JS
  • events and best practices handling them
  • what are behaviors, how do they work
• Custom CSS
  • Sandboxing and how/when to break out
  • Themes, what they should do, what not
  • Responsiveness, em/vh/etc VS px, generally how we utilize font-size here
• Unittests
  • How to write one
  • How to run it

--

@mcktr The basic documentation such as installation and configuration still will be kept in each repository. Development and end-user documentation however has a way more broad coverage of common topics and needs also updates due to changing technology and, well, additional chapters (over time). That's why a separate versioning system comes in handy, you can easily create different releases (versions) of documentation. Sure, we then have to ensure contributors are aware of this place but that's not a huge problem I guess. 😄

[onkobu]

I was forwarded here from issue #4296. From my point of view writing documentation is tedious and the result is always stale. I'd appreciate some structured documentation in the code. Maybe generating some formatted (HTML?) output to disk saves some IDE/ symbol backtracking to reconstruct a callstack's types in my head.

The only abstract section above would be some kind of coarse grained architecture. This is only to separate the different components and principles. It also serves as a sort of foundation for decisions: where should I put some auto-refresh or where is it discouraged.