readme: Add documentation for development container usage

Based on sotactl README.md.

Signed-off-by: Andre Detsch <[email protected]>

README.md

@@ -39,7 +39,7 @@ The make environment variables are:
 If `-f dev-flow.mk` is specified, then the `make` command is executed on a host, otherwise the `foundries/aklite-dev` container is used.
 A user can specify their own container to run the commands in by overriding `CONTAINER` environment variable.
 
-### Test
+### Unit Test
 
 ```
 [<MAKE ENV VARS>] make [-f dev-flow.mk] test
@@ -51,7 +51,61 @@ The make environment variables are:
 *  `CTEST_ARGS` - additional `ctest` parameters, by default is set to `--output-on-failure`.
 *  `GTEST_FILTER` - a regexp to filter tests within gtest suits, e.g. `GTEST_FILTER="*OstreeUpdateNoSpaceRetry*" TEST_LABEL="aklite:liteclient" make`.
 
-### Usage
+### Development Test Environment
+
+In order to facilitate development and testing of aktualizr-lite, an development container is made available.
+It works in conjunction with a container running dockerd,
+providing an environment where most of the functional aspects can be tested.
+It allows the communication with an actual factory instance, getting updates and sending back events.
+
+#### Prerequisites
+1. Linux host/VM (tested on Ubuntu and Arch Linux)
+2. Docker engine and client, version >= 20.10.xx
+3. Docker compose, version >= 2.22.0
+
+#### Set required environment variables
+1. `FACTORY` - Name of your FoundriesFactory.
+2. `USER_TOKEN` - Token to access your FoundriesFactory obtained from [Foundries.io settings page](https://app.foundries.io/settings/tokens/).
+
+#### Development in the development container
+Run `./dev-shell-e2e-test.sh`. The initial/first run may take some time as necessary container images are downloaded and built. Subsequent runs will be faster.
+
+##### Register/Unregister device
+Inside the development container, run `make register` or `make unregister` to register or unregister a device, respectively.
+Override the `DEVICE_TAG` environment variable if you need to register a device and set its tag to a non-default value (`main`).
+For example, `DEVICE_TAG=devel make register`.
+
+##### Build aktualizr-lite
+Run `make -f dev-flow.mk` to build the aktualizr-lite client.
+
+##### Configure your development device
+You can add additional configuration `*.toml` snippets to the default device configuration by placing them in `<sota-project-home-dir>/.device/etc.sota`.
+
+##### Check/Update local TUF metadata
+Run `make check` to update the local TUF (The Update Framework) repository and get a list of available targets. Alternatively, run `./build/src/atualizr-lite check`.
+
+##### Update your development device
+1. Run `make update` to update your development device to the latest available target. The initial update may take some time since it pulls the target's ostree repository from scratch. Subsequent updates are faster as they pull only the differences between two commits.
+2. If a device reboot is required, run `make reboot`.
+3. Finalize the update and run updated apps, if any, by running `make run`.
+
+##### Develop and debug aktualizr-lite
+After the initial update, you can continue developing and debugging aktualizr-lite:
+1. Make code changes.
+2. Build the code with `make -f dev-flow.mk`.
+3. Run or debug one of the SOTA client commands, for example:
+   ```bash
+   ./build/src/atualizr-lite check               # Check for TUF metadata changes and update local TUF repository if any changes are found
+   ./build/src/atualizr-lite pull [<target>]     # Pull the specified target content (ostree and/or apps)
+   ./build/src/atualizr-lite install [<target>]  # Install the pulled target
+   ./build/src/atualizr-lite run                 # Finalize target installation if required after a device reboot
+
+   gdb --args ./build/src/atualizr-lite [<command&params>]   # Debug
+
+###### Emulating device reboot
+To emulate a device reboot in the development container, remove the `/var/run/aktualizr-session/need_reboot` file if it exists.
+
+### Usage on Local Environment
 
 [Run aktualizr-lite locally against your Factory](./how-to-run-locally.md)