mirror of
https://github.com/YunoHost/doc.git
synced 2024-09-03 20:06:26 +02:00
Update packaging_apps_intro.md
updated translation in german
This commit is contained in:
Aaron
GitHub
parent
0baeafe8e9
commit
81d3e9f293
1 changed files with 69 additions and 69 deletions
|
|
@ -9,109 +9,109 @@ routes:
|
||||||
- '/packaging_apps'
|
- '/packaging_apps'
|
||||||
---
|
---
|
||||||
|
|
||||||
This documentation is here to provide all the basic concepts and vocabulary needed to understand app packaging.
|
In dieser Dokumentation findest du alle grundlegenden Konzepte und Vokabeln, die du zum Verständnis von Anwendungspaketen benötigst.
|
||||||
|
|
||||||
We will detail what a YunoHost application package is, how it works, how to make your own package and how to find help if you need it.
|
Wir werden detailliert beschreiben, was ein YunoHost-Anwendungspaket ist, wie es funktioniert, wie du dein eigenes Paket erstellst und wie du Hilfe findest, wenn du diese benötigst.
|
||||||
|
|
||||||
|
|
||||||
## 1. Packaging philosophy
|
## 1. Paketierungs-Philosophie
|
||||||
|
|
||||||
The ability to easily install applications from a catalog is a key feature of YunoHost. While you dive in the process of YunoHost application packaging, you should remember these key principles:
|
Die Möglichkeit, Anwendungen einfach aus einem Katalog zu installieren, ist eine Schlüsselfunktion von YunoHost. Während du in den Prozess der YunoHost-Anwendungspaketierung eintauchst, solltest du dich an diese Schlüsselprinzipien erinnern:
|
||||||
|
|
||||||
- **The admin should not have a PhD in computer science to be able to install, configure and use your application**: try to assume that the admin doesn't know about advanced computer concepts;
|
- **Der Administrator sollte keinen Doktortitel in Informatik haben, um deine Anwendung installieren, konfigurieren und nutzen zu können**: Gehe davon aus, dass der Administrator keine fortgeschrittenen Computerkenntnisse hat;
|
||||||
|
|
||||||
- **Less is more**, **Keep it simple!**: don't overcrowd the admin with a dozens technical questions;
|
- **Weniger ist mehr**, **Keep it simple!**: überfrachte den Administrator nicht mit Dutzenden von technischen Fragen;
|
||||||
|
|
||||||
- **Things should work out of the box**: for example, the admin should not have to manually finish the installation process by manually filling in database credentials;
|
- **Die Dinge sollten sofort funktionieren**: zum Beispiel sollte der Administrator den Installationsprozess nicht manuell abschließen müssen, indem er die Zugangsdaten für die Datenbank manuell ausfüllt;
|
||||||
|
|
||||||
- YunoHost app packaging is **not just about installing** sources and dependencies: it's also about maintenance (upgrade, backup...) and integrating the app in the YunoHost ecosystem (NGINX, SSO/LDAP, Fail2Ban, application catalog, UI/UX...)
|
- Bei der Paketierung von YunoHost-Apps geht es **nicht nur um die Installation** von Quellen und Abhängigkeiten: Es geht auch um Wartung (Upgrade, Backup...) und die Integration der App in das YunoHost-Ökosystem (NGINX, SSO/LDAP, Fail2Ban, Anwendungskatalog, UI/UX...)
|
||||||
|
|
||||||
|
|
||||||
## 2. Prerequisites
|
## 2. Voraussetzungen
|
||||||
|
|
||||||
Before diving in, this documentation assumes that:
|
In dieser Dokumentation wird vorausgesetzt, dass:
|
||||||
|
|
||||||
1. You already are a YunoHost admin yourself and already know what the install workflow looks like;)
|
1. Du selbst bereits YunoHost-Administrator bist und weißt, wie der Installationsablauf aussieht;)
|
||||||
2. You are somewhat familiar with (or are willing to learn) system administration and bash programming;
|
2. Du bist einigermaßen vertraut mit Systemadministration und Bash-Programmierung (oder bereit, diese zu lernen);
|
||||||
3. You are somewhat familiar with (or are willing to learn) Git;
|
3. Du bist einigermaßen vertraut mit Git (oder bereit, es zu lernen);
|
||||||
4. You are comfortable with tinkering and debugging computer stuff in general.
|
4. Du hast Spaß am Basteln und am Debuggen von Computerkram im Allgemeinen.
|
||||||
|
|
||||||
You are also encouraged to join the [app packaging chatroom](/chat_rooms) to ask any question you may have!
|
Du bist auch eingeladen, dem [app packaging chatroom](/chat_rooms) beizutreten, um alle Fragen zu stellen, die du vielleicht hast!
|
||||||
|
|
||||||
At some point, you will also want to have a dev/test environment, either using [VirtualBox](/packaging_apps_virtualbox) or [LXC/ynh-dev](https://github.com/yunohost/ynh-dev) which is meant for the core but can totally be used for developping apps. You can also setup a dev/test VPS on your favourite hosting provider, or even develop on your prod if you like to live dangerously;).
|
Irgendwann wirst du auch eine Entwicklungs-/Testumgebung haben wollen, entweder mit [VirtualBox](/packaging_apps_virtualbox) oder [LXC/ynh-dev](https://github.com/yunohost/ynh-dev), das für den Kern gedacht ist, aber durchaus auch für die Entwicklung von Anwendungen verwendet werden kann. Du kannst auch einen Dev/Test-VPS bei deinem bevorzugten Hosting-Anbieter einrichten oder sogar auf deinem Prod entwickeln, wenn du gerne gefährlich lebst ;).
|
||||||
|
|
||||||
## 3. Notes about the history of YunoHost's app packaging
|
## 3. Anmerkungen zur Geschichte der YunoHost-App-Pakete
|
||||||
|
|
||||||
Many things in YunoHost, and YunoHost app packaging format, are historical or were designed in an organic fashion. Thus some aspects may legitimately feel old.
|
Viele Dinge bei YunoHost und dem YunoHost App-Packaging-Format sind historisch bedingt oder wurden auf organische Art und Weise entwickelt. Daher können sich einige Aspekte zu Recht alt anfühlen.
|
||||||
|
|
||||||
The **"v0" of app packaging** consisted in writing raw bash scripts with no real standardization/constrain.
|
Die **"v0" der App-Paketierung** bestand aus dem Schreiben roher Bash-Skripte ohne echte Standardisierung/Einschränkung.
|
||||||
|
|
||||||
Over time, recurrent steps (such as installing dependencies with apt, or setting up the NGINX config) where formalized into standardized bash functions, aka "helpers". This pretty much marked **the beginning of the "v1" packaging era**.
|
Mit der Zeit wurden wiederkehrende Schritte (wie die Installation von Abhängigkeiten mit apt oder die Einrichtung der NGINX-Konfiguration) in standardisierte Bash-Funktionen, auch "Helfer" genannt, formalisiert. Dies markierte so ziemlich **den Beginn der Ära der "v1"-Pakete**.
|
||||||
|
|
||||||
Various tools were implemented to test the app and standardize their behavior.
|
Verschiedene Tools wurden implementiert, um die Anwendung zu testen und ihr Verhalten zu standardisieren.
|
||||||
|
|
||||||
After a while, a set of common practices and conventions emerged and is somewhat reflected and maintain in the `example_ynh` template application. While it is tempting for dev-oriented folks to change variable naming schemes or refactorize the structure of scripts, it turns out that it is even more important to stick to the common set of practices (even though arbitrary and not elegant) to ease the maintenance of all apps by any member of the packaging community accross all repos!
|
Nach einer Weile bildete sich eine Reihe von gemeinsamen Praktiken und Konventionen heraus, die sich in der `example_ynh`-Vorlagenanwendung widerspiegeln und erhalten. Während es für Entwickler verlockend ist, die Namensschemata von Variablen zu ändern oder die Struktur von Skripten zu refaktorisieren, stellt sich heraus, dass es sogar noch wichtiger ist, sich an die gemeinsamen Praktiken zu halten (auch wenn sie willkürlich und nicht elegant sind), um die Wartung aller Anwendungen durch jedes Mitglied der Paketierungsgemeinschaft über alle Repos hinweg zu erleichtern!
|
||||||
|
|
||||||
Nevertheless, even though helpers existed, the inherent structure of apps was hard and boring to maintain with too many redundant pieces of code or filled with funky historical conventions. **A new v2 format** [has been designed and added to YunoHost 11.1 in early 2023](https://github.com/YunoHost/yunohost/pull/1289) in the hope to modernize and simplify app packaging and improve the UI/UX of YunoHost.
|
Nichtsdestotrotz war die inhärente Struktur von Anwendungen, auch wenn es Helfer gab, schwer und langweilig zu warten, da sie zu viele redundante Codestücke enthielt oder mit seltsamen historischen Konventionen gefüllt war. **Ein neues v2-Format** [wurde entworfen und zu YunoHost 11.1 Anfang 2023 hinzugefügt] (https://github.com/YunoHost/yunohost/pull/1289) in der Hoffnung, das App-Packaging zu modernisieren und zu vereinfachen und die UI/UX von YunoHost zu verbessern.
|
||||||
|
|
||||||
However, [**a future v3 format** has yet to come](https://github.com/YunoHost/issues/issues/2136) to further simplify app packaging (such as taking care of NGINX/systemd/... configurations, removing the need to manually write remove/backup/restore scripts, etc.)
|
Es wird jedoch [**ein zukünftiges v3-Format**](https://github.com/YunoHost/issues/issues/2136) geben, um die Paketierung von Anwendungen weiter zu vereinfachen (z.B. durch die Übernahme von NGINX/systemd/... Konfigurationen, die Beseitigung der Notwendigkeit, Skripte zum Entfernen/Backup/Wiederherstellen manuell zu schreiben, usw.)
|
||||||
|
|
||||||
|
|
||||||
## 4. General overview of a YunoHost app structure
|
## 4. Allgemeiner Überblick über die Struktur einer YunoHost-App
|
||||||
|
|
||||||
A YunoHost app consists in a Git repository. We encourage you to have a look at those code repository to get familiar witch app repository structures:
|
Eine YunoHost-Anwendung besteht aus einem Git-Repository. Wir empfehlen dir, einen Blick auf diese Code-Repositories zu werfen, um dich mit der Struktur der App-Repositories vertraut zu machen:
|
||||||
- [the `helloworld_ynh` app](https://github.com/YunoHost-Apps/helloworld_ynh)
|
- [die `helloworld_ynh` App](https://github.com/YunoHost-Apps/helloworld_ynh)
|
||||||
- [the `example_ynh` app](https://github.com/YunoHost/example_ynh) which illustrates all common features and recommended formatting
|
- [die `example_ynh` app](https://github.com/YunoHost/example_ynh), die alle gängigen Funktionen und empfohlenen Formatierungen veranschaulicht
|
||||||
- your favourite "real-life" app in the [YunoHost-Apps organization](https://github.com/orgs/YunoHost-Apps/repositories)
|
- Deine bevorzugte "Real-Life"-App in der [YunoHost-Apps-Organisation](https://github.com/orgs/YunoHost-Apps/repositories)
|
||||||
|
|
||||||
Among the file contained in a package, the most important ones are:
|
Unter den in einem Paket enthaltenen Dateien sind die wichtigsten:
|
||||||
|
|
||||||
- the **app manifest** `manifest.toml` <small>(or `.json` in the past)</small>
|
- das **Anwendungsmanifest** `manifest.toml` <small>(oder `.json` in der Vergangenheit)</small>
|
||||||
- this can be seen as the ID card of the application, containing various metadatas.
|
- Dies kann als der Ausweis der Anwendung angesehen werden, der verschiedene Metadaten enthält.
|
||||||
- it also contains the questions asked during the installation of the app.
|
- Sie enthält auch die Fragen, die bei der Installation der Anwendung gestellt werden.
|
||||||
- and a bunch of "resources" to initialize, such as sources to download or apt dependencies to install
|
- und eine Reihe von "Ressourcen" zum Initialisieren, wie z.B. herunterzuladende Quellen oder zu installierende apt-Abhängigkeiten
|
||||||
- **scripts/** contains a bunch of bash scripts corresponding to actions exposed in YunoHost
|
- **scripts/** enthält eine Reihe von Bash-Skripten, die den in YunoHost angebotenen Aktionen entsprechen
|
||||||
- `_common.sh`: common variables or custom functions included in other scripts
|
- `_common.sh`: gemeinsame Variablen oder eigene Funktionen, die in anderen Skripten enthalten sind
|
||||||
- `install`/`remove`: the install and remove procedure
|
- `install`/`remove`: die Installations- und Deinstallationsprozedur
|
||||||
- `upgrade`: the upgrade procedure
|
- `upgrade`: die Upgrade-Prozedur
|
||||||
- `backup`/`restore`: the backup/restore procedures
|
- `backup`/`restore`: die Sicherungs-/Wiederherstellungsprozeduren
|
||||||
- (`change_url`): changing where the app is installed in terms of web access url
|
- (`change_url`): Ändern des Ortes, an dem die Anwendung in Bezug auf die Webzugriffsurl installiert ist
|
||||||
- **conf/** contains a bunch of configuration templates used when installing the app. Here are some example of commonly found files:
|
- **conf/** enthält eine Reihe von Konfigurationsvorlagen, die bei der Installation der Anwendung verwendet werden. Hier sind einige Beispiele für häufig vorkommende Dateien:
|
||||||
- `nginx.conf`: the NGINX (=web server) configuration template for this app
|
- `nginx.conf`: die NGINX (=Webserver) Konfigurationsvorlage für diese Anwendung
|
||||||
- `systemd.service`: the systemd service configuration template for this app
|
- systemd.service": die Konfigurationsvorlage für den systemd-Dienst für diese Anwendung
|
||||||
- `config.json/yaml/???`: the app's configuration template
|
- config.json/yaml/???`: die Konfigurationsvorlage für die Anwendung
|
||||||
|
|
||||||
Roughly speaking, the install itself generally consists of the following operations (though these may vary depending on the complexity and technologies used by the app) - not necessarily in that exact order:
|
Grob gesagt besteht die Installation selbst im Allgemeinen aus den folgenden Vorgängen (die jedoch je nach Komplexität und von der App verwendeten Technologien variieren können) - nicht unbedingt in dieser genauen Reihenfolge:
|
||||||
|
|
||||||
1. YunoHost fetches the package's Git repository
|
1. YunoHost holt das Git-Repository des Pakets
|
||||||
2. YunoHost asks to the admin the install questions defined in `manifest.toml`
|
2. YunoHost stellt dem Administrator die in `manifest.toml` definierten Fragen zur Installation
|
||||||
3. The admin fills the form and starts the install
|
3. Der Administrator füllt das Formular aus und startet die Installation
|
||||||
4. YunoHost provisions a bunch of technical prerequisites (called 'resources') such as:
|
4. YunoHost stellt eine Reihe von technischen Voraussetzungen (genannt 'Ressourcen') bereit, wie z.B.:
|
||||||
- initializes the app'skey/value store `settings.yml` with the admin's answers to the install form
|
- Initialisierung des Schlüssel/Wertspeichers der Anwendung `settings.yml` mit den Antworten des Administrators auf das Installationsformular
|
||||||
- creates a UNIX system user for this app
|
- legt einen UNIX-Systembenutzer für diese Anwendung an
|
||||||
- install apt dependencies needed for this app
|
- installiert apt-Abhängigkeiten, die für diese Anwendung benötigt werden
|
||||||
- picks up a port for internal reverse-proxying
|
- wählt einen Port für internes Reverse-Proxying aus
|
||||||
- initializes an empty SQL database
|
- initialisiert eine leere SQL-Datenbank
|
||||||
- configures SSOwat permissions
|
- konfiguriert SSOwat-Berechtigungen
|
||||||
- ...
|
- ...
|
||||||
5. The actual app's `install` script is ran and typically does:
|
5. Das eigentliche Skript `Install` wird ausgeführt und erledigt in der Regel:
|
||||||
- fetch and deploy the app sources
|
- Holen und Bereitstellen der App-Quellen
|
||||||
- configure the app (typically DB credentials, internal reverse-proxy port...)
|
- die App konfigurieren (typischerweise DB-Anmeldedaten, interner Reverse-Proxy-Port...)
|
||||||
- add the NGINX configuration
|
- Hinzufügen der NGINX-Konfiguration
|
||||||
- add the systemd configuration the app's daemon
|
- Hinzufügen der systemd-Konfiguration für den Daemon der Anwendung
|
||||||
- starts the app daemon
|
- Startet den Daemon der Anwendung
|
||||||
- various finialization tweaks
|
- verschiedene Feinabstimmungen zur Fertigstellung
|
||||||
6. ???
|
6. ???
|
||||||
7. Application is ready to use!
|
7. Die Anwendung ist einsatzbereit!
|
||||||
|
|
||||||
|
|
||||||
## 5. Creating your very first YunoHost package
|
## 5. Erstellen deines allerersten YunoHost-Pakets
|
||||||
|
|
||||||
Unless you really want to start from scratch or from [`example_ynh`](https://github.com/YunoHost/example_ynh), one common practice is to identify an app similar to the one you're trying to package - typically because it relies on the same technologies - clone the corresponding code repository, and adapt the various files.
|
Wenn du nicht wirklich bei Null anfangen willst oder von [`example_ynh`](https://github.com/YunoHost/example_ynh), ist eine gängige Praxis, eine Anwendung zu identifizieren, die derjenigen ähnlich ist, die du zu paketieren versuchst - typischerweise, weil du dich auf die gleichen Technologien stützt -, das entsprechende Code-Repository zu klonen und die verschiedenen Dateien anzupassen.
|
||||||
|
|
||||||
TODO/FIXME : here we should list a bunch of well-knowh apps for classic technologies
|
TODO/FIXME : hier sollten wir eine Reihe von bekannten Anwendungen für klassische Technologien auflisten
|
||||||
|
|
||||||
- PHP apps:
|
- PHP-Anwendungen:
|
||||||
- NodeJS apps:
|
- NodeJS-Apps:
|
||||||
- Python apps:
|
- Python-Apps:
|
||||||
- ???
|
- ???
|
||||||
|
|
|
||||||
Loading…
Add table
Reference in a new issue