diff --git a/doc/architecture.md b/doc/architecture.md deleted file mode 100644 index 9abe228e7d..0000000000 --- a/doc/architecture.md +++ /dev/null @@ -1,98 +0,0 @@ -# Agama's architecture - -On the surface, Agama implements a typical client-server architecture. The server offers an HTTP/ -JSON API with a WebSocket to send messages to the connected clients. The web and the command-line -interfaces, part of Agama, connect to that server. - -However, things are more complex, and the server comprises different pieces, as described in this -document. - -## Components - -On the server side, Agama is composed by: - -* **Agama server**: from a user's perspective, this is the core of Agama. It is responsible for: - * Implementing (part of) the installation logic. A good share of this logic is delegated to - **Agama YaST**. - * Offering an HTTP and WebSocket (HTTP/WS) interface. - * Making the **web-based user interface** available to the browsers. - -* **Agama YaST service**: it is written in Ruby and has direct access to YaST libraries. This - component implements complex parts, like storage and software handling. Communication with the - Agama web server happens over D-Bus. - -* **Agama D-Bus service**: implements a minimal API to allow **Agama YaST server** to talk to the web -server. It is expected to be replaced by direct communication in the future. - -On the client side, these are the main components: - -* **Web user interface (old `cockpit-agama`)**: Agama's graphical user interface. The **Agama web -server** makes this React application available to browsers. - -* **Command-Line Interface (`agama-cli`)**: it allows interaction with Agama and drives the -auto-installation process. - -* **Auto-installation (`autoinstallation`)**: it is composed of a Systemd service (`agama-auto`) and -a script that relies on `agama-cli` binary. - -The following diagram could be better, but it represents the main components and their interactions. - -```mermaid -flowchart LR - subgraph Clients - Browser - CLI - auto - end - - subgraph Agama Server - subgraph Web["Web Server"] - direction TB - UI["Web UI"] - API["HTTP/WS API"] - WS["WebSocket"] - end - - Web <--"Channel" --> Rust - end - Rust <-- "D-Bus" --> YaST["Agama YaST"] - - Browser --> UI - Browser --> API - Browser <---> WS - CLI --> API - CLI <---> WS - auto --> CLI -``` - -## Encryption - -In the case of a remote installation, the communication between the clients and the server must be -encrypted. Connecting to port 80 (HTTP) redirects the client to port 443 (HTTPS). - -About the certificate, Agama uses a self-signed certificate unless the user injects its own. - -## Authentication - -The HTTP interface allows authentication specifying the root password that will be checked -against PAM. - -On successful authentication, the server generates a [JSON Web Token][jwt] that the client -will include in the subsequent requests. The web client stores the token in an HTTP-only -cookie[^http-only] and the CLI uses a file with restricted permissions. - -[^http-only]: HTTP-only cookies cannot be accessed by client-side JavaScript. - -## Skipping the authentication - -When using Agama locally in the installation media, it would be unpleasant to ask for a password. -For that reason, Agama implements a mechanism to skip the authentication step. This mechanism is -documented in the [security document](./agama-security.md). - -## Links - -* https://bugzilla.suse.com/show_bug.cgi?id=1219688 -* https://cheatsheetseries.owasp.org/cheatsheets/JSON_Web_Token_for_Java_Cheat_Sheet.html - -[http-auth]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Authentication -[jwt]: https://jwt.io diff --git a/doc/autoyast.md b/doc/autoyast.md deleted file mode 100644 index 887c5b8c2d..0000000000 --- a/doc/autoyast.md +++ /dev/null @@ -1,436 +0,0 @@ -# AutoYaST Support - -Agama offers a mechanism to perform [unattended installations](../autoinstallation/). However, we -would like AutoYaST users to be able to use their profiles in Agama. This document describes how -Agama could support, to some extent, such profiles. - -Bear in mind that it is a living document and our plans could change as we progress. - -## What to support - -We want to point out that Agama and AutoYaST have different features. Agama is focused on the -installation and delegates further configuration to other tools. From this point of view, it is -clear that many of the sections you can find in an AutoYaST profile will not have an Agama -counterpart. - -Nevertheless, we want to cover: - -- Dynamic profiles, including rules/classes, ERB templates, pre-installation scripts and even "ask - lists". See [Dynamic profiles](#dynamic-profiles). -- Compatibility (partial or full) for the following sections: `networking`, `partitioning`, - `language`, `timezone`, `keyboard`, `software`, `scripts`, `users`, `iscsi-client`, `proxy` and - `suse_register`. See [Supported sections](#supported-sections). - -We still need to decide how to handle other sections like `firewall`, `bootloader`, `report`, -`general` or even some elements from `security` or `kdump`. - -Finally, we plan to "ignore" many other sections (e.g., all *-server elements) and sysconfig-like -elements. See [Unsupported sections](#unsupported-sections). - -## Dynamic profiles - -Many AutoYaST users rely on its dynamic capabilities to build adaptable profiles that they can use -to install different systems. For that reason, we need Agama to support these features: - -- [Rules and classes][rules-classes]. -- [Embedded Ruby (ERB)][erb]. -- [Pre-installation scripts][pre-scripts]. -- Ask lists. - -The most realistic way to support those features in the mid-term is to use the AutoYaST code with -some adaptations. The [import-autoyast-profiles branch][autoyast-branch] contains a proof-of-concept -that supports rules/classes, ERB and pre-installation scripts. If you are interested, you can give -it a try: - -``` -cd service -sudo bundle exec bin/agama-autoyast \ - file:///$PWD/test/fixtures/profiles/invalid.xml /tmp/output -cat /tmp/output/autoinst.json -``` - -You can even use the `agama-cli`: - -``` -cd rust -cargo build -sudo PATH=$PWD/../service/bin:$PATH ./target/debug/agama profile download \ - file:///$PWD/../service/test/fixtures/profiles/pre-scripts.xml -``` - -About "ask lists", there might need more work. Fortunately, the code to [parse][ask-list-reader] and -[run][ask-list-runner] the process are there but we need to adapt the -[user interface][ask-list-dialog], which is not trivial. - -[rules-classes]: https://doc.opensuse.org/documentation/leap/autoyast/html/book-autoyast/rulesandclass.html -[erb]: https://doc.opensuse.org/documentation/leap/autoyast/html/book-autoyast/erb-templates.html -[pre-scripts]: https://doc.opensuse.org/documentation/leap/autoyast/html/book-autoyast/cha-configuration-installation-options.html#pre-install-scripts -[ask-lists]: https://doc.opensuse.org/documentation/leap/autoyast/html/book-autoyast/cha-configuration-installation-options.html#CreateProfile-Ask -[autoyast-branch]: https://github.com/openSUSE/agama/tree/import-autoyast-profiles -[ask-list-reader]: https://github.com/yast/yast-autoinstallation/blob/c2dc34560df4ba890688a0c84caec94cc2718f14/src/lib/autoinstall/ask/profile_reader.rb#L29 -[ask-list-runner]: https://github.com/yast/yast-autoinstallation/blob/c2dc34560df4ba890688a0c84caec94cc2718f14/src/lib/autoinstall/ask/runner.rb#L50 -[ask-list-dialog]: https://github.com/yast/yast-autoinstallation/blob/c2dc34560df4ba890688a0c84caec94cc2718f14/src/lib/autoinstall/ask/dialog.rb#L23 - -## Supported sections - -Let's describe which sections and elements from an AutoYaST profile are (or will be) supported in -Agama. In some cases, you might find a table with the following columns: - -- AutoYaST: name of the AutoYaST element. -- Supported: whether it is (or will be) supported. The meaning of each value is: - - Yes: fully supported. - - Planned: not supported yet, but there are plans to support it. - - Undecided: no decision about whether it should be supported. - - No: there are not plans for supporting that element. -- Agama: name of the Agama element. -- Comment: any comment or reason about the element. - -### `dasd` and `iscsi-client` - -Support for iSCSI and DASD devices is missing in Agama profiles. Let's work on that when adding the -`partitioning` section equivalent. - -### `general` - -AutoYaST `general` section contains a set of elements that, for some reason, did not find a better -place. Most of those options will be ignored by Agama (e.g., `cio_ignore`, `mode`, `proposals`, -etc.). However, we might need to add support for a handful of them. - -Agama should process the `ask-list` section (see [Supported sections](#supported-sections)), -`signature-handling` (to deal with packages signatures) and, most probably, `storage` too (e.g., -affects the proposal). - -### `groups` and `users` - -Regarding users, Agama only allows defining the first user and setting the root authentication -mechanism (password and/or SSH public key). However, AutoYaST allows to specify a list of users and -groups plus some authentication settings. We have at least two options here: - -- Extract the root authentication data from the profile and try to infer which is the first user. - This behavior is already implemented. -- Import these sections as given because they are handled by the YaST code in Agama. - -| AutoYaST | Supported | Agama | Comment | -| -------- | --------- | ----- | -------------------------------------------- | -| groups | No | | It is not planned, but we should consider | -| users | No | | It is not planned, but we should consider | -| | | root | Root user (only password and SSH public key) | -| | | user | First non-system user from "users" | - -For the first user, the following elements are supported: - -| AutoYaST | Supported | Agama | Comment | -| -------------------- | --------- | -------- | ---------------------- | -| authorized_keys | Planned | | Only for the root user | -| encrypted | Planned | | | -| forename | No | | | -| fullname | Yes | fullName | | -| gid | No | | | -| group | No | | | -| groups | No | | | -| home | No | | | -| home_btrfs_subvolume | No | | | -| password_settings | No | | | -| shell | No | | | -| surname | No | | | -| uid | No | | | -| user_password | Yes | password | | -| username | Yes | userName | | - -### `keyboard` - -Only the `keymap` element is translated. The rest of options are ignored in YaST and they are not -even documented in the AutoYaST handbook. - -| AutoYaST | Supported | Agama | Comment | -| -------- | --------- | ------------- | ------------------------------ | -| keymap | Yes | l10n.keyboard | Should we rename it to keymap? | -| capslock | No | | Deprecated | -| delay | No | | Deprecated | -| discaps | No | | Deprecated | -| numlock | No | | Deprecated | -| rate | No | | Deprecated | -| scrlock | No | | Deprecated | -| tty | No | | Deprecated | - -### `language` - -| AutoYaST | Supported | Agama | Comment | -| --------- | --------- | -------------- | ------------------------- | -| language | Yes | l10n.languages | First element of the list | -| languages | Yes | l10n.languages | | - -### `networking` - -The `networking` section in AutoYaST is composed of several sections: `dns`, `interfaces`, -`net-udev`, `routing` and `s390-devices`. At this point, Agama only supports defining a list of -connections that could correspond with the AutoYaST interfaces list. We might need to extend Agama -to support `dns`, `net-udev`, etc. - -| AutoYaST | Supported | Agama | Comment | -| ----------------------- | --------- | ----------- | ---------------------------------- | -| backend | No | | No plan for additional backends | -| dhcp_options | No | | | -| dns | Partial | | Included in connections | -| interfaces | Partial | connections | Check the connections table below | -| ipv6 | Yes | | It affects `method4` and `method6` | -| keep_install_network | No | | | -| managed | No | | | -| modules | No | | | -| net-udev | No | | | -| routing | Planned | | | -| s390-devices | Planned | | | -| setup_before_proposal | No | | | -| strict_IP_check_timeout | No | | | -| virt_brige_proposal | No | | | - -As seen in the table above, AutoYaST `interfaces` corresponds with Agama `connections`, but the -format is not exactly the same. - -| AutoYaST | Supported | Agama | Comment | -| -------------------------- | --------- | ----------- | --------------------------------------- | -| device | Yes | interface | | -| name | Yes | id | | -| description | No | | | -| bootproto | Partial | method{4,6} | Different set of values | -| startmode | No | | Do not set up connections you won't use | -| lladdr | Yes | macAddress | | -| ifplugd_priority | No | | Not relevant (no ifplugd support) | -| usercontrol | No | | | -| dhclient_set_hostname | No | | | -| ipaddr | Yes | addresses | | -| prefixlen | Yes | addresses | Part of `addresses` | -| remote_ipaddr | Undecided | | | -| netmask | Yes | addresses | Part of `addresses` | -| bonding_* | Yes | bond | Use a different format to define bonds | -| aliases | Yes | | Part of `addresses` | -| broadcast | No | | Part of `addresses` | -| network | No | | Part of `addresses` | -| mtu | Undecided | | | -| ethtool_options | Undecided | | | -| wireless | Yes | wireless | It uses a different format | -| wifi_settings | Partial | wireless | It uses a different format | -| bridge_settings | Planned | | | -| vlan_settings | Planned | | | -| dhclient_set_down_link | No | | | -| dhclient_set_default_route | No | | | -| zone | No | | | -| firewall | No | | | - -#### Wireless connections - -Setting up a wireless connection in AutoYaST is not even documented, although it is possible. In -Agama, the options are placed under a `wireless` key. - -| AutoYaST | Supported | Agama | Comment | -| ---------------------------- | --------- | -------- | ----------------------- | -| wireless_auth_mode | Partial | security | Different set of values | -| wireless_ap | Undecided | | | -| wireless_bitrate | Undecided | | | -| wireless_ca_cert | Undecided | | | -| wireless_channel | Undecided | | | -| wireless_client_cert | Undecided | | | -| wireless_client_key | Undecided | | | -| wireless_client_key_password | Undecided | | | -| wireless_default_key | Undecided | | | -| wireless_eap_auth | Undecided | | | -| wireless_eap_mode | Undecided | | | -| wireless_essid | Yes | ssid | | -| wireless_frequency | Undecided | | | -| wireless_key | Undecided | | | -| wireless_key_0 | Undecided | | | -| wireless_key_1 | Undecided | | | -| wireless_key_2 | Undecided | | | -| wireless_key_3 | Undecided | | | -| wireless_key_length | Undecided | | | -| wireless_mode | Partial | mode | Different set of values | -| wireless_nick | No | | | -| wireless_nwid | No | | | -| wireless_peap_version | No | | | -| wireless_power | No | | | -| wireless_wpa_anonid | No | | | -| wireless_wpa_identity | No | | | -| wireless_wpa_password | Yes | password | | -| wireless_wpa_psk | Yes | password | | - -#### Bonding connections - -The AutoYaST `bonding*` elements allow setting up a bonding interface. In Agama, those settings are -placed under a `bond` key in the `connection` structure. - -| AutoYaST | Supported | Agama | Comment | -| ------------------- | --------- | ------- | ----------------------------- | -| bonding_master | Yes | | The master defines the `bond` | -| bonding_slaveX | Yes | ports | | -| bonding_module_opts | Yes | options | | -| - | | mode | Specific key to set the mode | - -Agama includes an specific `mode` options to set the mode, instead of abusing the -`bonding_module_opts`. - -### Bridge connections - -> [!WARNING] -> Bridge support is not implemented yet, although we have support at model level. - -The AutoYaST `bridge*` elements allow setting up a bridge. In Agama, those settings are placed under -a `bridge` key in the `connection` structure. - -| AutoYaST | Supported | Agama | Comment | -| -------------------- | --------- | ------------- | --------------------------------------- | -| bridge | Planned | | An existing `bridge` key means the same | -| bridge_ports | Planned | ports | | -| bridge_stp | Planned | stp | | -| bridge_forward_delay | Planned | forward_delay | | -| bridge_forwarddelay | Planned | forward_delay | Compatibility bsc#1180944 | - -### VLAN - -> [!WARNING] -> VLAN support is not implemented yet, although we have support at model level. - -The AutoYaST `vlan_settings` elements allow setting up a bridge. In Agama, those settings are placed -under a `vlan` key in the `connection` structure. - -| AutoYaST | Supported | Agama | Comment | -| ----------- | --------- | -------- | ------- | -| vlan_id | Planned | id | | -| etherdevice | Planned | parent | | -| - | Planned | protocol | | - -### `partitioning` - -By far, the most complex part of an AutoYaST profile. We can import the AutoYaST `partitioning` -section as it is because the partitioning is handled by the same code in Agama and AutoyaST. - -However, we must implement a mechanism to convert to/from both profile types. - -### `proxy` - -To use a proxy in Agama, you set the `proxy` in the [kernel's command line][cmdline]. In AutoYaST, -you can specify the proxy in the profile apart from the command line. - -Although we need to support the same use case, we should avoid introducing a `proxy` section unless -it is strictly required. - -[cmdline]: https://github.com/openSUSE/agama/blob/a105391949a914ae57719c80a610c642fb581924/service/lib/agama/proxy_setup.rb#L31 - -### `report` - -The AutoYaST `report` section defines which kind of messages to report (errors, warnings, -information and yes/no messages) and whether the installation should stop on any of them. Agama does -not have an equivalent mechanism. Moreover, it is arguable whether it is a good idea to base on the -type of message to stop the installation. A more fine-grained control over the situations that -should stop the installation would be better. As an example, consider the `signature-handling` -section. - -### `scripts` - -The only way to use scripts in Agama is to write your own autoinstallation script. Unlike AutoYaST, -you cannot embed the script within the Jsonnet-based profile. This is relevant from the -implementation point of view because we might need to extract AutoYaST scripts and put them in some -place for Agama to run them. - -Apart from that, AutoYaST considers five kind of scripts: `pre`, `post-partitioning`, `chroot`, -`post`, and `init`. The last two are expected to run after the first boot, where Agama is not -present anymore. - -If we want to support `post` or `init` scripts, we need to copy them to the installed system and run -them through a systemd service. - -### `software` - -The `software` section is composed of several lists: - -- A list of products to install, although a single value is expected. -- A list of patterns to install, a list of patterns to install in the 2nd stage and a list of - patterns to remove. -- A list of packages to install, a list of packages to install in the 2nd stage and a list of - packages to remove. - -Additionally, it is possible to force the installation of a specific kernel (`kernel`), perform an -online update at the end of the installation (`do_online_update`) or enable/disable the installation -of recommended packages (`install_recommended`). - -Only the product and the list of products or patterns are available for Agama. We might consider -adding support for the packages list and the `install_recommended` setting, although none are in the -web UI. - -| AutoYaST | Supported | Agama | Comment | -| ------------------- | --------- | ----------------- | --------------------------------- | -| do_online_update | No | | No 2nd stage | -| install_recommended | No | | | -| instsource | No | | | -| kernel | No | | | -| packages | No | | | -| patterns | Partial | software.patterns | No support for regular expresions | -| post-packages | No | | No 2nd stage | -| post-patterns | No | | No 2nd stage | -| products | Yes | software.id | | -| remove-packages | No | | No upgrade | -| remove-patterns | No | | No upgrade | -| remove-products | No | | No upgrade | - -### `suse_register` - -Basic support for registering in the SUSE Customer Center is already in place, although there is no -way to select the list of add-ons. - -It is arguable whether we should offer a `install_updates` element instead of just installing them -(which is the use case for not installing them?). - -About the `slp_discoverty` element, Agama does not support [SLP] at all? - -[SLP]: https://documentation.suse.com/sles/15-SP5/single-html/SLES-administration/#cha-slp - -| AutoYaST | Supported | Agama | Comment | -| -------------------------------- | --------- | ------------------------- | ------------------------------------ | -| do_registration | Yes | | The section is ignored if `false` | -| email | Yes | product.registrationEmail | | -| install_updates | Never | | | -| reg_code | Yes | product.registrationCode | | -| reg_server | Planned | | | -| reg_server_cert | Planned | | | -| reg_server_cert_fingerprint | Planned | | | -| reg_server_cert_fingerprint_type | Planned | | | -| addons | Undecided | | It is not clear how addons will work | -| slp_discovery | No | | | - -### `timezone` - -| AutoYaST | Supported | Agama | Comment | -| -------- | --------- | ------------- | ------- | -| timezone | Yes | l10n.timezone | | -| hwclock | No | | | - -## Unsupported sections - -- `FCoE` -- `add-on` -- `audit-laf` -- `auth-client` -- `configuration_management` -- `deploy_image` -- `dhcp-server` -- `dns-server` -- `files` -- `firstboot` -- `ftp-server` -- `groups` -- `host` -- `http-server` -- `mail` -- `nfs` -- `nfs_server` -- `nis` -- `nis_server` -- `ntp-client` -- `printer` -- `samba-client` -- `services-manager` -- `sound` -- `squid` -- `ssh_import` -- `sysconfig` -- `tftp-server` -- `upgrade` diff --git a/doc/avahi.md b/doc/avahi.md deleted file mode 100644 index 87e4f6af69..0000000000 --- a/doc/avahi.md +++ /dev/null @@ -1,89 +0,0 @@ -# Avahi/mDNS - -Agama's Live ISO is configured to use mDNS (sometimes called Avahi, Zeroconf, Bonjour) for hostname -resolution. The reason is that it might be quite difficult to find out which URL should be used for -connecting to a running Agama installer. - -This document explains how this feature works and offers a few hints for fix potential problems. - ->[!WARNING] -> Do not use the `.local` hostnames in untrusted networks (like public WiFi networks, shared -> networks), it is a security risk. An attacker can easily send malicious responses for the `.local` -> hostname resolutions and point you to a wrong Agama instance which could for example steal your -> root password! - -## Firewall Configuration - -If you cannot connect to a server using the `.local` domain then maybe the -firewall is blocking the traffic. Then you need to enable the mDNS traffic using -these commands: - -```shell -# enable the mDNS traffic in the current run -firewall-cmd --zone=public --add-service=mdns -# make the change permanent -firewall-cmd --permanent --zone=public --add-service=mdns -``` - -## Using mDNS - -The Live ISO by default uses the `agama.local` hostname. To connect to the -running instance simply type `https://agama.local` in your browser. In most -browsers the HTTPS is the default protocol so usually it is enough to just type -`agama.local`. - -If you run multiple Agama instances, each one will have a different name. The server -appends a number to make it unique. So the second Agama instance gets the -`agama-2.local` hostname. - -If you are not sure whether there are multiple Agama instances running you scan -the network, see the [service advertising](#service-advertising) below. - -Alternatively you can set a different hostname for each instance manually. Use -the `hostname=` boot option to set a different hostname. For example set -`hostname=foo`, `hostname=bar` and then use `https://foo.local`, -`https://bar.local` URLs in the web browser to connect to the respective -instance. - -It is possible to change the hostname later if needed: - -```shell -# set the new hostname -hostnamectl hostname -# restart the avahi daemon server -systemctl restart avahi-daemon -``` - -The mDNS resolution also works for other services like ping or SSH. So you can -use commands like: - -```shell -ping agama.local -ssh root@agama.local -``` - -## Fallback - -The mDNS approach is just an addition, one more possibility how to connect to -the machine. If it does not work for you then you can always use the old good -classic IP address approach. - -## Service Advertising - -The Agama Live ISO also uses Avahi service advertising. With this you can easily -search for all running Agama instances in the local network: - -```shell -avahi-browse -t -r _agama._sub._https._tcp -``` - -The command will print the found servers and their hostnames and IP addresses. - -## Notes - -- mDNS works only in the same local network, it does not work over internet - or separate network segments. -- mDNS might not be supported in all systems or it might be blocked by firewall. -- On mobile phones with Android OS mDNS is supported since Android version 12. - (but this might be vendor dependent...). - diff --git a/doc/i18n.md b/doc/i18n.md deleted file mode 100644 index afd5483b0e..0000000000 --- a/doc/i18n.md +++ /dev/null @@ -1,552 +0,0 @@ -# Internationalization (i18n) - -**Table of Contents** - -- [Internationalization (i18n)](#internationalization-i18n) - - [Using Translations](#using-translations) - - [Language Selector](#language-selector) - - [URL Query Parameter](#url-query-parameter) - - [Translations](#translations) - - [The Workflow](#the-workflow) - - [Staging Translation Repository](#staging-translation-repository) - - [Synchronization](#synchronization) - - [Uploading Translatable Texts](#uploading-translatable-texts) - - [Downloading Updated Translations](#downloading-updated-translations) - - [Weblate Configuration](#weblate-configuration) - - [Plugins](#plugins) - - [Technical Details](#technical-details) - - [The Web Frontend](#the-web-frontend) - - [Marking Texts for Translation](#marking-texts-for-translation) - - [Singular Form](#singular-form) - - [Plural Form](#plural-form) - - [Translating Constants](#translating-constants) - - [Formatting Texts](#formatting-texts) - - [TRANSLATORS Comments](#translators-comments) - - [Missing Translations](#missing-translations) - - [ESLint Plugin](#eslint-plugin) - - [Testing Language](#testing-language) - - [Building POT File](#building-pot-file) - - [Loading Web UI Translations](#loading-web-ui-translations) - - [Development Server](#development-server) - - [Backend Locale](#backend-locale) - - [Backend Translations](#backend-translations) - - [Troubleshooting](#troubleshooting) - ---- - -Internationalization (sometimes abbreviated as "i18n") is a process for -supporting different languages and locales in software. This documentation -describes how is that handled in Agama. - -Each Agama part (the web frontend, the D-Bus backend and the command line -interface) needs to solve this problem separately, see more details for each -part in the details below. - -## Using Translations - -Users have two ways how to change the used language in the Agama interface. - -### Language Selector - -The sidebar of the web UI contains a component that allows to change the -language. It was introduced in Agama 5 and it is the recommended way. The list -of supported languages is read from the -[languages.json](https://github.com/openSUSE/agama/blob/master/web/src/languages.json) -file. Check the [The Web Frontend](#the-web-frontend) for further details. - -### URL Query Parameter - -When using a remote installation it is possible to set the used language via an -URL query parameter. This is an expert option. - -To change the language append the `?lang=` query to the URL when -accessing the Agama installer. The `locale` string uses the [RFC -5646](https://www.rfc-editor.org/rfc/rfc5646.html) but the usual Linux locale -format is supported too, e.g. `cs_CZ`. - -It is the user responsibility to use a correct locale name. When using a wrong -name the translations might be broken, displayed only partially or even not at -all. - -Changing the language causes reloading the page, in some situations this could -cause losing some entered values on the current page. Therefore it is -recommended to change the language at the very beginning. - -## Translations - -For translation process Agama uses [Weblate](https://weblate.org/) tool running -at the [openSUSE](https://l10n.opensuse.org/) instance. - -## The Workflow - -The basic translation workflow looks like this: - -1. The translatable texts are marked for translation in the source code, usually - with the `_()` function or something similar -2. The translatable string are collected into a POT file which is uploaded to - the staging [agama-weblate](https://github.com/agama-project/agama-weblate) GitHub - repository -3. The POT file is loaded by the Weblate into the - [agama](https://l10n.opensuse.org/projects/agama/) project -4. Translators then can translate the English texts into other languages -5. Weblate pushes back the translations in the PO files back to the - [agama-weblate](https://github.com/agama-project/agama-weblate) repository -6. The translations in the PO files are regularly copied to the main repository - using pull requests -7. The PO files are processed during build so the translations can be used - later at runtime - -## Staging Translation Repository - -The special [agama-weblate](https://github.com/agama-project/agama-weblate) -repository works like a buffer between the Agama sources and the Weblate tool. - -We do not want to spam the Weblate tool with every trivial change in the texts -and the other way round, we do not need to get dozen commits from the Weblate -every day with updated translations. This would be especially annoying -before releasing a new version where we might want to accept only unnecessary -changes to not break something at the very last minute. - -The agama-weblate repository uses webhooks to notify the Weblate instance -of any change. Changes in the repository should be visible in Weblate in matter -of seconds. - -## Synchronization - -The content between the main [agama](https://github.com/openSUSE/agama) and -the translation [agama-weblate](https://github.com/agama-project/agama-weblate) -GitHub repositories is synchronized automatically using the GitHub Actions. - -### Uploading Translatable Texts - -Collecting and uploading the translatable texts is done by the -[weblate-update-pot.yml]( -https://github.com/openSUSE/agama/blob/master/.github/workflows/weblate-update-pot.yml) -GitHub action. - -- It checks out both `agama` and `agama-weblate` repositories -- It runs a script which extracts the translatable strings in the `agama` - repository into a POT file -- The POT file is copied to the `agama-weblate` repository and committed to - the GitHub repository - -This action is run daily, but it can be started manually if needed. -Go to the [weblate-update-pot.yml]( -https://github.com/openSUSE/agama/actions/workflows/weblate-update-pot.yml) -action detail and use the "Run workflow" option at the top of the page. - -The code compares the old POT file with the new one and if there is no change -besides the timestamps in the file it is not uploaded to `agama-weblate`. - -### Downloading Updated Translations - -The translations from the `agama-weblate` repository are merged back by the -[weblate-merge-po.yml]( -https://github.com/openSUSE/agama/blob/master/.github/workflows/weblate-merge-po.yml) -GitHub action. - -- It checks out both `agama` and `agama-weblate` repositories -- It copies the PO files from the `agama-weblate` to the `agama` repository -- It updates the `languages.json` file with the list of supported languages. -- It creates a pull request with the changes - -If there are no changes besides the timestamps in the PO files the pull request -is not created. - -## Weblate Configuration - -The [Agama Weblate](https://l10n.opensuse.org/projects/agama/) project defines a -separate translation component for each Agama part (the web frontend, the D-Bus -backend and the command line interface). - -For reading the translations it uses the [agama-weblate]( -https://github.com/agama-project/agama-weblate) GitHub repository, but for the source -code locations it uses the original [agama](https://github.com/openSUSE/agama) -repository. That means after clicking the source location link in the Weblate -you will see the correct source location in the other repository. - -### Plugins - -The Weblate components use the [msgmerge]( -https://docs.weblate.org/en/weblate-4.9.1/admin/addons.html#addon-weblate-gettext-msgmerge) -plugin which automatically updates all PO files to match the POT file. That -means after adding or updating any translatable text the changes are -automatically applied to all existing PO files and translators can translate -the new or updated texts immediately. - -## Technical Details - -This part describes technical and implementation details. It also describes the -translation process for developers. - -### The Web Frontend - -Most of the translatable texts which can user see in Agama are defined in the -web frontend. However, the web frontend can display some translated texts coming -from the backend part so it is important to set the same language in both parts -and make sure the translations are available there. - -The list of supported languages is read from the -[languages.json](https://github.com/openSUSE/agama/blob/master/web/src/languages.json). -Such a list is automatically refreshed when any of the PO files is updated (see -[Uploading Translatable Texts](#uploading-translatable-texts)). - -The [update-manifest.py -script](https://github.com/openSUSE/agama/blob/master/web/share/update-manifest.py) -is the responsible for updating the list of supported languages. It goes -through all PO files, filters out the ones with less than 70% of translated -content and adds the corresponding locales to the `languages.json`. - -The name of the locale is taken from -[langtable](https://pypi.org/project/langtable/), so be sure to have it -installed. However, when the territory is not include in the PO file (`es` -instead of `es_es`), the script uses the -[locales.json map](https://github.com/openSUSE/agama/blob/master/web/share/locales.json) -to determine which territory to use. - -If you need to manually update the `languages.json` file, run: - -``` -web/share/update-languages.py > web/src/languages.json -``` - -### Marking Texts for Translation - -The texts are marked for translation using the usual functions like `_()`, -`n_()` and others. It is similar to the GNU gettext style. - -The mechanism of loading and displaying the translation is heavily inspired -in Cockpit's approach. The [i18n module](../web/src/i18n.js) offers a set of translation functions: - - -```js -import { _, n_, N_, Nn_ } from "~/i18n"; -``` - -It is important to use these functions only on string literals! Do not use them -with string templates or string concatenation, that will not work properly. - -The `_` and `n_` functions can be used on variables or constants, but their -content must marked for translation using the `N_` or `Nn_` functions -on string literals. See the examples below. - -#### Singular Form - -This is the most common way: - -```js -const title=_("Storage"); -``` - -For using translated text in React components you need to use curly braces -to switch to plain Javascript in the attributes and the content: - -```js -
-``` - -or - -```js - -``` - -For translating long texts you might use multiline string literals: - -```js -const description = _("Select the device for installing the system. All the \ -file systems will be created on the selected device."); -``` - -If you need to insert some values into the text you should use the -[formatting function](#formatting-texts). It is recommended to use -[translator comments](#translators-comments) for short or ambiguous texts. - -#### Plural Form - -If the translated text contains a number or quantity it is good to use a plural -form so the translated texts looks naturally. - -```js -sprintf( - // the first argument is a singular form used when errors.length === 1, - // the second argument is used in all other cases - n_("%d error found", "%d errors found", errors.length), - errors.length -) -``` - -Although the English language has only a single plural form the translators can -use more of them. The translation definition also defines a function that -computes which plural form to use for a specific number. See more details about -the [plural forms]( -https://www.gnu.org/software/gettext/manual/html_node/Plural-forms.html) in the -GNU gettext documentation. - -#### Translating Constants - -The top-level constants are evaluated too early, at that time the translations -are not available yet and the language is not set. - -The constant value must be marked with `N_()` function which does nothing -and then later translated with the usual `_()` function. - -```js -const LABELS = Object.freeze({ - auto: N_("Auto"), - fixed: N_("Fixed"), - range: N_("Range") -}); - -export default function Foo() { - ... - -``` - -#### Formatting Texts - -For formatting complex texts use the C-like `sprintf()` function. - -```js -import { sprintf } from "sprintf-js"; - -sprintf(_("User %s will be created"), user) -``` - -See the [sprintf-js](https://www.npmjs.com/package/sprintf-js) documentation -for more details about the formatting specifiers. - -*Note: You cannot use HTML tags in the translated texts, React automatically -escapes all special HTML characters like `<>&`. That is different to YaST -where we can use HTML tags in rich text messages.* - -It is recommended to avoid building texts from several parts translated -separately. This is error prone because the translators will not see the -complete final text and might translate some parts inaccurately. - -```js -// do NOT use this! it is difficult to translate the parts correctly -// so they build a nice text after merging -return
{_("User ")}{user}{_(" will be created")}
- -// rather translate a complete text and then split it into parts -// TRANSLATORS: %s will be replaced by the user name -const [msg1, msg2] = _("User %s will be created").split("%s"); -... -return
{msg1}{user}{msg2}
-``` - -Text splitting might be quite complex in some cases, but still should be -preferred. - -```js -// TRANSLATORS: error message, the text in square brackets [] is a clickable link -const [msgStart, msgLink, msgEnd] = _("An error occurred. \ -Check the [details] for more information.").split(/[[\]]/); -... -return

{msgStart}{msgLink}{msgEnd}

; -``` - -Building sentences from separate parts might be easy in English, but is some -other languages it might much more complex. Always assume that the target -language has more complex grammar and rules. - -```js -// do NOT use this! it is difficult to translate "enabled" and "not enabled" -// differently in the target language! -const msgNot = enabled ? "" : _("not"); -sprintf(_("Service is %s enabled"), msgNot); - -// this is better -enabled ? _("Service is enabled") : _("Service is disabled"); -``` - -#### TRANSLATORS Comments - -You can use a special `TRANSLATORS` keyword in the comment preceding the text -marked for translation. All comments after the keyword are included in the -translations file, this should help the translator to correctly translate the -text. - -```js -// this line is NOT included in the PO file -// TRANSLATORS: this line is included in the PO file, -// this line as well -_("Back") -``` - -The translators comments should be used especially for short texts to better -describe the meaning and the context of the message. - -```js -// TRANSLATORS: button label, going back to the main page -_("Back") -``` - -Also the formatting placeholders should be always described. - -```js -// TRANSLATORS: %s will be replaced by the user name -_("User %s will be created") -``` - -The JSX code does not support comments natively, you have to write them in curly -braces. - -```js - -``` - -But in the component attributes you can use usual Javascript comments. - -```js - -``` - -The translators can change the order of the arguments if needed using additional -positional arguments. For example to change the order of the arguments in `"Foo -%s %s"` they can translate it as `"Bar %2$s %1$s"`. - -### Missing Translations - -Here are some code examples which might look correct at the first sight. They -even work, no crash. But there are still translation problems with them. - -- Do not use Javascript string templates, that does not work at all - (~~``_(`User ${user} will be created`)``~~), use a string formatting function - for that (`sprintf(_("User %s will be created"), user)`). - -- Use the translation functions only with string literals without any operators, - texts like ~~`_("foo" + "bar")`~~ will not be extracted correctly to the POT - file. - -In both cases the strings will not be extracted to the POT file. - -### ESLint Plugin - -There is special ESLint plugin [eslint-plugin-agama-i18n]( -https://github.com/openSUSE/eslint-plugin-agama-i18n) which ensures that a -string literal is passed to the translation functions. See more details there. - -### Testing Language - -The Agama web interface supports special testing `xx` language. That language -needs to be selected manually by adding the `?lang=xx` query string to the -server URL. With this setting the `_()` and `n_()` translation functions replace -all alphabetical characters by the `x` symbol. - -This can be used for testing to find out the texts which are not marked for -translation. If a text is not replaced by the `x` symbols then either it is not -marked for translation or it comes from the backend and it should be translated -by the backend. - -However, this is not perfect. It will replace also the texts mentioned in the -[missing translations](#missing-translations) section above but in reality -the there would be no translations available for them. - -### Building POT File - -The translatable strings are extracted from the source files by using the -standard `xgettext` tool. There is a helper script [build_pot](../web/build_pot) -which defines the needed parameters for the `xgettext` tool. - -To build the POT file locally just run the script, it will save the output to -the `agama.pot` file. - -### Loading Web UI Translations - -The translations are loaded by the `` HTML -code in the [index.html](../web/src/index.html) file. But there is no such file -in Agama but one `po..js` file per language, like `po.cs.js`. - -The trick is that Agama's web server checks the `agamaLang` cookie sent in the -HTTP request header and returns the content from the respective file. - -### Development Server - -Because Agama serves the `po.js` file a bit differently as described in the -[](#loading-web-ui-translations) section above we need to implement this -logic also in the development server. - -The [webpack-po-handler.js](../web/src/lib/webpack-po-handler.js) file -checks the language cookie and uses HTTP redirection to load the respective -language file. It uses redirection because the built translation files are only -available in the webpack memory. But the result is the same, the browser gets -a different content according to the currently configured language. - -### Backend Locale - -The Agama server exposes a `uiLocale` configuration option via the -`/api/l10n/locales/config` endpoint which defines the locale used by all the - services. - -The `uiLocale` property is a single global value shared by all connected clients. -That means it is possible to use only one language for all clients, if -more users connect to the server and uses a different UI language then there -will be race conditions and the other users might see the texts coming from the -backend in another language than expected. - -This is a known limitation, we expect that only one user at a time will access -the Agama installer or if multiple users use the same server we expect that -they will be from the same team or company using the same language. - -To check or set the locale you can use the `/api/l10n/locales/config` endpoint. -Alternatively, you can check (but not change) the current locale via D-Bus: - - -```shell -sudo busctl --address unix:path=/run/agama/bus get-property org.opensuse.Agama1 \ - /org/opensuse/Agama1/Locale org.opensuse.Agama1.Locale UILocale -``` - -#### Backend Translations - -The backend might return texts from external components like `libstorage-ng`. -Make sure the translations for those components are also available for Agama, -e.g. the `libstorage-ng` translations are stored in the `libstorage-ng-lang` -package or the YaST translations are stored in `yast2-trans-` packages. - -## Troubleshooting - -Here are some hints what to do when some untranslated text appears in the Agama -UI. - -1. Check that the text is marked for translation, for a quick verification - you might try setting the [testing language](#testing-language). -2. If the text comes from backend or the other parts check that the appropriate - [language package](#backend-translations) is installed. -3. The text should be [extracted into the POT file](#building-pot-file) -4. The [agama.pot]( - https://github.com/agama-project/agama-weblate/blob/master/web/agama.pot) in the - `agama-weblate` repository is up to date, if not then run the [Weblate Update - POT](https://github.com/openSUSE/agama/actions/workflows/weblate-update-pot.yml) - Github Action manually. -5. The text is translated in the [Weblate repository]( - https://l10n.opensuse.org/projects/agama/). -6. The translation is included in the respective PO file in the [agama-weblate]( - https://github.com/agama-project/agama-weblate) repository. -7. The PO file in the [agama]( - https://github.com/openSUSE/agama/tree/master/web/po) repository is up to - date, if not the check whether there is an [open pull request]( - https://github.com/openSUSE/agama/pulls?q=is%3Aopen+is%3Apr+label%3Atranslations+label%3Abot) - with the change, if yes then check it and merge, if not then run the [Weblate - Merge PO](https://github.com/openSUSE/agama/actions/workflows/weblate-merge-po.yml) - GitHub Action manually, then check the created pull request. -8. The translated string should be present in the built packages, run - `npm build` command and check the `dist/po.*.js` files, check the built RPM - package. -9. The translations are loaded by the browser, check the content loaded for the - `po.js` file. -10. Check the current language used in the browser, run `agama.language` - command in the development tools console, check the `agamaLang` cookie - value (run `document.cookie` command in the console). -11. Check the language used by the [Backend Locale](#backend-locale). diff --git a/doc/live_iso.md b/doc/live_iso.md deleted file mode 100644 index 55c5cb3725..0000000000 --- a/doc/live_iso.md +++ /dev/null @@ -1,241 +0,0 @@ - -# Agama ISO Installer - -**Table of Contents** - -- [Sources](#sources) -- [Live ISO Requirements](#live-iso-requirements) -- [Agama Live ISO (*only for development and testing*)](#agama-live-iso-only-for-development-and-testing) - - [Description](#description) - - [Hardware Requirements](#hardware-requirements) -- [Experimental Self-update](#experimental-self-update) -- [The Access Password](#the-access-password) - - [Using Custom Password](#using-custom-password) - - [Boot Command Line](#boot-command-line) - - [Interactive Input](#interactive-input) - - [Injecting the Default Password Into the ISO Image](#injecting-the-default-password-into-the-iso-image) - - [Random Password as a Fallback](#random-password-as-a-fallback) - - [Password Priority](#password-priority) - - [Creating a Hashed Password](#creating-a-hashed-password) - - [Mkpasswd](#mkpasswd) - - [OpenSSL](#openssl) - ---- - -Agama installer is deployed as a regular application which can be installed and run on a local system. However, the most expected way of using Agama is by running it on a live ISO image. - -## Sources - -The Live ISO sources are maintained in the [live](../live/) subdirectory, -See more details in a [live/README.md](../live/README.md) documentation. - -## Live ISO Requirements - -A live ISO for running Agama should provide the following software: - -* Hardware drivers. -* Agama installer and related tools (lvm, cryptsetup, networkmanager, etc). -* A browser to locally render the Agama web UI. -* Optionally, repository packages of the products to install. - -Notes: - -* If no browser is included, then the installation has to be remotely performed by using a browser from another machine. This would be the typical case for s390x installations. -* If no repositories are included, then the installation would require internet connection to download the packages of the product to install. - -## Agama Live ISO (*only for development and testing*) - -The Agama project provides a [live ISO image](https://build.opensuse.org/package/show/systemsmanagement:Agama:Devel/agama-live) for testing purposes and it is intended to be used for developers only. It has some limitations and it is not optimized for production usage. - -**Disclaimer: Agama project is focused on develop the Agama installer applications. Generating and optimizing production ready live ISO images for both SUSE and openSUSE projects is out of the scope.** - -### Description - -* The live ISO is based on openSUSE Tumbleweed. -* Allows installing both SUSE and openSUSE products. -* Weighs around 1 GiB. -* Contains Agama installer and tools, and hardware drivers. -* **Includes Firefox (except for ppc64le and s390x).** -* **Does not include packages from product repositories.** -* Supported archs: x86_64, aarch64, ppc64le and s390x. - -Notes: - -* Firefox is compiled for [ppc64le in Factory](https://build.opensuse.org/package/show/openSUSE:Factory:PowerPC/MozillaFirefox), but it is not included in the repositories of ALP and openSUSE products. -* Firefox is not compiled for s390x. -* For both ppc64le and s390x a browser from a remote machine has to be used in order to run the Agama web UI. Auto-installation and CLI equally works in all architectures. -* An internet connection is always required to download the packages of the product to install. - -### Hardware Requirements - -* 2 GiB of RAM memory -* Internet connection to download packages of the product to install. -* Around 10 GiB of disk size, although it depends on the selected product to install. - -## Experimental Self-update - -> [!WARNING] -> This feature is experimental and untested! - -The Agama packages on the Live ISO can be automatically updated from the OBS -Devel project. - -* Use the `agama.self_update` boot parameter to run the self-update -automatically during boot. -* Or run the `agama-self-update` script anytime later in a running Live system. - -> [!NOTE] -> After updating the packages the Agama servers need to be restarted. This will -> reset all you current Agama settings, you will need to start from scratch! - -## The Access Password - -Because the ISO image is built publicly we cannot use any predefined password as -everybody would know that and for attackers it would be really trivial to hack -your running installer. - -That means you have to provide our own password. If none is specified then Agama -generates a random password and prints it on the console after boot. - -### Using Custom Password - -There are several ways how to specify your custom password, each of them might -be suitable for a different use case. - -### Boot Command Line - -You can define the password directly on the boot command line. There are two -options: - -* Use `live.password=` with a plain text password. - -* Use `live.password_hash=` with a hashed password. This is more - secure than using a plaintext password. - - The disadvantage is that the hashed password is quite long and is not easy to - type it into the boot prompt manually. It makes sense in environments where - you can prepare the boot parameters in advance like in PXE boot or some - virtual machines. - - See more details about creating a hashed password [below]( - #creating-a-hashed-password). - -### Interactive Input - -You can enter your password during boot in an interactive session. Again, there -are two options: - -* Use `live.password_dialog` boot option to start an interactive dialog during - the boot process. This uses a nice dialog for entering and confirming the - password. However, in some situations the full screen dialog might not be - displayed correctly or some messages might be displayed over it. In that case - you might use the `Ctrl+L` key shortcut to refresh the screen. If it still - does not work then try using the other option below. - -* Use `live.password_systemd` boot option to ask for the password in a simple - prompt. This is similar to the option above, but the advantage is that this - solution does not use a full screen dialog but a single line prompt so it - should work better in special environments like a serial console. - -The Agama and the SSH server are not started until a password is configured. -This avoid using the default password from the medium accidentally. - -### Injecting the Default Password Into the ISO Image - -Another option is to inject your custom hashed password directly into the ISO -image. The advantage is than you can easily use the same image for installing -multiple machines and you do not need to configure anything during the boot. - -To inject a new password into the ISO run: - -```sh -# replace the agama.iso name with your image name -tagmedia --add-tag "live_password=$((openssl passwd -6) | base64 -w 0)" agama.iso -``` - -It will interactively ask for a password then it will be hashed using the SHA512 -algorithm, encoded to the Base64 encoding and appended to the application area -in the ISO file. If you want to update the password then just the same command -again, it will overwrite the existing password. - -See the [Creating a Hashed Password](#creating-a-hashed-password) section below -if you want to use a different hashing algorithm than SHA512. - -To check all tags present in an ISO file use this command: - -```sh -# replace the agama.iso name with your image name -tagmedia agama.iso -``` - -If you want to remove the password setting from the ISO image then run: - -```sh -# replace the agama.iso name with your image name -tagmedia --remove-tag live_password agama.iso -``` - -> [!CAUTION] -> The image usually already contains some other tags, like the checksums for -> verifying the medium integrity. Do not touch them! - -### Random Password as a Fallback - -When no password is specified or entering the password interactively was -canceled by the user then Agama generates a random password and prints it on the -console. - -### Password Priority - -The password setting priority is following (from highest priority to the -lowest): - -1. Password entered interactively during the boot process -2. Password entered on the boot command line -3. Default password from the ISO image meta data -4. A random password is generated as a fallback - -### Creating a Hashed Password - -There are several ways how to create a password hash, here we will mention two -tools. - -Each tool allows to select the encryption method to use. To check the details -about all encryption methods see `man 5 crypt`, it lists the encryption methods -sorted by their strength so you can check which methods are recommended and -which ones should be avoided. - -#### Mkpasswd - -You can use the `mkpasswd` tool from the `whois` package. It offers a lot of -encryption methods, see the `mkpasswd -m help` for the list. - -By default it uses the strongest method available so in most cases you just run - -```sh -mkpasswd -``` - -and then enter the password on the command line prompt. - -#### OpenSSL - -Alternatively you can use the `openssl passwd` command from the openSSL package. -It offers less encryption methods but on the other hand it should be basically -installed in every system. - -> [!WARNING] -> By default it uses a weak encryption method (DES or MD5 depending on the OpenSSL -> version) so you should always provide an additional encryption method parameter -> to select a stronger encryption! - -To create a SHA512 hash for your password run - -```sh -openssl passwd -6 -``` - -and then enter the password on the command line prompt. - -For less strong SHA256 hash use the `-5` option, the other encryption methods -should be avoided. diff --git a/doc/running.md b/doc/running.md deleted file mode 100644 index 5d5b5ff235..0000000000 --- a/doc/running.md +++ /dev/null @@ -1,38 +0,0 @@ -# Running from sources - -You can run Agama from its sources by cloning and configuring the project: - -```console -$ git clone https://github.com/openSUSE/agama -$ cd agama -$ ./setup.sh -``` - -Then point your browser to http://localhost:8080/, login with your -root password and that's all. - -The [setup.sh](./setup.sh) script installs the required dependencies to build and run the project -and it also configures the Agama services. It uses `sudo` to install packages and files to system -locations. The script is well commented so we refer you to it instead of repeating its steps here. - -Regarding the web user interface, alternatively you can run a development -server which works as a proxy for Agama's server. See more details [in the -documentation]( web/README.md#using-a-development-server). - -To start or stop Agama D-Bus and web services at any time, use the `agama` and `agama-web-server` systemd services: - -```console -sudo systemctl start agama -sudo systemctl start agama-web-server -``` - -If something goes wrong, you can use `journalctl` to get Agama logs: - -```console -sudo journalctl -u agama -sudo journalctl -u agama-web-server -``` - -Another alternative is to run source checkout inside container so system is not -affected by doing testing run beside real actions really done by installer. -See more details [in the documentation](doc/testing_using_container.md). diff --git a/doc/startup.md b/doc/startup.md deleted file mode 100644 index 9917f48b9a..0000000000 --- a/doc/startup.md +++ /dev/null @@ -1,44 +0,0 @@ -# Agama Startup Process - -This document summarizes Agama's startup process. - -## Overview - -As described in the [architecture docment](./architecture.md), Agama is composed of a web server, -a set of D-Bus services, a web client and a command-line interface. The startup process aims -to get those D-Bus services up and running and make the web server available. Additionally, the -auto-installation procedure could be started if required by the user. - -The startup process is handled by systemd and D-Bus. The only exception is starting the local -browser in the Agama Live image. - -## Starting the D-Bus Services - -[agama.service](../service/share/agama.service) is responsible for starting up Agama's D-Bus daemon -process using the `agamactl --daemon` command. This process uses a dedicated bus with a [specific -configuration](../service/share/dbus.conf). - -Once the daemon process is running, each D-Bus service will be automatically activated when -required. The definitions of those services are located in `/usr/share/dbus-1/agama-services`, -although you can find the sources in the [repository](../service/share) -(`org.opensuse.Agama*.service` files). - -## Starting the web server - -[agama-web-server](../rust/share/agama-web-server.service) is responsible for starting up -Agama's web server using the `agama-web-server` command. - -## Auto-installation - -If the `agama.auto` option is specified in the kernel command-line, the -[agama-auto.service](../service/share/systemd/agama-auto.service) comes into play. It runs after the -`agama-web-server.service` so the web server and the D-Bus daemon are ready. - -## Web UI - -When discussing the web UI, we can distinguish two sides: the server process and the web browser. -Regarding the server, Agama's web UI is implemented as a React application which is served -by the web server. You can connect to the UI using the http://$SERVER_IP` address. - -When using Agama Live, a local web browser is automatically started. In the default image, it is -launched using an [IceWM startup script](../live/root/root/.icewm/startup) diff --git a/doc/testing_using_container.md b/doc/testing_using_container.md deleted file mode 100644 index 3914c84d5b..0000000000 --- a/doc/testing_using_container.md +++ /dev/null @@ -1,16 +0,0 @@ -## Testing Using Container - -To test complex change that affects multiple parts of Agama it is possible to -run from sources using container that is used to run CI. - -Use the [testing_using_container.sh](../testing_using_container.sh) shell -script. That scripts does several steps: - -- Starts the container -- Installs the needed packages, compiles the sources and starts the servers - (using the [setup.sh](../setup.sh) script) -- It asks for the new root password to allow logging in (by default there is - no root password set in containers) -- It provides web UI on a forwarded HTTPS port, -- Starts a shell inside the container with root access for more testing or - debugging. diff --git a/doc/yupdate.md b/doc/yupdate.md deleted file mode 100644 index aec1863ac7..0000000000 --- a/doc/yupdate.md +++ /dev/null @@ -1,100 +0,0 @@ -# Patching the Agama on a Live Medium - -The Agama installer allows patching itself directly from the GitHub sources -or from your local Git checkout using the [yupdate script]( -https://github.com/yast/yast-installation/blob/master/bin/yupdate). -See more details in the [yupdate documentation]( -https://github.com/yast/yast-installation/blob/master/doc/yupdate.md). - -This patching only works when running from a live medium. You can also patch -the standard YaST modules included in the installer if needed. - -The goal is to provide an easy way for testing fixes or new features for the -end users or testers. - -## Patching from GitHub - -``` -yupdate patch openSUSE/agama master -``` - -You can replace the `master` branch with any branch containing a fix or a new feature. - -## Patching from a Local Git Checkout - -First you need to run the `rake server` command in your Agama Git checkout. - -Then run this command: - -``` -yupdate patch 192.168.1.2:8000 -``` - -Replace the IP address with the IP address of your machine running the -`rake server` command. Port 8000 is the default port used, modify it if you use -a different port number. - -## Options - -You can modify the update process with these environment variables: - -- `DEBUG=1` - to find more about what is going behind process. If it fails in - rake install see VERBOSE below. -- `VERBOSE` - makes visible all commands and its output when doing rake - install. Useful to debug if yupdate failed. -- `NPM_CACHE=1` - The installed NPM packages will be saved to a local cache - and will be reused in the next run. This can speed up the patching process - if you need to patch the installer several times. On the other hand this - increases the amount of needed RAM memory. - The cache is stored in `$HOME/.cache/agama-devel/` directory, - if you need to refresh the content of the cache then delete this directory. -- `NODE_ENV=development` - The web front-end will be built in the development - mode. The files will not be minimized and additional `*.map` files will be - generated. This helps with debugging in the browser, you can get the locations - in the original source files. -- `YUPDATE_SKIP_FRONTEND=1` - Skip updating the web frontend. Use this option - when you use the webpack development server for running the web frontend. - In that case updating the web frontend does not make sense because it is - running in a different server. This saves some time and disk/RAM space. -- `YUPDATE_SKIP_BACKEND=1` - Skip updating the D-Bus service backend. This is - similar to the previous option, use it when you do want to keep the D-Bus - service unchanged. - -## Notes - -For compiling the Javascript code and SCSS files the yupdate installs several -RPM and NPM packages. Because the live medium is completely running in a RAM -disk all downloaded files are stored in the RAM memory. - -That means the machine should have enough memory for this process. If there -is not enough memory the system becomes completely frozen and might not respond -to any input event. - -Currently the minimum for a safe operation is around 4GB RAM. If you use the -`NPM_CACHE=1` option then recommended minimum is around 5GB. - -## Activating the Changes - -After patching the files the DBus service is restarted if any related file -has been changed. That means the configured settings will be lost. - -To activate the changes in the web frontend you need to reload the page in the -browser. - -:warning: *In the FireFox browser you need to use the `Ctrl+F5` combination -for reloading the page, this uses full reload ignoring the cache. Plain `F5` -uses cached files and will not reflect the update on the server!* - -In some special cases you might need to do some additional actions manually, -the update script might not handle all corner cases. - -## Implementation Details - -The support is implemented in the main [Rakefile](../Rakefile) and in the -[.yupdate.pre](../.yupdate.pre) and [.yupdate.post](../.yupdate.post) hook -scripts. - -- The `.yupdate.pre` script prepares the system for compiling and installing - new Agama files. -- The `Rakefile` code builds and installs both backend and frontend parts. -- The `.yupdate.pre` script activates the changes, it restarts the backend if needed.