Describe Agama's startup process

README.md

@@ -93,7 +93,7 @@ communication.
 
 ![Architecture](./doc/images/architecture.png)
 
-Agama consists on a set of D-Bus services and a web client (an experimental CLI is also available). The services use YaST-based libraries under the hood, reusing a lot logic already provided by YaST. Currently Agama comes with six separate services, although the list can increase in the future:
+Agama consists on a set of D-Bus services, a web client and a command-line interface. The services use YaST-based libraries under the hood, reusing a lot logic already provided by YaST. Currently Agama comes with six separate services, although the list can increase in the future:
 
 * Agama service: it is the main service which manages and controls the installation process.
 * Software service: configures the product and software to install.
@@ -136,50 +136,30 @@ Then point your browser to http://localhost:9090/cockpit/@localhost/agama/index.
 
 The [setup.sh](./setup.sh) script installs the required dependencies
 to build and run the project and it also configures the Agama services
-and cockpit. It uses `sudo` to install packages and files to system locations.
+and Cockpit. 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.
 
-Alternatively you can run a development server which works as a proxy for
-the cockpit server. See more details [in the documentation](
-web/README.md#using-a-development-server).
+Regarding the web user interface, alternatively you can run a development
+server which works as a proxy for the cockpit server. See more details [in the
+documentation]( web/README.md#using-a-development-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).
-
-* Start the services:
-    * beware that Agama must run as root (like YaST does) to do
-      hardware probing, partition the disks, install the software and so on.
-    * Note that `setup.sh` sets up D-Bus activation so starting manually is
-      only needed when you prefer to see the log output upfront.
+To start or stop Agama D-Bus services at any time, use the `agama` systemd service:
 
 ```console
-$ cd service
-$ sudo bundle exec bin/agama
+sudo systemctl start agama
 ```
 
-* Check that Agama services are working with a tool like
-[busctl](https://www.freedesktop.org/wiki/Software/dbus/) or
-[D-Feet](https://wiki.gnome.org/Apps/DFeet) if you prefer a graphical one:
-
+If something goes wrong, you can use `journalctl` to get Agama logs:
 
 ```console
-$ busctl --address=unix:path=/run/agama/bus \
-    call \
-    org.opensuse.Agama1 \
-   /org/opensuse/Agama1/Manager \
-    org.opensuse.Agama1.Manager \
-    CanInstall
-
-$ busctl --address=unix:path=/run/agama/bus \
-    call \
-    org.opensuse.Agama.Locale1 \
-   /org/opensuse/Agama/Locale1 \
-    org.freedesktop.DBus.Properties \
-    GetAll s org.opensuse.Agama.Locale1
+sudo journalctl -u agama
 ```
 
+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).
+
 ## How to Contribute
 
 If you want to contribute to Agama, then please open a pull request or report an issue. You can also have a look to our [road-map](https://github.com/orgs/yast/projects/1/views/1).

doc/startup.md

@@ -0,0 +1,42 @@
+# Agama Startup Process
+
+This document summarizes Agama's startup process.
+
+## Overview
+
+As described in the [README](../README.md#architecture), Agama is composed of 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 UI 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).
+
+## 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.service` so the D-Bus daemon is ready and the services can be activated as needed.
+
+## 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 Cockpit module, so the only requirement is
+that the `cockpit.socket` is enabled. Then, you can connect to the UI using the
+`https://$SERVER_IP:9090/cockpit/@localhost/agama/index.html`.
+
+When using Agama Live, a local web browser is automatically started. In the default image, it is
+launched using an Icewm startup script[^1].
+
+[^1]: Check the `root.tar` file from the [agama-live](https://build.opensuse.org/package/show/systemsmanagement:Agama:Devel/agama-live) sources.