docs: improve testflinger agent host documentation (#924)

* docs: update README and CONTRIBUTING guides

* docs: update documentation with agent administration tasks

* fixes

* fix spell checks

* reestructure administrator to be inside how-to

* add suggestions made by reviewers

* fix title underline

* fix other line lengths

* modify how-to index

Author: rene-oromtz

agent/charms/testflinger-agent-host-charm/CONTRIBUTING.md

@@ -0,0 +1,49 @@
+# Contributing to Testflinger
+
+This document outlines contribution guidelines specific to the Testflinger charm.
+To learn more about the general contribution guidelines for the Testflinger project, refer to the [Testflinger contribution guide](../../../CONTRIBUTING.md).
+
+To make contributions to this charm, you'll need a working
+[development setup][juju-setup]. If you are setting up a VM manually, you may
+want to use [`concierge`][concierge]. To get started run:
+
+```shell
+concierge prepare --verbose --juju-channel=3/stable --charmcraft-channel=latest/stable -p machine
+```
+
+You can create an environment for development with [`uv`][uv] from within the `agent` directory (you can install it as a [snap][uv-snap]):
+
+```shell
+uv sync
+source .venv/bin/activate
+```
+
+## Testing
+
+This project uses [`tox`][tox] for managing test environments. There are some pre-configured environments
+that can be used for linting and formatting code when you're preparing contributions to the charm:
+
+```shell
+uvx --with tox-uv tox run -e format         # update your code according to linting rules
+uvx --with tox-uv tox -e lint               # code style
+uvx --with tox-uv tox -e charm-unit         # charm unit tests
+uvx --with tox-uv tox -e charm-integration  # charm integration tests
+```
+
+## Build the charm
+
+Build the charm with [`charmcraft`][charmcraft-snap]:
+
+```shell
+charmcraft pack
+```
+
+> [!NOTE]
+> Before running the integration tests, you require to build the charm 
+
+[juju-setup]: https://documentation.ubuntu.com/juju/3.6/howto/manage-your-deployment/#set-up-your-deployment-local-testing-and-development
+[concierge]: https://snapcraft.io/concierge
+[uv]: https://docs.astral.sh/uv
+[uv-snap]: https://snapcraft.io/astral-uv
+[tox]: https://tox.wiki/en/4.32.0/
+[charmcraft-snap]: https://snapcraft.io/charmcraft

agent/charms/testflinger-agent-host-charm/README.md

@@ -1,5 +1,9 @@
 # Testflinger Agent Host Charm
 
+[![Charmcraft][charmcraft-badge]][charmcraft-site]
+[![uv Status][uv-badge]][uv-site]
+[![Ruff status][ruff-badge]][ruff-site]
+
 ## Overview
 
 This charm provides the base system for a host system that will be used for
@@ -10,12 +14,12 @@ in `src/tf-cmd-scripts/` to the host system. The scripts would be used by the
 `testflinger-agent` to trigger the `testflinger-device-connector` at each
 phase.
 
-## Deploying
+## Basic Usage
 
-To deploy a Testflinger agent host from charmhub, you can use:
+On [Juju-ready][juju] systems, you can deploy it on the command-line with:
 
 ```shell
-juju deploy testflinger-agent-host --channel=edge
+juju deploy testflinger-agent-host
 ```
 
 ## Configuration
@@ -31,45 +35,16 @@ Supported options for this charm are:
 - `config-repo`:
     Git repository containing device agent configuration data
 - `config-branch`:
-    Git branch to pull for the configuration data
+    Git branch to pull for the configuration data (default: `main`)
 - `config-dir`:
     Path from the root of the configuration repository where the
     directories and configurations are located for this agent host
-
-To keep the tf-cmd-scripts files up-to-date, run:
-
-```shell
-juju upgrade-charm {testflinger-agent-host-application}
-```
-
-The `config-repo` where the Testflinger configurations for the agents are stored
-should contain a directory tree. The leaf directories should be named the same
-as the `agent-id` configured for the agent in the `testflinger-agent.conf`
-file, and this directory should contain the configuration files for both the
-agent and the device connector. For example, consider a repository containing
-the configurations for multiple locations and agents. It might have a structure
-like this:
-
-```text
-/
-- lab1/
-  - agent-101/
-    - testflinger-agent.conf
-    - default.yaml
-  - agent-102/
-    - testflinger-agent.conf
-    - default.yaml
-  - ...
-- lab2/
-  - agent-201/
-    - testflinger-agent.conf
-    - default.yaml
-  - ...
-...
-```
-
-In order to make the charm consider only the agents under the `lab1` directory,
-you should set the `config-dir` to `lab1`.
+- `testflinger-server`:
+    The hostname of the Testflinger server to connect to, this is required
+    for authentication (default: `https://testflinger.canonical.com`)
+- `credentials-secret`: 
+    URI to the Juju Secret that contains the credentials to perform authentication
+    against `testflinger-server`
 
 ## Actions
 
@@ -79,7 +54,9 @@ The following actions are supported for this charm:
     This action is used to update the `testflinger-agent` and install it to a
     location shared by all the agents running on this host.
     This action will trigger all running agents to restart when they are not
-    running a job.
+    running a job. The following key is optional:
+    - `branch`: The name of the branch to pull Testflinger agent code
+      from (default if not specified is `main`)
 - `update-configs`:
     This action pulls the git repository set in the charm configuration to
     update the agent configurations on the agent host.
@@ -90,99 +67,29 @@ The following actions are supported for this charm:
     running agents to restart when they are not running a job in case the
     Testflinger configuration has changed.
 
-## Building
-
-To build this charm, first install charmcraft:
-
-```shell
-sudo snap instsall --classic charmcraft
-```
-
-Then build the charm:
-
-```shell
-charmcraft pack
-```
-
-## Testing
-
-This charm includes both unit and integration tests. The integration tests
-take some time to run and require setting up juju in your test environment
-as described [here][set-up-juju].
-
-Once you've done that, you can run all the unit and integration tests by
-going up 2 directories from here to the `agent` directory, and running:
-
-```shell
-tox -e charm
-```
-
-For debugging, it can be useful to keep the model that was deployed so that
-it can be reused. To do this, you can add a few additional arguments to tox:
-
-```shell
-tox -e charm -v -- --model=testmodel --keep-models
-```
-
-This will create a model called `testmodel` and keep it after the run is
-complete. If you want to reuse it without deploying again, you can
-run the same command again with `--no-deploy` at the end.
-
-## Operational Notes
-
-### Using supervisorctl on the agent host to check status
-
-The agent host is configured to use supervisorctl to manage the agents. From the
-agent host, you can run `sudo supervisorctl status` to see the status of all the
-agents configured on it.
-
-### Viewing the agent logs
-
-To show the logs for a specific agent, run
-`sudo supervisorctl tail <agent name>`. You can also use the `-f` option to
-follow the logs.
-
-To show the logs for supervisorctl itself, to see what it's recently started,
-stopped, or signalled, you can use `supervisorctl maintail`.
-
-### Stopping and restarting agents
 
-You can use `sudo supervisorctl stop <agent name>` to stop a specific agent.
-Be aware that other actions on the charm such as `update-configs` might later
-cause this to restart the agents. In order to mark it offline so that it will
-no longer process jobs, you may want to either remove it completely from the
-configurations, or set a disable marker file using
-`touch /tmp/TESTFLINGER-DEVICE-OFFLINE-<agent name>` instead.
+## Community and Support
 
-To signal an agent to safely restart when it's no longer running a job, you can
-run `sudo supervisorctl signal USR1 <agent name>`.
+You can report any issues, bugs, or feature requests on the project's
+[GitHub repository][canonical/testflinger].
 
-### Updating agent configs
+## Contribute to the Testflinger Agent Host Charm
 
-If the agent configurations in the `config-repo` have changed, you can run
-`juju run testflinger-agent-host-application/0 update-configs`
-(use `run-action` for juju < 3.x) to update the agent configurations on the
-agent host. This will automatically add any new agents, remove any agents that
-are no longer configured, and all agents will be sent a signal to restart when
-they are not running a job.
+The Testflinger Agent Host Charm is open source. Contributions are welcome.
 
-### Updating the Testflinger repository
+If you're interested, start with the [charm contribution guide](CONTRIBUTING.md).
 
-When the code for the agent or device connectors changes, you can run
-`juju run testflinger-agent-host-application/0 update-testflinger` to update
-the Testflinger repository on the agent host. This will automatically trigger
-a safe restart on all the agents after installing the new code.
+## License and Copyright
 
-### Changes to the supervisord configurations
+The Testflinger Agent Host Charm is released under the [Apache-2.0 license](LICENSE).
 
-Be aware that if you change anything in the supervisord configurations under
-`/etc/supervisor/conf.d`, the agents will be **forced** to restart without
-waiting for running jobs to terminate the next time you run the
-`update-configs` action or perform a configuration change in the charm. This is
-because it runs `supervisorctl update`. This should not normally happen, but if
-for some reason you need to make a change to the charm that causes it to write
-changes to the supervisord configurations, then you should take precautions to
-ensure that the agents are not running jobs when `supervisord update` is run the
-next time.
+© 2026 Canonical Ltd.
 
-[set-up-juju]: https://juju.is/docs/sdk/dev-setup#heading--manual-set-up-juju
+[juju]: https://canonical.com/juju
+[charmcraft-badge]: https://charmhub.io/testflinger-agent-host/badge.svg
+[charmcraft-site]: https://charmhub.io/testflinger-agent-host
+[uv-badge]: https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/astral-sh/uv/main/assets/badge/v0.json
+[uv-site]: https://github.com/astral-sh/uv
+[ruff-badge]: https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/astral-sh/ruff/main/assets/badge/v2.json
+[ruff-site]: https://github.com/astral-sh/ruff
+[canonical/testflinger]: https://github.com/canonical/testflinger

docs/.custom_wordlist.txt

@@ -14,5 +14,6 @@ Queryable
 rclone
 SDWire
 stderr
+supervisorctl
 Tegra
 WebDAV

docs/explanation/agents.rst

@@ -33,6 +33,8 @@ able to communicate with the server. If an agent has not checked in after 7 days
 it will automatically be removed from the database and will no longer appear in
 the "Agents" list.
 
+.. _handling-agent-status:
+
 Handling Agent Status
 -------------------------------------------