Merge branch 'jennis/patch_remote_cache_docs' into 'master'

Improve our documentation for configuring an artifact server

See merge request BuildStream/buildstream!899

1 files changed, 15 insertions, 1 deletions

diff --git a/doc/source/using_configuring_artifact_server.rst b/doc/source/using_configuring_artifact_server.rst
index b25b5aecf..813952cb3 100644
--- a/doc/source/using_configuring_artifact_server.rst
+++ b/doc/source/using_configuring_artifact_server.rst
@@ -40,7 +40,7 @@ them in a specific order:
 
 When an artifact is built locally, BuildStream will try to push it to all the
 caches which have the ``push: true`` flag set. You can also manually push
-artifacts to a specific cache using the :ref:`bst pull command <commands>`.
+artifacts to a specific cache using the :ref:`bst push command <invoking_push>`.
 
 Artifacts are identified using the element's :ref:`cache key <cachekeys>` so
 the builds provided by a cache should be interchangable with those provided
@@ -110,6 +110,15 @@ You can also use a key pair obtained from a trusted certificate authority instea
 
     openssl req -new -newkey rsa:4096 -x509 -sha256 -days 3650 -nodes -batch -subj "/CN=artifacts.com" -out server.crt -keyout server.key
 
+.. note::
+
+    Note that in the ``-subj "/CN=<foo>"`` argument, ``/CN`` is the *certificate common name*,
+    and as such ``<foo>`` should be the public hostname of the server. IP addresses will
+    **not** provide you with working authentication.
+
+    In addition to this, ensure that the host server is recognised by the client.
+    You may need to add the line: ``<ip address>`` ``<hostname>`` to
+    your ``/etc/hosts`` file.
 
 Authenticating users
 ~~~~~~~~~~~~~~~~~~~~
@@ -233,3 +242,8 @@ Pull and push:
      client-cert: client.crt
 
      push: true
+
+.. note::
+
+    Equivalent statements can be delcared in a project's configuration file
+    (the ``project.conf``).