docs: Refactor docs (#398)

* docs: Refactor docs

Signed-off-by: jannfis <jann@mistrust.net>

* Fix spelling

Signed-off-by: jannfis <jann@mistrust.net>

* Fix spelling

Signed-off-by: jannfis <jann@mistrust.net>

* Sort expect

Signed-off-by: jannfis <jann@mistrust.net>

17 files changed, 1243 insertions, 522 deletions

diff --git a/.github/actions/spelling/expect.txt b/.github/actions/spelling/expect.txt
index 1a53d6f..ee658fc 100644
--- a/.github/actions/spelling/expect.txt
+++ b/.github/actions/spelling/expect.txt
@@ -1,11 +1,29 @@
+
+aeece
+Artifactory
 bacd
-wohoo
-myuser
+credref
+DEBU
+DEBU
+dockerhub
+eec
+fbd
+ffb
+gitlab
+jfrog
+JFrog
+mep
 mypass
+myregistry
+myuser
 otherapp
+repocreds
+rollbacked
+someimage
+somerepo
+ssw
 wildcard
 wildcards
-credref
-repocreds
+wohoo
 yyyy
 YYYY
diff --git a/config/example-config.yaml b/config/example-config.yaml
index 98cb109..d0fd651 100644
--- a/config/example-config.yaml
+++ b/config/example-config.yaml
@@ -1,43 +1,21 @@
 # Example configuration for argocd-image-controller
-
-# Registry configuration. Each registry must have the following properties:
-# 
-# name (string)
-#   A name for the registry. Can be anything basically.
-# api_url (string)
-#   API endpoint URL
-# prefix: (string)
-#   The prefix for images from this registry
-# ping: (boolean) 
-#   Whether to perform a request on /v2 endpoint initially. Some registries
-#   do not support this.
-# credentials: (string)
-#   The credentials to use for the registry. See "specifying credentials" in
-#   the documentation for string format.
-# 
-# Exactly one registry can be specified without a prefix, which is then used
-# as the default registry for images. Most likely, this will be Docker Hub.
-#
-# Each prefix can be specified exactly once. There must not be more than one
-# registry with the same prefix configured.
 registries:
-- name: Docker Hub
+- name: Docker Hub 
   api_url: https://registry-1.docker.io
-  ping: yes
+  prefix: docker.io
   credentials: env:SOME_ENV_VAR
+  default: true
+  defaultns: library
 - name: Google Container Registry
   api_url: https://gcr.io
   prefix: gcr.io
-  ping: no
   credentials: pullsecret:foo/bar
 - name: RedHat Quay
   api_url: https://quay.io
-  ping: no
   prefix: quay.io
   credentials: secret:foo/bar#creds
 - name: GitHub Container Registry
   api_url: https://ghcr.io
-  ping: no
   prefix: ghcr.io
   credentials: ext:/some/script
   credsexpire: 5h
diff --git a/docs/assets/extra.css b/docs/assets/extra.css
index 055aff2..bc120d7 100644
--- a/docs/assets/extra.css
+++ b/docs/assets/extra.css
@@ -8,3 +8,18 @@
     background-color: transparent;
     padding: .525rem .6rem;
 }
+
+@media only screen and (min-width: 76.25em) {
+    .md-main__inner {
+      max-width: none;
+    }
+    .md-sidebar--primary {
+      left: 0;
+    }
+    .md-sidebar--secondary {
+      right: 0;
+      margin-left: 0;
+      -webkit-transform: none;
+      transform: none;   
+    }
+  }
\ No newline at end of file
diff --git a/docs/basics/authentication.md b/docs/basics/authentication.md
new file mode 100644
index 0000000..ffcc343
--- /dev/null
+++ b/docs/basics/authentication.md
@@ -0,0 +1,245 @@
+# Authentication in Argo CD Image Updater
+
+There are several scenarios where Argo CD Image Updater needs to authenticate
+to external systems in order to fulfil its duties. 
+
+## <a name="auth-kubernetes"></a>Authentication to Kubernetes
+
+If you are running Argo CD Image Updater as a Kubernetes workload in the
+`kubernetes` API access mode (which is the default), it uses the token of a
+ServiceAccount mounted to its pod to authenticate at the Kubernetes API.
+
+The name of this ServiceAccount is `argocd-image-updater`, and it gets
+created through the installation manifests in the installation namespace.
+The ServiceAccount is accompanied with an appropriate Kubernetes RBAC
+Role that holds the required permissions, and a RoleBinding to bind the
+Role to the ServiceAccount.
+
+In the default installation scenario, i.e. Argo CD Image Updater installed
+to the `argocd` namespace, no further configuration has to done in order
+for Argo CD Image Updater to access the Kubernetes API. If your Argo CD
+installation is in a different namespace than `argocd`, you would have
+to adapt the RoleBinding to bind to the ServiceAccount in the correct
+namespace.
+
+## <a name="auth-argocd"></a>Authentication to Argo CD
+
+If you are using Argo CD Image Updater to connect to Argo CD via its API,
+you will need to create credentials in Argo CD and provide them to the
+Image Updater.
+
+This usually involves the following steps:
+
+1. Create a local user with `apiKey` capabilities in Argo CD
+1. Generate an authentication token for that user
+1. Create appropriate RBAC permissions for that user in Argo CD
+1. Configure Argo CD Image Updater to connect to the Argo CD API endpoint
+   instead of the Kubernetes API
+1. Configure Argo CD Image Updater to use the credentials created in steps 1
+   and 2 for authenticating at the Argo CD API
+
+A complete walk-through can be found in the installation guide.
+
+## <a name="auth-registries"></a>Authentication to container registries
+
+If you are using private registries, or private repositories on public
+registries, chances are that you will need to have Argo CD Image Updater use
+credentials to access the registry.
+
+Credentials can be configured either on a per registry basis or on a per image
+basis. You can also use a mixed setup where credentials are configured in both
+ways.
+
+If credentials are configured on a per registry basis, all requests to that
+registry will use these credentials, without requiring any further
+configuration. Also, credentials configured for a registry will be cached
+for a configurable time and don't have to be re-read for every authentication
+requests. This can be useful especially for situations where you use tokens
+with a limited life time that are generated externally, and don't want to
+regenerate the token for each request.
+
+However, you can override the credentials used for authentication to the same
+registry on a per image basis, e.g. if you use repositories on the registry
+that require a different set of credentials.
+
+You can read more about
+[configuration credentials at the registry level]()
+and
+[configuration credentials at the image level]()
+for more details on how to configure either mechanisms.
+
+### <a name="auth-registries-creds-sources"></a>Types of supported credential sources
+
+Argo CD Image Updater can source credentials for accessing registries using the
+following mechanisms:
+
+* Secrets stored in Kubernetes. Argo CD Image Updater can either use a typical
+  Docker pull secret, or a custom secret with credentials in a certain format.
+
+* An environment variable available to Argo CD Image Updater (for example,
+  an environment variable mounted to the pod from a secret)
+
+* A script that, when executed, outputs the credentials to stdout.
+
+The following sections describe the configuration format to be used for the
+different types of credential sources.
+
+### <a name="auth-registries-pull-secret"></a>Using a pull secret
+
+A pull secret is a secret with a well-defined format, that can also be used
+by Kubernetes' container engine to pull container images from registries.
+
+These secrets typically have a field `.dockerconfigjson` in the `.data`
+section, which holds a JSON string with the appropriate credentials.
+
+In its default configuration, Argo CD Image Updater can only read secrets
+from the same namespace where it is installed to.
+
+Pull secrets can be referenced as follows in credentials configuration:
+
+```
+pullsecret:<namespace>/<secret_name>
+```
+
+Where `<namespace>` is the namespace the secret resides in, and `<secret_name>`
+is the name of the Secret resource.
+
+You can create a pull secret by using `kubectl`. The following command would
+create a pull secret for Docker Hub named `dockerhub-secret` in the namespace
+`argocd`:
+
+```shell
+kubectl create -n argocd secret docker-registry dockerhub-secret \
+  --docker-username someuser \
+  --docker-password s0m3p4ssw0rd \
+  --docker-registry "https://registry-1.docker.io"
+```
+
+This secret could then be referred to as
+
+```
+pullsecret:argocd/dockerhub-secret
+```
+
+### <a name="auth-registries-generic-secret"></a>Using a generic secret
+
+Argo CD Image Updater can also retrieve credentials from a field in a generic
+Secret. This may be useful if you have similar credentials for a different set
+of registries, and don't want to maintain a unique pull-secret for each
+registry.
+
+The credentials can be stored in any field of the Secret's `.data` section,
+but credentials must be stored in the format `<username>:<password>`.
+
+To retrieve the credentials from a generic secret, you must specify the field
+name along with the namespace and name of the secret like follows:
+
+```
+secret:<namespace>/<secret_name>#<field_name>
+```
+
+E.g. if you have stored your credentials in the field `creds` in the secret
+`some-secret` in the namespace `argocd`, you would refer to it as
+
+```
+secret:argocd/some-secret#creds
+```
+
+### <a name="auth-registries-env"></a>Using an environment variable
+
+Argo CD Image Updater can read credentials from an environment variable. This
+can be useful for testing purposes (e.g. when using the command
+`argocd-image-updater test` to test access to a registry), or if you have the
+environment variable to use mounted from a secret to the `argocd-image-updater`
+pod.
+
+To retrieve credentials from an environment variable, you must specify the name
+of the environment variable as follows:
+
+```
+env:<name_of_environment_variable>
+```
+
+The credentials passed via environment variables must be specified in the format
+`<username>:<password>`, e.g. to store credentials in an environment variable
+named `DOCKER_HUB_CREDS`:
+
+```
+DOCKER_HUB_CREDS=someuser:s0m3p4ssw0rd
+```
+
+And then, to use this environment variable, reference it as
+
+```
+env:DOCKER_HUB_CREDS
+```
+
+### <a name="auth-registries-script"></a>Using a script to generate credentials
+
+Argo CD Image Updater supports using credentials that are generated by an
+external script. In order to retrieve the credentials, Argo CD Image Updater
+will execute a user configured script or executable, and parse its output.
+
+Having a script generate the credentials can be useful if your registry does
+require a short-lived token for authentication which is issued by a third
+party system, possibly with this third party system requiring a different set
+of credentials. A prominent example would be ECR on aws.
+
+Referencing a script used to output the credentials is done as follows:
+
+```
+ext:<full_path_to_script>
+```
+
+When executing the script, Argo CD Image Updater does not pass any arguments
+to it.
+
+The executed script is expected to output exactly one line to stdout, which
+holds the credentials used for accessing the registry in the format
+`<username>:<password>`. Please note that the output should contain a newline
+character. For example, the most simple form of such a script would be:
+
+```bash
+#!/bin/sh
+
+echo "someuser:s0mep4ssw0rd"
+```
+
+When executing on Kubernetes, the script to be executed must exist in the
+Image Updater container's file system. You can either mount the script from
+a config map, or use an init container to copy it. Make sure that the script
+is executable.
+
+For example, if above script would exist at `/usr/local/bin/creds.sh`, it
+would be referenced as
+
+```
+ext:/usr/local/bin/creds.sh
+```
+
+Please keep in mind that executing scripts to retrieve credentials can become
+expensive. If possible, use this method only on a per-registry level with
+proper caching. Read more about this in the
+[Registry configuration]()
+section of the docs.
+
+* A typical pull secret, i.e. a secret containing a `.dockerconfigjson` field
+  which holds a Docker client configuration with auth information in JSON
+  format. This kind of secret is specified using the notation
+  `pullsecret:<namespace>/<secret_name>`
+
+* A custom secret, which has the credentials stored in a configurable field in
+  the format `<username>:<password>`. This kind of secret is specified using
+  the notation `secret:<namespace>/<secret_name>#<field_in_secret>`
+
+* An environment variable which holds the credentials in the format
+  `<username>:<password>`. This kind of secret is specified using the notation
+  `env:<env_var_name>`.
+
+* A script that outputs credentials on a single line to stdout, in the format
+  `<username:password>`. This can be used to support external authentication
+  mechanisms. You can specify this kind of secret in the notation
+  `ext:/path/to/script`. Please note that the script must be referenced as
+  absolute path, and must be executable (i.e. have the `+x` bit set). You
+  can add scripts to `argocd-image-updater` by using an init container.
+
diff --git a/docs/basics/update-methods.md b/docs/basics/update-methods.md
new file mode 100644
index 0000000..2a368ea
--- /dev/null
+++ b/docs/basics/update-methods.md
@@ -0,0 +1,282 @@
+# Update methods
+
+## Overview
+
+Argo CD Image Updater supports several methods to propagate new versions of the
+images to Argo CD. These methods are also refered to as *write back methods*.
+
+Currently, the following methods are supported:
+
+* [argocd](../configuration/applications.md#method-argocd)
+  directly modifies the Argo CD *Application* resource, either using Kubernetes
+  or via Argo CD API, depending on Argo CD Image Updater's configuration.
+
+* [git](../configuration/applications.md#method-git)
+  will create a Git commit in your Application's Git repository that holds the
+  information about the image to update to.
+
+Depending on the write back method, further configuration may be possible.
+
+The write back method and its configuration is specified per Application.
+
+## <a name="method-argocd"></a>`argocd` write-back method
+
+When using the Argo CD API to write back changes, Argo CD Image Updater will
+perform a similar action as `argocd app set --parameter ...` to instruct
+Argo CD to re-render the manifests using those parameters.
+
+This method is pseudo-persistent. If you delete the `Application` resource
+from the cluster and re-create it, changes made by Image Updater will be gone.
+The same is true if you manage your `Application` resources using Git, and
+the version stored in Git is synced over the resource in the cluster. This
+method is most suitable for Applications also created imperatively, i.e.
+using the Web UI or CLI.
+
+This method is the default and requires no further configuration.
+
+## <a name="method-git"></a>`git` write-back method
+
+!!!warning "Compatibility with Argo CD"
+    The Git write-back method requires a feature in Argo CD that has been
+    introduced with Argo CD v2.0. Git write-back will not work with earlier
+    versions of Argo CD.
+
+The `git` write-back method uses Git to permanently store its parameter
+overrides along with the Application's resource manifests. This will enable
+persistent storage of the parameters in Git.
+
+By default, Argo CD Image Updater will store the parameter in a file named
+`.argocd-source-<appName>.yaml` in the path used by the Application to source
+its manifests from. This will allow Argo CD to pick up parameters in this
+file, when rendering manifests for the Application named `<appName>`. Using
+this approach will also minimize the possibility of merge conflicts, as long
+as no other party in your CI will modify this file.
+
+!!!note "A note on the application's target revision"
+    Due to the nature of how Git write-back works, your application really
+    should track a *branch* instead of a revision. If you track `HEAD`, a tag
+    or a certain revision with your application, you **must** override the
+    branch in an annotation (see below). But in order for Argo CD to pick up
+    the change after Image Updater has committed & pushed the change, you
+    really want to set it up so it tracks a branch.
+
+To use the Git write-back method, annotate your `Application` with the right
+write-back method:
+
+```yaml
+argocd-image-updater.argoproj.io/write-back-method: git
+```
+
+In order to better decide whether this method is suitable for your use-case,
+this is the workflow how Argo CD Image Updater performs change to Git:
+
+* Fetch the remote repository from location specified by `.spec.source.repoURL`
+  in the Argo CD Application manifest, using credentials specified as annotation
+  (see below)
+* Check-out the target branch on the local copy. The target branch is either
+  taken from an annotation (see below), or if no annotation is set, taken from
+  `.spec.source.targetRevision` in the Application manifest
+* Create or update `.argocd-source-<appName>.yaml` in the local repository
+* Commit the changed file to the local repository
+* Push the commit to the remote repository, using credentials specified as
+  annotation (see below)
+
+The important pieces to this workflow are:
+
+* Credentials configured in Argo CD will be re-used, unless you override with a
+  dedicated set of credentials
+
+* Write-back is a commit to the tracking branch of the Application.
+
+* If `.spec.source.targetRevision` does not reference a *branch*, you will have
+  to specify the branch to use manually (see below)
+
+### <a name="method-git-general-config"></a>General configuration
+
+Configuration for the Git write-back method comes from two sources:
+
+* The Argo CD `Application` manifest is used to define the repository and the
+  path where the `.argocd-source-<appName>.yaml` should be written to. These
+  are defined in `.spec.source.repoURL` and `.spec.source.path` fields,
+  respectively. Additionally, `.spec.source.targetRevision` is used to define
+  the branch to commit and push the changes to. The branch to use can be
+  overridden by an annotation, see below.
+
+* A set of annotations on the `Application` manifest, see below
+
+### <a name="method-git-credentials"></a>Specifying Git credentials
+
+By default Argo CD Image Updater re-uses the credentials you have configured
+in Argo CD for accessing the repository.
+
+If you don't want to use credentials configured for Argo CD you can use other credentials stored in a Kubernetes secret,
+which needs to be accessible by the Argo CD Image Updater's Service Account. The secret should be specified in 
+`argocd-image-updater.argoproj.io/write-back-method` annotation using `git:<credref>` format. Where `<credref>` might
+take one of following values:
+
+* `repocreds` (default) - Git repository credentials configured in Argo CD settings
+* `secret:<namespace>/<secret>` - namespace and secret name.
+
+Example:
+
+```yaml
+argocd-image-updater.argoproj.io/write-back-method: git:secret:argocd-image-updater/git-creds
+```
+
+If the repository is accessed using HTTPS, the secret must contain two fields:
+`username` which holds the Git username, and `password` which holds the user's
+password or a private access token (PAT) with write access to the repository.
+You can generate such a secret using `kubectl`, e.g.:
+
+```bash
+kubectl -n argocd-image-updater create secret generic git-creds \
+  --from-literal=username=someuser \
+  --from-literal=password=somepassword
+```
+
+If the repository is accessed using SSH, the secret must contain the field
+`sshPrivateKey`, which holds a SSH private key in OpenSSH-compatible PEM
+format. To create such a secret from an existing private key, you can use
+`kubectl`, for example:
+
+```bash
+kubectl -n argocd-image-updater create secret generic git-creds \
+  --from-file=sshPrivateKey=~/.ssh/id_rsa
+```
+
+### <a name="method-git-branch"></a>Specifying a branch to commit to
+
+By default, Argo CD Image Updater will use the value found in the Application
+spec at `.spec.source.targetRevision` as Git branch to checkout, commit to
+and push back the changes it made. In some scenarios, this might not be what
+is desired, and you can (and maybe have to) override the branch to use by
+specifying the annotation `argocd-image-updater.argoproj.io/git-branch` on the
+Application manifest.
+
+The value of this annotation will define the Git branch to use, for example the
+following would use GitHub's default `main` branch:
+
+```yaml
+argocd-image-updater.argoproj.io/git-branch: main
+```
+
+### <a name="method-git-base-commit-branch"></a>Specifying a separate base and commit branch
+
+By default, Argo CD Imager Updater will checkout, commit, and push back to the
+same branch specified above. There are many scenarios where this is not
+desired or possible, such as when the default branch is protected. You can
+add a separate write-branch by modifying `argocd-image-updater.argoproj.io/git-branch`
+with additional data, which will create a new branch from the base branch, and
+push to this new branch instead:
+
+```yaml
+argocd-image-updater.argoproj.io/git-branch: base:target
+```
+
+If you want to specify a write-branch but continue to use the target revision from the application
+specification, just omit the base branch name:
+
+```yaml
+argocd-image-updater.argoproj.io/git-branch: :target
+```
+
+A static branch name may not be desired for this value, so a simple template
+can be created (evaluating using the `text/template` Golang package) within
+the annotation. For example, the following would create a branch named
+`image-updater-foo/bar-1.1` based on `main` in the event an image with
+the name `foo/bar` was updated to the new tag `1.1`.
+
+```yaml
+argocd-image-updater.argoproj.io/git-branch: main:image-updater{{range .Images}}-{{.Name}}-{{.NewTag}}{{end}}
+```
+
+Alternatively, to assure unique branch names you could use the SHA1 representation of the changes:
+
+```yaml
+argocd-image-updater.argoproj.io/git-branch: main:image-updater-{{.SHA256}}
+```
+
+The following variables are provided for this template:
+
+* `.Images` is a list of changes that were performed by the update. Each
+  entry in this list is a struct providing the following information for
+  each change:
+  * `.Name` holds the full name of the image that was updated
+  * `.Alias` holds the alias of the image that was updated
+  * `.OldTag` holds the tag name or SHA digest previous to the update
+  * `.NewTag` holds the tag name or SHA digest that was updated to
+* `.SHA256` is a unique SHA256 has representing these changes
+
+Please note that if the output of the template exceeds 255 characters (git branch name limit) it will be truncated.
+
+### <a name="method-git-commit-user"></a>Specifying the user and email address for commits
+
+Each Git commit is associated with an author's name and email address. If not
+configured, commits performed by Argo CD Image Updater will use
+`argocd-image-updater <noreply@argoproj.io>`
+as the author. You can override the author using the
+`--git-commit-user` and `--git-commit-email` command line switches or set
+`git.user` and `git.email`
+in the `argocd-image-updater-config` ConfigMap.
+
+### <a name="method-git-commit-message"></a>Changing the Git commit message
+
+You can change the default commit message used by Argo CD Image Updater to some
+message that best suites your processes and regulations. For this, a simple
+template can be created (evaluating using the `text/template` Golang package)
+and made available through setting the key `git.commit-message-template` in the
+`argocd-image-updater-config` ConfigMap to the template's contents, e.g.
+
+```yaml
+data:
+  git.commit-message-template: |
+    build: automatic update of {{ .AppName }}
+
+    {{ range .AppChanges -}}
+    updates image {{ .Image }} tag '{{ .OldTag }}' to '{{ .NewTag }}'
+    {{ end -}}
+```
+
+Two top-level variables are provided to the template:
+
+* `.AppName` is the name of the application that is being updated
+* `.AppChanges` is a list of changes that were performed by the update. Each
+  entry in this list is a struct providing the following information for
+  each change:
+  * `.Image` holds the full name of the image that was updated
+  * `.OldTag` holds the tag name or SHA digest previous to the update
+  * `.NewTag` holds the tag name or SHA digest that was updated to
+
+In order to test a template before configuring it for use in Image Updater,
+you can store the template you want to use in a temporary file, and then use
+the `argocd-image-updater template /path/to/file` command to render the
+template using pre-defined data and see its outcome on the terminal.
+
+### <a name="method-git-target"></a>Git Write-Back Target
+
+By default, git write-back will create or update `.argocd-source-<appName>.yaml`.
+
+If you are using Kustomize and want the image updates available for normal use with `kustomize`,
+you may set the `write-back-target` to `kustomization`. This method commits changes to the Kustomization
+file back to git as though you ran `kustomize edit set image`.
+
+```yaml
+argocd-image-updater.argoproj.io/write-back-method: git  # all git options are supported
+argocd-image-updater.argoproj.io/write-back-target: kustomization
+```
+
+You may also specify which kustomization to update with either a path relative to the project source path...
+
+```yaml
+argocd-image-updater.argoproj.io/write-back-target: "kustomization:../../base"
+# if the Application spec.source.path = config/overlays/foo, this would update the kustomization in config/base 
+```
+
+...or absolute with respect to the repository:
+
+```yaml
+# absolute paths start with /
+argocd-image-updater.argoproj.io/write-back-target: "kustomization:/config/overlays/bar"
+```
+
+Note that the Kustomization directory needs to be specified, not a file, like when using Kustomize.
diff --git a/docs/install/strategies.md b/docs/basics/update-strategies.md
index e9d8b67..453cbf1 100644
--- a/docs/install/strategies.md
+++ b/docs/basics/update-strategies.md
@@ -1,27 +1,45 @@
 # Update strategies
 
+## <a name="supported-strategies"></a>Supported update strategies
+
+An update strategy defines how Argo CD Image Updater will find new versions of
+an image that is to be updated.
+
 Argo CD Image Updater supports different update strategies for the images that
 are configured to be tracked and updated.
 
-You can configure the strategy to be used for each image individually, with the
-default strategy being `semver` (see below).
+You can configure the update strategy to be used for each image individually,
+with the default being the `semver` strategy.
+
+The following update strategies are currently supported:
+
+* [semver](#strategy-semver) - Update to the latest version of an image
+  considering semantic versioning constraints
+* [latest](#strategy-latest) - Update to the most recently built image found in a registry
+* [digest](#strategy-digest) - Update to the latest version of a given version (tag), using the tag's SHA digest
+* [name](#strategy-name) - Sorts tags alphabetically and update to the one with the highest cardinality
 
 Some of the strategies will require additional configuration, or can be tweaked
 with additional parameters. Please have a look at the
 [image configuration](../../configuration/images)
 documentation for more details.
 
+## <a name="mutable-immutable"></a>Mutable vs immutable tags
+
 Please note that all update strategies except `digest` assume tags to be
 *immutable* and that new images will be pushed with a new, unique tag. If
 you want to update to *mutable* tags (e.g. the commonly used `latest` tag),
 you should use the `digest` strategy.
 
-## Update to semantic versions
+## Update strategies in detail
+### <a name="strategy-semver"></a>semver - Update to semantic versions
 
 This is the default strategy.
 
 Strategy name: `semver`
 
+Basic configuration:
+
 ```yaml
 argocd-image-updater.argoproj.io/image-list: some/image[:<version_constraint>]
 # Specifying update-strategy is optional, because semver is the default
@@ -79,7 +97,7 @@ Image Updater will pick the highest version number found in the registry.
 Argo CD Image Updater will omit any tags from your registry that do not match 
 a semantic version when using the `semver` update strategy.
 
-## Update to the most recently built image
+### <a name="strategy-latest"></a>latest - Update to the most recently built image
 
 !!!warning
     As of November 2020, Docker Hub has introduced pull limits for accounts on
@@ -89,8 +107,16 @@ a semantic version when using the `semver` update strategy.
     by these pull limits, it is **not recommended** to use the `latest` update
     strategy with images hosted on Docker Hub.
 
+!!!note
+    If you are using *reproducible builds* for your container images (e.g. if
+    your build pipeline always sets the creation date of the image to the same
+    value), the `latest` strategy will not be able to determine which tag to
+    update to.
+
 Strategy name: `latest`
 
+Basic configuration:
+
 ```yaml
 argocd-image-updater.argoproj.io/image-list: <alias>=some/image
 argocd-image-updater.argoproj.io/<alias>.update-strategy: latest
@@ -138,10 +164,12 @@ This would allow for considering all tags found but `latest` and `master`. You
 can read more about filtering tags
 [here](../../configuration/images/#filtering-tags).
 
-## Update to the most recent pushed version of a tag
+### <a name="strategy-digest"></a>digest - Update to the most recent pushed version of a given tag
 
 Strategy name: `digest`
 
+Basic configuration:
+
 ```yaml
 argocd-image-updater.argoproj.io/image-list: <alias>=some/image:<tag_name>
 argocd-image-updater.argoproj.io/<alias>.update-strategy: digest
@@ -152,7 +180,8 @@ updates the image on any change to the previous state. The tag name to be
 inspected must be specified as a version constraint in the image list.
 
 Use this update strategy if you want to follow a *mutable* tag, such as the
-commonly used `latest` tag. 
+commonly used `latest` tag, or when your CI system produces a tag named as
+the environment it is intended for, e.g. `dev` or `stage` or `prod`.
 
 Argo CD Image Updater will then update the image when either
 
@@ -175,10 +204,12 @@ argocd-image-updater.argoproj.io/image-list: myimage=some/image:latest
 argocd-image-updater.argoproj.io/myimage.update-strategy: digest
 ```
 
-## Update according to lexical sort
+### <a name="strategy-name"></a>Update according to lexical sort
 
 Strategy name: `name`
 
+Basic configuration:
+
 ```yaml
 argocd-image-updater.argoproj.io/image-list: <alias>=some/image
 argocd-image-updater.argoproj.io/<alias>.update-strategy: name
diff --git a/docs/basics/update.md b/docs/basics/update.md
new file mode 100644
index 0000000..30da0f7
--- /dev/null
+++ b/docs/basics/update.md
@@ -0,0 +1,85 @@
+# Updating container images
+
+## General process overview
+
+Argo CD Image Updater can update container images managed by one or more of
+your Argo CD applications, according to how it is configured.
+
+The workflow of Argo CD Image Updater can be described as follows:
+
+* It scans for currently configured Argo CD `Application` resources either
+  using the Kubernetes or the Argo CD API (depending on how you installed
+  the Argo CD Image Updater). The `Applications` to consider can be further
+  limited by having Argo CD Image Updater selecting only those applications
+  whose name match a given pattern, or match a given label.
+
+* It then goes through the list of `Applications` found and inspects each
+  for the the annotation `argocd-image-updater.argoproj.io/image-list`. This
+  annotation holds a list of image names that should be updated, and is a
+  mandatory annotation for Argo CD Image Updater to indicate it should
+  process this `Application`. Read more about the syntax expected in this
+  annotations's value in the [marking images for update](#TODO)
+  section in this doc.
+
+* For each image found in the list, Argo CD Image Updater will first check
+  if this image is actually deployed with the application. It does a strict
+  check for the complete image name, including the registry the image is
+  pulled from. For example, `docker.io/some/image` and `quay.io/some/image`,
+  while both referring to `some/image`, are not considered equal. This strict
+  behavior can be relaxed, however. See [forcing image updates](#TODO) for
+  further explanation.
+
+* If Argo CD Image Updater considers an image from the list eligible for an
+  update check, it will connect the corresponding container registry to see
+  if there is a newer version of the image according to the
+  [update strategy](../strategies/)
+  and other constraints that may have been configured for the image (e.g.
+  a list of tags that are allowed to consider).
+
+* If a newer version of an image was found, Argo CD Image Updater will try
+  to update the image according to the configured
+  [update method](../methods/). Please note that Argo CD Image Updater will
+  never update your manifests, instead it re-configures your Application
+  sources to use the new image tag, and control is handed over to Argo CD.
+
+## <a name="multi-arch"></a>Multi-arch images and clusters
+
+As of version 0.12, Argo CD Image Updater has full support for multi-arch
+images (and multi-arch clusters) by being able to inspect images with multiple
+manifests (i.e. a manifest list).
+
+Multi-arch currently only is supported for
+[update strategies](../basics/update-strategies.md)
+which fetch image meta-data: `latest` and `digest`. Multi-arch will be ignored
+for the update strategies that do not fetch meta-data, `semver` and `name`.
+
+By default, Argo CD Image Updater will only consider updating to images that
+have a manifest for the same platform where itself runs on. If you are on a
+cluster that has nodes of multiple architectures, and are pinning certain
+workloads to certain nodes, you will have to tell Argo CD Image Updater which
+platforms are allowed for a certain application or an image. This can be done
+by setting an appropriate
+[annotation per image](../configuration/images.md#platforms)
+or for all images of a given
+[application as a default setting](../configuration/images.md#appendix-defaults).
+
+Multi-arch is also implemented by the
+[test command](../install/testing.md#multi-arch).
+
+## Sync policies and image updates
+
+As explained above, the Argo CD Image Updater will assume that Argo CD will
+update the manifests in your cluster to use any new image that has been set
+by the Argo CD Image Updater.
+
+Argo CD Image Updater will work best with automatic syncing enabled for the
+Argo CD applications that are being updated.
+
+## Rollback and image updates
+
+Currently, Argo CD Image Updater does not honor the rollback status of an
+Argo CD application, and keeps updating to new images also for Applications
+that are being rolled back. However, Argo CD will disable auto-sync for
+such applications.
+
+Honoring rollbacked applications correctly is on our roadmap.
diff --git a/docs/configuration/applications.md b/docs/configuration/applications.md
index 6a05d8f..c334c4b 100644
--- a/docs/configuration/applications.md
+++ b/docs/configuration/applications.md
@@ -1,6 +1,19 @@
 # Application configuration
 
-## Marking an application for being updateable
+Most of the runtime configuration for Argo CD Image Updater is performed by
+setting various annotations on resources of type `Application`, which are
+managed by Argo CD.
+
+For its annotations, Argo CD Image Updater uses the following prefix:
+
+```yaml
+argocd-image-updater.argoproj.io
+```
+
+This section of the documentation tells you about which things you can
+configure, and what annotations are available.
+
+## <a name="application-mark"></a>Marking an application for being updateable
 
 In order for Argo CD Image Updater to know which applications it should inspect
 for updating the workloads' container images, the corresponding Kubernetes
@@ -9,12 +22,6 @@ only resources of kind `application.argoproj.io`, that is, your Argo CD
 `Application` resources. Annotations on other kinds of resources will have no
 effect and will not be considered.
 
-For its annotations, Argo CD Image Updater uses the following prefix:
-
-```yaml
-argocd-image-updater.argoproj.io
-```
-
 As explained earlier, your Argo CD applications must be of either `Kustomize`
 or `Helm` type. Other types of applications will be ignored.
 
@@ -48,7 +55,10 @@ spec:
     targetRevision: HEAD
 ```
 
-## Configuring the write-back method
+There is a whole chapter dedicated on how to
+[configure images for update](../images).
+
+## <a name="configure-write-back"></a>Configuring the write-back method
 
 The Argo CD Image Updater supports two distinct methods on how to update images
 of an application:
@@ -72,264 +82,15 @@ Where `<method>` must be one of `argocd` (imperative) or `git` (declarative).
 
 The default used by Argo CD Image Updater is `argocd`.
 
-### Using the Argo CD API write-back method
-
-When using the Argo CD API to write back changes, Argo CD Image Updater will
-perform a similar action as `argocd app set --parameter ...` to instruct
-Argo CD to re-render the manifests using those parameters.
-
-This method is pseudo-persistent. If you delete the `Application` resource
-from the cluster and re-create it, changes made by Image Updater will be gone.
-The same is true if you manage your `Application` resources using Git, and
-the version stored in Git is synced over the resource in the cluster. This
-method is most suitable for Applications also created imperatively, i.e.
-using the Web UI or CLI.
-
-This method is the default and requires no further configuration.
-
-### Using the Git write-back method
-
-!!!warning "Compatibility with Argo CD"
-    The Git write-back method requires a feature in Argo CD that has been
-    introduced with Argo CD v2.0. Git write-back will not work with earlier
-    versions of Argo CD.
-
-The `git` write-back method uses Git to permanently store its parameter
-overrides along with the Application's resource manifests. This will enable
-persistent storage of the parameters in Git.
-
-By default, Argo CD Image Updater will store the parameter in a file named
-`.argocd-source-<appName>.yaml` in the path used by the Application to source
-its manifests from. This will allow Argo CD to pick up parameters in this
-file, when rendering manifests for the Application named `<appName>`. Using
-this approach will also minimize the possibility of merge conflicts, as long
-as no other party in your CI will modify this file.
-
-!!!note "A note on the application's target revision"
-    Due to the nature of how Git write-back works, your application really
-    should track a *branch* instead of a revision. If you track `HEAD`, a tag
-    or a certain revision with your application, you **must** override the
-    branch in an annotation (see below). But in order for Argo CD to pick up
-    the change after Image Updater has committed & pushed the change, you
-    really want to set it up so it tracks a branch.
-
-To use the Git write-back method, annotate your `Application` with the right
-write-back method:
-
-```yaml
-argocd-image-updater.argoproj.io/write-back-method: git
-```
-
-In order to better decide whether this method is suitable for your use-case,
-this is the workflow how Argo CD Image Updater performs change to Git:
-
-* Fetch the remote repository from location specified by `.spec.source.repoURL`
-  in the Argo CD Application manifest, using credentials specified as annotation
-  (see below)
-* Check-out the target branch on the local copy. The target branch is either
-  taken from an annotation (see below), or if no annotation is set, taken from
-  `.spec.source.targetRevision` in the Application manifest
-* Create or update `.argocd-source-<appName>.yaml` in the local repository
-* Commit the changed file to the local repository
-* Push the commit to the remote repository, using credentials specified as
-  annotation (see below)
-
-The important pieces to this workflow are:
-
-* Credentials configured in Argo CD will be re-used, unless you override with a
-  dedicated set of credentials
-
-* Write-back is a commit to the tracking branch of the Application.
-
-* If `.spec.source.targetRevision` does not reference a *branch*, you will have
-  to specify the branch to use manually (see below)
-
-#### General configuration
-
-Configuration for the Git write-back method comes from two sources:
-
-* The Argo CD `Application` manifest is used to define the repository and the
-  path where the `.argocd-source-<appName>.yaml` should be written to. These
-  are defined in `.spec.source.repoURL` and `.spec.source.path` fields,
-  respectively. Additionally, `.spec.source.targetRevision` is used to define
-  the branch to commit and push the changes to. The branch to use can be
-  overridden by an annotation, see below.
-
-* A set of annotations on the `Application` manifest, see below
-
-#### Specifying Git credentials
-
-By default Argo CD Image Updater re-uses the credentials you have configured
-in Argo CD for accessing the repository.
-
-If you don't want to use credentials configured for Argo CD you can use other credentials stored in a Kubernetes secret,
-which needs to be accessible by the Argo CD Image Updater's Service Account. The secret should be specified in 
-`argocd-image-updater.argoproj.io/write-back-method` annotation using `git:<credref>` format. Where `<credref>` might
-take one of following values:
-
-* `repocreds` (default) - Git repository credentials configured in Argo CD settings
-* `secret:<namespace>/<secret>` - namespace and secret name.
-
-Example:
-
-```yaml
-argocd-image-updater.argoproj.io/write-back-method: git:secret:argocd-image-updater/git-creds
-```
-
-If the repository is accessed using HTTPS, the secret must contain two fields:
-`username` which holds the Git username, and `password` which holds the user's
-password or a private access token (PAT) with write access to the repository.
-You can generate such a secret using `kubectl`, e.g.:
-
-```bash
-kubectl -n argocd-image-updater create secret generic git-creds \
-  --from-literal=username=someuser \
-  --from-literal=password=somepassword
-```
-
-If the repository is accessed using SSH, the secret must contain the field
-`sshPrivateKey`, which holds a SSH private key in OpenSSH-compatible PEM
-format. To create such a secret from an existing private key, you can use
-`kubectl`, for example:
-
-```bash
-kubectl -n argocd-image-updater create secret generic git-creds \
-  --from-file=sshPrivateKey=~/.ssh/id_rsa
-```
-
-#### Specifying a branch to commit to
-
-By default, Argo CD Image Updater will use the value found in the Application
-spec at `.spec.source.targetRevision` as Git branch to checkout, commit to
-and push back the changes it made. In some scenarios, this might not be what
-is desired, and you can (and maybe have to) override the branch to use by
-specifying the annotation `argocd-image-updater.argoproj.io/git-branch` on the
-Application manifest.
-
-The value of this annotation will define the Git branch to use, for example the
-following would use GitHub's default `main` branch:
-
-```yaml
-argocd-image-updater.argoproj.io/git-branch: main
-```
-
-#### Specifying a separate base and commit branch
-
-By default, Argo CD Imager Updater will checkout, commit, and push back to the
-same branch specified above. There are many scenarios where this is not
-desired or possible, such as when the default branch is protected. You can
-add a separate write-branch by modifying `argocd-image-updater.argoproj.io/git-branch`
-with additional data, which will create a new branch from the base branch, and
-push to this new branch instead:
-
-```yaml
-argocd-image-updater.argoproj.io/git-branch: base:target
-```
-
-If you want to specify a write-branch but continue to use the target revision from the application
-specification, just omit the base branch name:
-
-```yaml
-argocd-image-updater.argoproj.io/git-branch: :target
-```
-
-A static branch name may not be desired for this value, so a simple template
-can be created (evaluating using the `text/template` Golang package) within
-the annotation. For example, the following would create a branch named
-`image-updater-foo/bar-1.1` based on `main` in the event an image with
-the name `foo/bar` was updated to the new tag `1.1`.
-
-```yaml
-argocd-image-updater.argoproj.io/git-branch: main:image-updater{{range .Images}}-{{.Name}}-{{.NewTag}}{{end}}
-```
-
-Alternatively, to assure unique branch names you could use the SHA1 representation of the changes:
-
-```yaml
-argocd-image-updater.argoproj.io/git-branch: main:image-updater-{{.SHA256}}
-```
-
-The following variables are provided for this template:
+You can read more about the update methods and how to configure them in the
+[chapter about update methods](../basics/update-methods.md)
 
-* `.Images` is a list of changes that were performed by the update. Each
-  entry in this list is a struct providing the following information for
-  each change:
-  * `.Name` holds the full name of the image that was updated
-  * `.Alias` holds the alias of the image that was updated
-  * `.OldTag` holds the tag name or SHA digest previous to the update
-  * `.NewTag` holds the tag name or SHA digest that was updated to
-* `.SHA256` is a unique SHA256 has representing these changes
+## <a name="application-defaults"></a>Application defaults
 
-Please note that if the output of the template exceeds 255 characters (git branch name limit) it will be truncated.
-
-#### Specifying the user and email address for commits
-
-Each Git commit is associated with an author's name and email address. If not
-configured, commits performed by Argo CD Image Updater will use
-`argocd-image-updater <noreply@argoproj.io>`
-as the author. You can override the author using the
-`--git-commit-user` and `--git-commit-email` command line switches or set
-`git.user` and `git.email`
-in the `argocd-image-updater-config` ConfigMap.
-
-#### Changing the Git commit message
-
-You can change the default commit message used by Argo CD Image Updater to some
-message that best suites your processes and regulations. For this, a simple
-template can be created (evaluating using the `text/template` Golang package)
-and made available through setting the key `git.commit-message-template` in the
-`argocd-image-updater-config` ConfigMap to the template's contents, e.g.
-
-```yaml
-data:
-  git.commit-message-template: |
-    build: automatic update of {{ .AppName }}
-
-    {{ range .AppChanges -}}
-    updates image {{ .Image }} tag '{{ .OldTag }}' to '{{ .NewTag }}'
-    {{ end -}}
-```
-
-Two top-level variables are provided to the template:
-
-* `.AppName` is the name of the application that is being updated
-* `.AppChanges` is a list of changes that were performed by the update. Each
-  entry in this list is a struct providing the following information for
-  each change:
-  * `.Image` holds the full name of the image that was updated
-  * `.OldTag` holds the tag name or SHA digest previous to the update
-  * `.NewTag` holds the tag name or SHA digest that was updated to
-
-In order to test a template before configuring it for use in Image Updater,
-you can store the template you want to use in a temporary file, and then use
-the `argocd-image-updater template /path/to/file` command to render the
-template using pre-defined data and see its outcome on the terminal.
-
-#### Git Write-Back Target
-
-By default, git write-back will create or update `.argocd-source-<appName>.yaml`.
-
-If you are using Kustomize and want the image updates available for normal use with `kustomize`,
-you may set the `write-back-target` to `kustomization`. This method commits changes to the Kustomization
-file back to git as though you ran `kustomize edit set image`.
-
-```yaml
-argocd-image-updater.argoproj.io/write-back-method: git  # all git options are supported
-argocd-image-updater.argoproj.io/write-back-target: kustomization
-```
-
-You may also specify which kustomization to update with either a path relative to the project source path...
-
-```yaml
-argocd-image-updater.argoproj.io/write-back-target: "kustomization:../../base"
-# if the Application spec.source.path = config/overlays/foo, this would update the kustomization in config/base 
-```
-
-...or absolute with respect to the repository:
-
-```yaml
-# absolute paths start with /
-argocd-image-updater.argoproj.io/write-back-target: "kustomization:/config/overlays/bar"
-```
+Additional to per-image configuration, you can also set some defaults for the
+application.
 
-Note that the Kustomization directory needs to be specified, not a file, like when using Kustomize.
+For example, if you have multiple images tracked in your application, and all
+of them should use the `latest` update strategy, you can define this strategy
+as the application's default and may omit any specific configuration for the
+images' update strategy.
diff --git a/docs/configuration/images.md b/docs/configuration/images.md
index f5e67f9..7edf9bb 100644
--- a/docs/configuration/images.md
+++ b/docs/configuration/images.md
@@ -61,13 +61,12 @@ of the [Semver library](https://github.com/Masterminds/semver) we're using.
     [filtering tags](#filtering-tags)
     below.
 
-
 ### Forcing Image Updates
 
 By default, Image Updater will only update an image that is actually used in your Application
 (i.e., is it exported in the Status of your ArgoCD Application.)
 
-To support custom resources and things like PodTemplates that don't actually create a container, 
+To support custom resources and things like PodTemplates that don't actually create a container,
 you may force an update:
 
 ```yaml
@@ -75,7 +74,6 @@ argocd-image-updater.argoproj.io/image-list: myalias=some/image
 argocd-image-updater.argoproj.io/myalias.force-update: "true"
 ```
 
-
 ## Assigning aliases to images
 
 It's possible (and sometimes necessary) to assign an alias name to any given
@@ -108,6 +106,11 @@ as `_` (underscore) in the annotation. This is a limit of Kubernetes. So for
 example, if you assign the alias `argoproj/argocd` to your image, the
 appropriate key in the annotation would be referenced as `argoproj_argocd`.
 
+!!!note
+    It is generally recommended to set aliases for each of your images. Many of
+    the features depend on an alias being set, and aliases might become a strict
+    requirement in the future.
+
 ## Update strategies
 
 Argo CD Image Updater can update images according to the following strategies:
@@ -137,7 +140,6 @@ strategy `semver` will be used.
     by these pull limits, it is **not recommended** to use the `latest` update
     strategy with images hosted on Docker Hub.
 
-
 ## Filtering tags
 
 You can specify an expression that is matched against each tag returned from
@@ -190,7 +192,38 @@ argocd-image-updater.argoproj.io/<image_name>.ignore-tags: "*"
 
 Please note that regular expressions are not supported to be used for patterns.
 
-## Specifying pull secrets
+## <a name="platforms"></a>Image platforms
+
+By default, Argo CD Image Updater will only consider images from the registry
+that are built for the same platform as the one Argo CD Image Updater is
+running on. In multi-arch clusters, your workloads may be targeted to a
+different platform, and you can configure the allowed platforms for a given
+image.
+
+For example, when Argo CD Image Updater is running on a `linux/amd64` node but
+your application will be executed on a node with `linux/arm64` platform, you
+need to let Argo CD Image Updater know:
+
+```yaml
+argocd-image-updater.argoproj.io/<image_alias>.platforms: linux/arm64
+```
+
+You can specify multiple allowed platforms as a comma separated list of allowed
+platforms:
+
+```yaml
+argocd-image-updater.argoproj.io/<image_alias>.platforms: linux/arm64,linux/amd64
+```
+
+The correct image to execute will be chosen by Kubernetes.
+
+!!!note
+    The `platforms` annotation only has effect for images that use an update
+    strategy which fetches meta-data. Currently, these are the `latest` and
+    `digest` strategies. For `semver` and `name` strategies, the `platforms`
+    setting has no effect.
+
+## <a name="pull-secrets"></a>Specifying pull secrets
 
 There are generally two ways on how to specify pull secrets for Argo CD Image
 Updater to use. Either you configure a secret reference globally for the
@@ -384,27 +417,52 @@ argocd-image-updater.argoproj.io/baralias.helm.image-name: bar.image
 argocd-image-updater.argoproj.io/baralias.helm.image-tag: bar.tag
 ```
 
+### Tracking an image's `latest` tag
+
+*Scenario:* You want to track the latest build of a given tag, e.g. the `latest`
+tag that many images use without having to restart your pods manually.
+
+*Solution:*
+
+1. Define an alias for your image, i.e. `fooalias`
+
+2. Set the constraint of your image to the tag you want to track, e.g. `latest`
+
+3. Set the update strategy for this image to `digest`
+
+```yaml
+argocd-image-updater.argoproj.io/image-list: fooalias=yourorg/yourimage:latest
+argocd-image-updater.argoproj.io/fooalias.update-strategy: digest
+```
+
+When there's a new build for `yourorg/yourimage:latest` found in the registry,
+Argo CD Image Updater will update your configuration to use the SHA256 sum of
+the image, and Kubernetes will restart your pods automatically to have them
+use the new image.
+
 ## Appendix
 
-### Available annotations
+### <a name="appendix-annotations"></a>Available annotations
 
 The following is a complete list of available annotations to control the
 update strategy and set options for images. Please note, all annotations
-must be prefixed with `argocd-image-updater.argoproj.io`.
+must be prefixed with `argocd-image-updater.argoproj.io/`.
 
 |Annotation name|Default value|Description|
 |---------------|-------|-----------|
 |`image-list`|*none*|Comma separated list of images to consider for update|
 |`<image_alias>.update-strategy`|`semver`|The update strategy to be used for the image|
+|`<image_alias>.force-update`|`"false"`|If set to "true" (with quotes), even images that are not currently deployed will be updated|
 |`<image_alias>.allow-tags`|*any*|A function to match tag names from registry against to be considered for update|
 |`<image_alias>.ignore-tags`|*none*|A comma-separated list of glob patterns that when match ignore a certain tag from the registry|
 |`<image_alias>.pull-secret`|*none*|A reference to a secret to be used as registry credentials for this image|
+|`<image_alias>.platform`|*none*|Only update to images for given platform(s). Comma separated list, e.g. `linux/amd64,linux/arm64`|
 |`<image_alias>.helm.image-spec`|*none*|Name of the Helm parameter to specify the canonical name of the image, i.e. holds `image/name:1.0`. If this is set, other Helm parameter related options will be ignored.|
 |`<image_alias>.helm.image-name`|`image.name`|Name of the Helm parameter used for specifying the image name, i.e. holds `image/name`|
 |`<image_alias>.helm.image-tag`|`image.tag`|Name of the Helm parameter used for specifying the image tag, i.e. holds `1.0`|
 |`<image_alias>.kustomize.image-name`|*original name of image*|Name of Kustomize image parameter to set during updates|
 
-### Application-wide defaults
+### <a name="appendix-defaults"></a>Application-wide defaults
 
 If you want to update multiple images in an Application, that all share common
 settings (such as, update strategy, allowed tags, etc), you can define common
diff --git a/docs/configuration/registries.md b/docs/configuration/registries.md
index fd9f346..8a20582 100644
--- a/docs/configuration/registries.md
+++ b/docs/configuration/registries.md
@@ -1,128 +1,201 @@
-# Configuring Container Registries
+# Configuration of Container Registries
 
-Argo CD Image Updater comes with support for the following registries out of the
-box:
+## <a name="supported-registries"></a>Supported registries
 
-* Docker Hub Registry
-* Google Container Registry (*gcr.io*)
-* RedHat Quay Registry (*quay.io*)
-* GitHub Docker Packages (*docker.pkg.github.com*)
-* GitHub Container Registry (*ghcr.io*)
+Argo CD Image Updater comes with out of the box support for most container
+registries that implement the Docker registry v2 API.
 
-Adding additional (and custom) container registries is supported by means of a
-configuration file. If you run Argo CD Image Updater within Kubernetes, you can
-edit the registries in a ConfigMap resource, which will get mounted to the pod
-running Argo CD Image Updater.
+It has been successfully tested against the following popular registries:
 
-## Configuring a custom container registry
+* Docker Hub (`docker.io`)
+* Docker Registry v2 reference implementation (on-premise)
+* Red Hat Quay (`quay.io` and on-premise)
+* JFrog Artifactory (`jfrog.io` and on-premise)
+* GitHub Container Registry (`ghcr.io`)
+* GitHub Packages Registry (`docker.pkg.github.com`)
+* GitLab Container Registry (`registry.gitlab.com`)
+* Google Container Registry (`gcr.io`)
 
-A sample configuration configuring a couple of registries might look like the
-following:
+Chances are, that it will work out of the box for other registries as well.
 
-```yaml
-registries:
-- name: Docker Hub
-  api_url: https://registry-1.docker.io
-  ping: yes
-  credentials: secret:foo/bar#creds
-  defaultns: library
-- name: Google Container Registry
-  api_url: https://gcr.io
-  prefix: gcr.io
-  ping: no
-  credentials: pullsecret:foo/bar
-- name: RedHat Quay
-  api_url: https://quay.io
-  ping: no
-  prefix: quay.io
-  insecure: yes
-  credentials: env:REGISTRY_SECRET
-- name: GitHub Docker Packages
-  prefix: docker.pkg.github.com
-  api_url: https://docker.pkg.github.com
-  ping: no
-  tagsortmode: latest-first
-- name: GitHub Container Registry
-  prefix: ghcr.io
-  api_url: https://docker.pkg.github.com
-  ping: no
-  tagsortmode: latest-last
+If you have a registry that doesn't work with Argo CD Image Updater, please
+let us know.
+
+## <a name="custom-registry-when"></a>When to configure a custom registry?
+
+Generally, there is no need to configure custom registries. Image Updater will
+infer the registry from the image slug, e.g. if you are using an image that is
+defined as `ghcr.io/somerepo/someimage`, Image Updater will infer the registry
+from the `ghcr.io` prefix and use the Docker registry at `https://ghcr.io/v2`.
+
+However, there may be reasons when you need to configure a custom registry, or
+adapt the default settings to your requirements:
+
+* Your registry uses a self-signed (or not publicly known) TLS certificate,
+  and you want to either turn off TLS certificate verification or provide a
+  custom CA certificate to be used for verification
+
+* Your registry has its API endpoint at a different location. One notable
+  example is Docker Hub, which uses `docker.io` as image prefix but the
+  registry is at `registry-1.docker.io`. However, this quirk related to
+  Docker Hub has been accounted for in Argo CD Image Updater, so you won't
+  have to configure Docker Hub as a custom registry.
+
+* You want to use a certain registry with deviations from the default settings,
+  such as setting a custom rate limit, or configuring global credentials for
+  accessing that registry.
+
+* Your cluster's container engine is set up to use a different registry than
+  `docker.io` as the default so that it does not pull images from Docker Hub
+  when no prefix is specified, but e.g. from an on-premise registry.
+
+## Can I use my registry without further configuration?
+
+There is an easy way to find out by running the argocd-image-updater CLI in
+[test mode](../install/testing.md). You can run the CLI either from your
+workstation (if the registry is reachable from there) or from the pod deployed
+to your cluster.
+
+Assuming you have an image at `myregistry.com/somerepo/someimage`, and you
+want to find out if Argo CD Image Updater could possibly connect to that
+specific registry at `myregistry.com` and gather information about the image,
+run the following command:
+
+```
+argocd-image-updater test myregistry.com/somerepo/someimage
 ```
 
-The above example defines access to three registries. The properties have the
-following semantics:
+You may also want to pass some options to that command to set the appropriate
+[update strategy](../basics/update-strategies.md)
+or
+[credentials](../basics/authentication.md)
+to access the registry.
 
-* `name` is just a symbolic name for the registry. Must be unique.
+The `argocd-image-updater test` command won't perform any modifications to
+your cluster or your workloads.
 
-* `api_url` is the base URL (without `/v2` suffix) to the API of the registry
+## <a name="custom-registries"></a>Configuring custom registries
+### <a name="registry-configuration-format"></a>Configuration format
 
-* `ping` specifies whether to send a ping request to `/v2` endpoint first.
-  Some registries don't support this.
+Registries are configured in a configuration file in YAML syntax. That YAML
+must have a top level key of `registries`, which holds a list of registries
+to be configured. Each item in the list represents a single registry. You
+can add as many registries as you like.
 
-* `prefix` is the prefix used in the image specification. This prefix will
-  be consulted when determining the configuration for given image(s). If no
-  prefix is specified, will be used as the default registry. The prefix is
-  mandatory, except for one of the registries in the configuration.
+The following properties can be set to configure a registry. Most of these
+properties are optional, unless otherwise stated:
 
-* `credentials` (optional) is a reference to the credentials to use for
-  accessing the registry API (see below). Credentials can also be specified
-  [per image](../images/#specifying-pull-secrets)
+  * `name` (mandatory) - The symbolic name for your registry. Can be any string,
+    used only for informational purposes.
 
-* `credsexpire` (optional) can be used to set an expiry time for the
-   credentials. The value must be in a `time.Duration` compatible format,
-   having a unit suffix, i.e. `5s` for 5 seconds or `2h` for 2 hours. The
-   value should be positive, and `0` can be used to disable it (the default).
+    Default value: _none_
 
-   From the golang documentation:
+    Example value: `My Custom Registry`
 
-   > A duration string is a possibly signed sequence of decimal numbers, each with optional fraction and a unit suffix, such as "300ms", "-1.5h" or "2h45m". Valid time units are "ns", "us" (or "µs"), "ms", "s", "m", "h".
+  * `prefix` - (mandatory) The lookup prefix for this registry. Must match a DNS
+    name, and must be unique in the configuration.
 
-* `insecure` (optional) if set to true, does not validate the TLS certificate
-  for the connection to the registry. Use with care.
+    Default value: _none_
 
-* `defaultns` (optional) defines a default namespace for images that do not
-  specify one. For example, Docker Hub uses the default namespace `library`
-  which turns an image specification of `nginx:latest` into the canonical name
-  `library/nginx:latest`.
+    Example value: `docker.io`
+
+  * `api_url` - The URL to the API of the Docker registry. Must be a HTTP or
+    HTTPS URL.
+
+    Default value: _none_
+
+    Example value: `https://registry-1.docker.io`
+
+  * `defaultns`- Some registries (notably Docker Hub) have a default namespace,
+    which can be specified here.
+
+    Default value: _none_
+
+    Example value: `library`
+
+  * `default` - If set to true, use this registry as the default registry.
+   
+    Default value: `false`
+
+    Example value: `true`
+   
+  * `credentials` - A string describing the credential source to use when
+    accessing this registry and no other credentials are configured on the
+    image level. For more information, refer to
+    [Authenticating to container registries](../../basics/authentication/#auth-registries).
+
+    Default value: _none_
+
+    Example value: `pullsecret:argocd/dockerhub-secret`
+
+  * `credsexpire` - Whether and when credentials should expire and be
+    re-fetched. Must be specified as _Duration_ value, with an integer value
+    and a unit suffix, i.e. `s` for seconds, `m` for minutes, or `h` for hours.
+
+    Default value: _none (no expiry)_
+
+    Example value: `5h`
+  
+  * `insecure` - Whether to turn off verification of the registry's TLS
+    certificate. As the name implies, it's insecure and should not be used in
+    production environments
+
+    Default value: `false`
+
+    Example value: `true`
+
+  * `limit` - The rate limit (max. number of requests per second) to use for
+    this registry, specified as integer.
+
+    Default value: `20`
+
+    Example value: `100`
+
+The following is an example that configures two registries.
+
+```yaml
+registries:
+- name: Docker Hub
+  prefix: docker.io
+  api_url: https://registry-1.docker.io
+  credentials: secret:foo/bar#creds
+  defaultns: library
+  default: true
+- name: RedHat Quay
+  api_url: https://quay.io
+  prefix: quay.io
+  insecure: yes
+  credentials: env:REGISTRY_SECRET
+```
 
-* `tagsortmode` (optional) defines whether and how the list of tags is sorted
-  chronologically by the registry. Valid values are `latest-first` (the last
-  pushed image will appear first in list), `latest-last` (the last pushed image
-  will appear last in list) or `none` (the default, list is not chronological
-  sorted). If `tagsortmode` is set to one of `latest-first` or `latest-last`,
-  Argo CD Image Updater will not request additional meta data from the registry
-  if the `<image_alias>.sort-mode` is `latest` but will instead use the sorting
-  from the tag list.
+When running Argo CD Image Updater from the command line (e.g. using the `test`
+command), the path to this YAML file can be specified with the command line
+parameter `--registries-conf-path <path>`.
 
-If you want to take above example to the `argocd-image-updater-config` ConfigMap,
-you need to define the key `registries.conf` in the data of the ConfigMap as
-below:
+If you are running Argo CD Image Updater as a Kubernetes workload, you will
+need to tie that up in the `argocd-image-updater-config` ConfigMap, as a multi
+line string under the `registries.conf` key, e.g.:
 
 ```yaml
+apiVersion: v1
+kind: ConfigMap
+metadata:
+  name: argocd-image-updater-config
 data:
   registries.conf: |
     registries:
     - name: Docker Hub
+      prefix: docker.io
       api_url: https://registry-1.docker.io
-      ping: yes
       credentials: secret:foo/bar#creds
       defaultns: library
-    - name: Google Container Registry
-      api_url: https://gcr.io
-      prefix: gcr.io
-      ping: no
-      credentials: pullsecret:foo/bar
+      default: true
     - name: RedHat Quay
       api_url: https://quay.io
-      ping: no
       prefix: quay.io
+      insecure: yes
       credentials: env:REGISTRY_SECRET
-    - name: GitHub Container Registry
-      api_url: https://ghcr.io
-      ping: no
-      prefix: ghcr.io
-      credentials: ext:/custom/ghcr-creds.sh.io
-      credsexpire: 5h
+
 ```
 
 !!!note
@@ -130,45 +203,117 @@ data:
     configuration to take effect. There are plans to change this behaviour so
     that changes will be reload automatically in a future release.
 
-## Specifying credentials for accessing container registries
+### <a name="default-registry"></a>Configuring a default registry
+
+!!!warning
+    When you change the default registry for Argo CD Image Updater, make sure
+    it matches the default registry set up in your cluster. If the default
+    registries mismatch between the Argo CD Image Updater and your cluster,
+    it is going to break your workloads.
+
+Most container engines will follow Docker's approach and use Docker Hub as the
+default registry when no registry is specified in the image's reference. For
+example, in most environments, the two image references `argoproj/argocd` and
+`docker.io/argoproj/argocd` are semantically the same, and would refer to the
+same image stored in Docker Hub's registry. You can configure the default
+registry if your cluster's container engine is configured to use a different
+default registry than `docker.io`, which is the default for Argo CD Image
+Updater in the standard configuration.
+
+In order to set another registry to be used as default, you will have to set
+the registry's `default` property to `true`, e.g. the following:
+
+```yaml
+registries:
+- name: RedHat Quay
+  api_url: https://quay.io
+  prefix: quay.io
+  default: true
+```
+
+would make `quay.io` the default registry, so `argoproj/argocd` would become
+synonymous to `quay.io/argoproj/argocd`.
+
+Please note that you can only configure one registry as the default registry.
+If you set `default` to `true` for more than one registry's configuration,
+Argo CD Image Updater will not load that configuration.
 
-You can optionally specify a reference to a secret or an environment variable
-which contain credentials for accessing the container registry. If credentials
-are configured for a registry, they will be used as a default when accessing
-the registry and no dedicated credential is specified for the image that is
-being processed.
+Also note, as stated previously, Docker Hub (i.e. `docker.io`) is the default
+used by Image Updater without any additional configuration.
+
+### <a name="default-namespace"></a>Configuring a registry's default namespace
+
+Some registries provide a default namespace, that is, a namespace that doesn't
+have to be specified in the image's slug. A good example for that is the
+implicit `library` namespace on Docker Hub, that allows you to pull an image
+from that library by just specifying the name of the image. Consider e.g. the
+command `docker pull nginx`, which will pull from `docker.io/library/nginx`.
+
+If your registry supports a default namespace and you would like this to be
+used with Image Updater, you can configure this by setting the `defaultns`
+property of the registry to the name of the namespace to use as the default.
+
+The canonical example for Docker Hub would be:
+
+```yaml
+registries:
+- name: Docker Hub
+  api_url: https://registry-1.docker.io
+  prefix: docker.io
+  defaultns: library
+```
+
+### <a name="rate-limit"></a>Configuring a request rate limit for your registry
+
+Some registries might be picky about how many requests per time they let you
+perform from a client's connection. In order to play nicely, and to prevent
+Image Updater from triggering rate limit failures on your registry, you can
+set a rate limit for each of the registries you are using.
+
+The rate limit can currently be configured as _requests per second_ allowed
+and is specified via the `limit` configuration property. It takes an integer
+as argument.
+
+For example, the following connection would cap requests to `quay.io` to 10
+per second:
+
+```yaml
+registries:
+- name: RedHat Quay
+  api_url: https://quay.io
+  prefix: quay.io
+  limit: 10
+```
 
-Credentials can be referenced as follows:
+Please note that the limit considers all HTTP requests sent to the registry.
+For inspecting a single tag of any given image, Image Updater may require
+performing multiple requests to the registry.
 
-* A typical pull secret, i.e. a secret containing a `.dockerconfigjson` field
-  which holds a Docker client configuration with auth information in JSON
-  format. This kind of secret is specified using the notation
-  `pullsecret:<namespace>/<secret_name>`
+The default for all registries is 20 requests per second. If your registry
+doesn't impose limits upon you, raising this limit may significantly speed
+up Argo CD Image Updater. But please be considerate and careful before you
+increase the limit.
 
-* A custom secret, which has the credentials stored in a configurable field in
-  the format `<username>:<password>`. This kind of secret is specified using
-  the notation `secret:<namespace>/<secret_name>#<field_in_secret>`
+### <a name="registry-credentials"></a>Configuring default credentials for container registries
 
-* An environment variable which holds the credentials in the format
-  `<username>:<password>`. This kind of secret is specified using the notation
-  `env:<env_var_name>`.
+If you require authentication for accessing your registry, you can configure
+a set of default credentials to use. If you have configured the credentials
+on the registry level, it will be reused for any image processed from that
+registry, unless an image configuration overrides it. A benefit of having
+the credentials configured at the registry level is
 
-* A script that outputs credentials on a single line to stdout, in the format
-  `<username:password>`. This can be used to support external authentication
-  mechanisms. You can specify this kind of secret in the notation
-  `ext:/path/to/script`. Please note that the script must be referenced as
-  absolute path, and must be executable (i.e. have the `+x` bit set). You
-  can add scripts to `argocd-image-updater` by using an init container.
+Registry credentials are configured using the `credentials` property of a
+registry's configuration.
 
-## Credentials caching
+### <a name="credentials-caching"></a>Credentials caching
 
 By default, credentials specified in registry configuration are read once on
 startup and then cached until `argocd-image-updater` is restarted. There are
 two strategies to overcome this:
 
-* Use per-image credentials in annotations - credentials will be read every
-  time an image update cycle is performed, and your credentials will always
-  be up-to-date (i.e. if you update a secret).
+* Use per-image credentials in annotations - credentials will be read from
+  their source every time an image update cycle is performed, and your
+  credentials will always be up-to-date (i.e. if you update a secret).
 
 * Specify credential expiry time in the registry configuration - if set, the
   registry credentials will have a defined lifetime, and will be re-read from
diff --git a/docs/examples/index.md b/docs/examples/index.md
new file mode 100644
index 0000000..2eddaf9
--- /dev/null
+++ b/docs/examples/index.md
@@ -0,0 +1,7 @@
+# Examples
+
+This chapter contains community contributed examples on how to configure Argo
+CD Image Updater for a certain registry or environment.
+
+Feel free to submit your own examples or guides to the documentation, as we do
+not have access to all the registries and cloud platforms out there.
diff --git a/docs/index.md b/docs/index.md
index e48da53..511c77f 100644
--- a/docs/index.md
+++ b/docs/index.md
@@ -7,9 +7,9 @@ that are managed by
 !!!warning "A note on the current status"
     Argo CD Image Updater is under active development.
 
-    You are welcome to test it out on non-critical environments, and to 
-    contribute by sending bug reports, enhancement requests and - most
-    appreciated - pull requests.
+    You are welcome to test it out on non-critical environments, and of
+    course to 
+    [contribute](./contributing/start.md) by many means.
 
     There will be (probably a lot of) breaking changes from release to
     release as development progresses until version 1.0. We will do our
@@ -44,23 +44,26 @@ RBAC authorization on Application resources etc. are fully supported.
 
 * Updates images of apps that are managed by Argo CD and are either generated
   from *Helm* or *Kustomize* tooling
-* Update app images according to different update strategies
+* Update app images according to different
+  [update strategies](./basics/update-strategies.md)
     * `semver`: update to highest allowed version according to given image
     constraint,
     * `latest`: update to the most recently created image tag,
     * `name`: update to the last tag in an alphabetically sorted list
     * `digest`: update to the most recent pushed version of a mutable tag
-* Default support for public images on widely used container registries:
-    * Docker Hub (docker.io)
-    * Google Container Registry (gcr.io)
-    * Red Hat Quay (quay.io)
-    * GitHub Container Registry (docker.pkg.github.com)
-* Support for private container registries via configuration
+* Support for 
+  [widely used container registries](./configuration/registries.md#supported-registries)
+* Support for private container registries via 
+  [configuration](./configuration/registries.md#custom-registries)
+* Can write changes
+  [back to Git](./basics/update-methods.md#method-git)
 * Ability to filter list of tags returned by a registry using matcher functions
-* Support for custom, per-image pull secrets (using generic K8s secrets, K8s
-  pull secrets or environment variables)
-* Runs in a Kubernetes cluster or can be used stand-alone from the command
-  line
+* Support for custom, per-image 
+  [pull secrets](./basics/authentication.md#auth-registries) (using generic K8s
+  secrets, K8s pull secrets, environment variables or external scripts)
+* Runs in a 
+  [Kubernetes cluster](./install/installation.md#install-kubernetes) or can be
+  used stand-alone from the command line
 * Ability to perform parallel update of applications
 
 ## Limitations
diff --git a/docs/install/start.md b/docs/install/installation.md
index bf425b4..b7b4241 100644
--- a/docs/install/start.md
+++ b/docs/install/installation.md
@@ -1,77 +1,16 @@
 # Getting Started
 
-## Runtime environment
+## Installation methods
 
-It is recommended to run Argo CD Image Updater in the same Kubernetes namespace cluster that
-Argo CD is running in, however, this is not a requirement. In fact, it is not
-even a requirement to run Argo CD Image Updater within a Kubernetes cluster or
-with access to any Kubernetes cluster at all. 
+It is recommended to run Argo CD Image Updater in the same Kubernetes namespace
+cluster that Argo CD is running in, however, this is not a requirement. In fact,
+it is not even a requirement to run Argo CD Image Updater within a Kubernetes
+cluster or with access to any Kubernetes cluster at all.
 
-However, some features might not work without accessing Kubernetes.
+However, some features might not work without accessing Kubernetes, and it is
+strongly advised to use the first installation method.
 
-## Testing beforehand
-
-With v0.8.0, a new method to test your desired configuration before configuring
-your applications was introduced with the `argocd-image-updater test` command.
-
-You can use this command from your workstation without any modifications to your
-Argo CD installation or applications, and without having to install the image
-updater in your Kubernetes cluster. The `test` command does not need to talk to
-Argo CD, and only needs access to your Kubernetes cluster if you need to use
-image pull secret stored in Kubernetes.
-
-The new `test` command's main purpose is to verify the behaviour of Argo CD
-Image Updater on arbitrary images. For example, the most simple form of running
-a test is the following:
-
-```shell
-argocd-image-updater test <image_name>
-```
-
-For example, to see what Argo CD Image Updater would consider the latest nginx
-version according to semantic versioning, you can run:
-
-```shell
-$ argocd-image-updater test nginx 
-INFO[0000] getting image                                 image_name=nginx registry=
-INFO[0002] Fetching available tags and metadata from registry  image_name=nginx
-INFO[0004] Found 321 tags in registry                    image_name=nginx
-INFO[0004] latest image according to constraint is nginx:1.19.5
-```
-
-To see what it would consider the latest patch version within the 1.17 release,
-run:
-
-```shell
-$ argocd-image-updater test nginx --semver-constraint 1.17.X
-INFO[0000] getting image                                 image_name=nginx registry=
-INFO[0002] Fetching available tags and metadata from registry  image_name=nginx
-INFO[0004] Found 321 tags in registry                    image_name=nginx
-INFO[0004] latest image according to constraint is nginx:1.17.10
-```
-
-You can also specify parameters that you would set for any given application,
-i.e. to use [update strategy](../../configuration/images/#update-strategies)
-`latest` and the registry requires [authentication](../../configuration/images/#specifying-pull-secrets),
-you can use additional command line options:
-
-```shell
-$ export GITHUB_PULLSECRET="<username>:<token>"
-$ argocd-image-updater test docker.pkg.github.com/argoproj/argo-cd/argocd --update-strategy latest --credentials env:GITHUB_PULLSECRET
-INFO[0000] getting image                                 image_name=argoproj/argo-cd/argocd registry=docker.pkg.github.com
-INFO[0000] Fetching available tags and metadata from registry  image_name=argoproj/argo-cd/argocd
-INFO[0040] Found 100 tags in registry                    image_name=argoproj/argo-cd/argocd
-INFO[0040] latest image according to constraint is docker.pkg.github.com/argoproj/argo-cd/argocd:1.8.0-9fb51f7a
-```
-
-For a complete list of available command line parameters, run
-`argocd-image-updater test --help`. 
-
-It is recommended that you read about core updating and image concepts in the
-[documentation](../../configuration/images/)
-before using this command.
-
-## Installing as Kubernetes workload in Argo CD namespace
+## <a name="install-kubernetes"></a>Method 1: Installing as Kubernetes workload in Argo CD namespace
 
 The most straightforward way to run the image updater is to install it as a Kubernetes workload into the namespace where
 Argo CD is running. Don't worry, without any configuration, it will not start messing with your workloads yet.
@@ -110,16 +49,31 @@ data:
 
 If you omit the `log.level` setting, the default `info` level will be used.
 
-## Connect using Argo CD API Server
+## Method 2: Connect using Argo CD API Server
+
+If you are unable to install Argo CD Image Updater into the same Kubernetes
+cluster you can configure it to use the API of your Argo CD installation.
 
-If you unable to install Argo CD Image Updater into the same Kubernetes cluster you might
-configure it to use API of your Argo CD installation. 
 If you chose to install the Argo CD Image Updater outside of the cluster where
 Argo CD is running in, the API must be exposed externally (i.e. using Ingress).
 If you have network policies in place, make sure that Argo CD Image Updater will
 be allowed to communicate with the Argo CD API, which is usually the service
 `argocd-server` in namespace `argocd` on port 443 and port 80.
 
+### Apply the manifests
+
+First, create a namespace and apply the manifests to your cluster
+
+```shell
+kubectl create namespace argocd-image-updater
+kubectl apply -n argocd-image-updater -f https://raw.githubusercontent.com/argoproj-labs/argocd-image-updater/stable/manifests/install.yaml
+```
+
+!!!note "A word on high availability"
+    It is not advised to run multiple replicas of the same Argo CD Image Updater
+    instance. Just leave the number of replicas at 1, otherwise weird side
+    effects could occur.
+
 ### Create a local user within Argo CD
 
 Argo CD Image Updater needs credential for accessing the Argo CD API. Using a
diff --git a/docs/install/running.md b/docs/install/reference.md
index e5556c1..bfd0b42 100644
--- a/docs/install/running.md
+++ b/docs/install/reference.md
@@ -1,4 +1,4 @@
-# Running Argo CD Image Updater
+# Configuration and command line reference
 
 The `argocd-image-updater` provides some command line parameters to control the
 behaviour of its operations. The following is a list of available parameters
diff --git a/docs/install/testing.md b/docs/install/testing.md
new file mode 100644
index 0000000..fb2df4b
--- /dev/null
+++ b/docs/install/testing.md
@@ -0,0 +1,132 @@
+# Testing outside the cluster
+
+The `argocd-image-updater` binary provides means to test its behavior using the
+`test` subcommand.
+
+You can use this command from your workstation without any modifications to your
+Argo CD installation or applications, and without having to install the image
+updater in your Kubernetes cluster. The `test` command does not need to talk to
+Argo CD, and only needs access to your Kubernetes cluster if you need to use
+image pull secret stored in Kubernetes.
+
+The `test` command's main purpose is to verify the behaviour of Argo CD
+Image Updater on arbitrary images and to validate your configuration. For
+example, the most simple form of running a test is the following:
+
+```shell
+argocd-image-updater test <image_name>
+```
+
+## Testing registry access
+
+For example, to see what Argo CD Image Updater would consider the latest nginx
+version on Docker Hub according to semantic versioning, you can run:
+
+```shell
+$ argocd-image-updater test nginx 
+INFO[0000] getting image                                 image_name=nginx registry=
+INFO[0002] Fetching available tags and metadata from registry  image_name=nginx
+INFO[0004] Found 321 tags in registry                    image_name=nginx
+INFO[0004] latest image according to constraint is nginx:1.19.5
+```
+
+## Multi-arch images
+
+As stated in the section about
+[multi-arch support](../basics/update.md#multi-arch),
+Argo CD Image Updater by default only considers images in the registry for the
+same platform as `argocd-image-updater` is executed on.
+
+For the `test` command, this means it takes the platform of the system you are
+running it on. If you are executing it for example on your Mac workstation, most
+likely no results will yield at all - because there are simple no native images
+for any of the `darwin` platforms.
+
+You can specify the target platforms manually, using the `--platforms` command
+line option, e.g. the following demonstrates no available images for the given
+platform:
+
+```shell
+$ argocd-image-updater test gcr.io/heptio-images/ks-guestbook-demo --platform darwin/amd64 --update-strategy latest
+DEBU[0000] Creating in-cluster Kubernetes client        
+INFO[0000] retrieving information about image            image_alias= image_name=gcr.io/heptio-images/ks-guestbook-demo registry_url=gcr.io
+DEBU[0000] setting rate limit to 20 requests per second  prefix=gcr.io registry="https://gcr.io"
+DEBU[0000] Inferred registry from prefix gcr.io to use API https://gcr.io 
+INFO[0000] Fetching available tags and metadata from registry  application=test image_alias= image_name=gcr.io/heptio-images/ks-guestbook-demo registry_url=gcr.io
+DEBU[0001] ignoring v2 manifest sha256:fe18e00a6aeece16b5b2f77a32ee60929e8a60e27c71df8df66bf804f5677f47. Manifest platform: linux/amd64, requested: darwin/amd64  application=test image_alias= image_name=gcr.io/heptio-images/ks-guestbook-demo registry_url=gcr.io
+DEBU[0001] No metadata found for heptio-images/ks-guestbook-demo:0.1  application=test image_alias= image_name=gcr.io/heptio-images/ks-guestbook-demo registry_url=gcr.io
+DEBU[0001] ignoring v2 manifest sha256:e6fbd640820c32c847a53b93eb7b404f25ffb56df1cc16d0711eec3a405d6509. Manifest platform: linux/amd64, requested: darwin/amd64  application=test image_alias= image_name=gcr.io/heptio-images/ks-guestbook-demo registry_url=gcr.io
+DEBU[0001] No metadata found for heptio-images/ks-guestbook-demo:0.2  application=test image_alias= image_name=gcr.io/heptio-images/ks-guestbook-demo registry_url=gcr.io
+INFO[0001] Found 0 tags in registry                      application=test image_alias= image_name=gcr.io/heptio-images/ks-guestbook-demo registry_url=gcr.io
+INFO[0001] no newer version of image found               application=test image_alias= image_name=gcr.io/heptio-images/ks-guestbook-demo registry_url=gcr.io
+```
+
+While setting the `platforms` to include `linux/amd64`, yields the following:
+
+```shell
+$ argocd-image-updater test gcr.io/heptio-images/ks-guestbook-demo --platform linux/amd64 --update-strategy latest
+DEBU[0000] Creating in-cluster Kubernetes client        
+INFO[0000] retrieving information about image            image_alias= image_name=gcr.io/heptio-images/ks-guestbook-demo registry_url=gcr.io
+DEBU[0000] setting rate limit to 20 requests per second  prefix=gcr.io registry="https://gcr.io"
+DEBU[0000] Inferred registry from prefix gcr.io to use API https://gcr.io 
+INFO[0000] Fetching available tags and metadata from registry  application=test image_alias= image_name=gcr.io/heptio-images/ks-guestbook-demo registry_url=gcr.io
+INFO[0001] Found 2 tags in registry                      application=test image_alias= image_name=gcr.io/heptio-images/ks-guestbook-demo registry_url=gcr.io
+DEBU[0001] found 2 from 2 tags eligible for consideration  image=gcr.io/heptio-images/ks-guestbook-demo
+INFO[0001] latest image according to constraint is gcr.io/heptio-images/ks-guestbook-demo:0.2  application=test image_alias= image_name=gcr.io/heptio-images/ks-guestbook-demo registry_url=gcr.io
+
+```
+
+## Testing for semver constraints
+
+To see what it would consider the latest patch version within the 1.17 release,
+run:
+
+```shell
+$ argocd-image-updater test nginx --semver-constraint 1.17.X
+INFO[0000] getting image                                 image_name=nginx registry=
+INFO[0002] Fetching available tags and metadata from registry  image_name=nginx
+INFO[0004] Found 321 tags in registry                    image_name=nginx
+INFO[0004] latest image according to constraint is nginx:1.17.10
+```
+
+## Testing different update strategies
+
+You can test the result of different
+[update strategies](../basics/update-strategies.md)
+using the `--update-strategy` command line option, e.g.:
+
+```shell
+$ argocd-image-updater test ghcr.io/argoproj/argocd --update-strategy latest
+DEBU[0000] Creating in-cluster Kubernetes client        
+INFO[0000] retrieving information about image            image_alias= image_name=ghcr.io/argoproj/argocd registry_url=ghcr.io
+DEBU[0000] setting rate limit to 20 requests per second  prefix=ghcr.io registry="https://ghcr.io"
+DEBU[0000] Inferred registry from prefix ghcr.io to use API https://ghcr.io 
+INFO[0000] Fetching available tags and metadata from registry  application=test image_alias= image_name=ghcr.io/argoproj/argocd registry_url=ghcr.io
+INFO[0139] Found 864 tags in registry                    application=test image_alias= image_name=ghcr.io/argoproj/argocd registry_url=ghcr.io
+DEBU[0139] found 864 from 864 tags eligible for consideration  image=ghcr.io/argoproj/argocd
+INFO[0139] latest image according to constraint is ghcr.io/argoproj/argocd:2.4.0-f8390c94  application=test image_alias= image_name=ghcr.io/argoproj/argocd registry_url=ghcr.io
+```
+
+## Using credentials
+
+If you need to specify 
+[credentials](../basics/authentication.md#auth-registries),
+you can do so using the `--credentials` parameter. It accepts the same values
+as the corresponding
+[annotation](../configuration/images.md#pull-secrets), i.e.:
+
+```shell
+$ export GITHUB_PULLSECRET="<username>:<token>"
+$ argocd-image-updater test docker.pkg.github.com/argoproj/argo-cd/argocd --update-strategy latest --credentials env:GITHUB_PULLSECRET
+INFO[0000] getting image                                 image_name=argoproj/argo-cd/argocd registry=docker.pkg.github.com
+INFO[0000] Fetching available tags and metadata from registry  image_name=argoproj/argo-cd/argocd
+INFO[0040] Found 100 tags in registry                    image_name=argoproj/argo-cd/argocd
+INFO[0040] latest image according to constraint is docker.pkg.github.com/argoproj/argo-cd/argocd:1.8.0-9fb51f7a
+```
+
+For a complete list of available command line parameters, run
+`argocd-image-updater test --help`.
+
+It is recommended that you read about core updating and image concepts in the
+[documentation](../../configuration/images/)
+before using this command.
diff --git a/mkdocs.yml b/mkdocs.yml
index 6a3a8af..00eb9c6 100644
--- a/mkdocs.yml
+++ b/mkdocs.yml
@@ -19,14 +19,20 @@ extra_javascript:
 markdown_extensions:
 - codehilite
 - admonition
+- tables
 - toc:
     permalink: true
 nav:
   - Overview: index.md
-  - Install:
-    - Getting Started: install/start.md
-    - Running Argo CD Image Updater: install/running.md
-  - Update strategies: install/strategies.md
+  - Getting started:
+    - Installation: install/installation.md
+    - Testing: install/testing.md
+    - Command Line and Configuration reference: install/reference.md
+  - Basics:
+    - Updating images: basics/update.md
+    - Update methods: basics/update-methods.md
+    - Update strategies: basics/update-strategies.md
+    - Authentication: basics/authentication.md
   - Configuration: 
     - Applications: configuration/applications.md
     - Images: configuration/images.md
@@ -34,5 +40,6 @@ nav:
   - Contributing:
     - Overview: contributing/start.md
     - Developing: contributing/development.md
+  - Examples: examples/index.md
   - Releases ⧉: https://github.com/argoproj-labs/argocd-image-updater/releases
   - Roadmap ⧉: https://github.com/argoproj-labs/argocd-image-updater/milestones
diff --git a/pkg/registry/endpoints.go b/pkg/registry/endpoints.go
index 4230b3d..a04ff3b 100644
--- a/pkg/registry/endpoints.go
+++ b/pkg/registry/endpoints.go
@@ -204,7 +204,7 @@ func GetRegistryEndpoint(prefix string) (*RegistryEndpoint, error) {
 			err = fmt.Errorf("could not infer registry configuration from prefix %s", prefix)
 		}
 		if err == nil {
-			log.Debugf("Infered registry from prefix %s to use API %s", prefix, ep.RegistryAPI)
+			log.Debugf("Inferred registry from prefix %s to use API %s", prefix, ep.RegistryAPI)
 		}
 		return ep, err
 	}