summaryrefslogtreecommitdiff
path: root/doc
diff options
context:
space:
mode:
authorRaoul Hidalgo Charman <raoul.hidalgocharman@codethink.co.uk>2019-05-30 17:23:41 +0100
committerRaoul Hidalgo Charman <raoul.hidalgocharman@codethink.co.uk>2019-05-31 10:08:54 +0100
commitd88c4aa38a2cb119c36c0648baa722b35369f786 (patch)
tree9ce80f21f5fef0c44e4eefefad7932c99b609bf1 /doc
parentfe721b65df09497c0f07f5fe414ad5cb2db49095 (diff)
downloadbuildstream-d88c4aa38a2cb119c36c0648baa722b35369f786.tar.gz
docs: Update configuring cache serverraoul/1024-artifact-docs
Now that we have both artifact and source caches the documentation is updated to reflect that. Some sections headings/links etc. have been expanded and changed. Part of #1025
Diffstat (limited to 'doc')
-rw-r--r--doc/source/format_project.rst4
-rw-r--r--doc/source/main_using.rst2
-rw-r--r--doc/source/using_config.rst6
-rw-r--r--doc/source/using_configuring_cache_server.rst (renamed from doc/source/using_configuring_artifact_server.rst)61
4 files changed, 40 insertions, 33 deletions
diff --git a/doc/source/format_project.rst b/doc/source/format_project.rst
index 214b6c616..ac6786c79 100644
--- a/doc/source/format_project.rst
+++ b/doc/source/format_project.rst
@@ -189,7 +189,7 @@ for more detail.
Artifact server
~~~~~~~~~~~~~~~
-If you have setup an :ref:`artifact server <artifacts>` for your
+If you have setup an :ref:`artifact server <cache_servers>` for your
project then it is convenient to configure the following in your ``project.conf``
so that users need not have any additional configuration to communicate
with an artifact share.
@@ -274,7 +274,7 @@ using the `remote-execution` option:
instance-name: development-emea-1
storage-service specifies a remote CAS store and the parameters are the
-same as those used to specify an :ref:`artifact server <artifacts>`.
+same as those used to specify an :ref:`artifact server <cache_servers>`.
The action-cache-service specifies where built actions are cached, allowing
buildstream to check whether an action has already been executed and download it
diff --git a/doc/source/main_using.rst b/doc/source/main_using.rst
index d56023e74..48553087c 100644
--- a/doc/source/main_using.rst
+++ b/doc/source/main_using.rst
@@ -17,4 +17,4 @@ guides and information on user preferences and configuration.
using_examples
using_config
using_commands
- using_configuring_artifact_server
+ using_configuring_cache_server
diff --git a/doc/source/using_config.rst b/doc/source/using_config.rst
index 2b74b2de5..2582e711f 100644
--- a/doc/source/using_config.rst
+++ b/doc/source/using_config.rst
@@ -32,8 +32,8 @@ the supported configurations on a project wide basis are listed here.
Artifact server
~~~~~~~~~~~~~~~
-Although project's often specify a :ref:`remote artifact cache <artifacts>` in
-their ``project.conf``, you may also want to specify extra caches.
+Although project's often specify a :ref:`remote artifact cache <cache_servers>`
+in their ``project.conf``, you may also want to specify extra caches.
Assuming that your host/server is reachable on the internet as ``artifacts.com``
(for example), there are two ways to declare remote caches in your user
@@ -100,6 +100,8 @@ pull only access and push/pull access. For information regarding this and the
server/client certificates and keys, please see:
:ref:`Key pair for the server <server_authentication>`.
+.. _config_sources:
+
Source cache server
~~~~~~~~~~~~~~~~~~~
Similarly global and project specific source caches servers can be specified in
diff --git a/doc/source/using_configuring_artifact_server.rst b/doc/source/using_configuring_cache_server.rst
index 6eb64113c..856046f35 100644
--- a/doc/source/using_configuring_artifact_server.rst
+++ b/doc/source/using_configuring_cache_server.rst
@@ -1,32 +1,34 @@
-.. _artifacts:
+.. _cache_servers:
-Configuring Artifact Server
-===========================
+Configuring Cache Servers
+=========================
BuildStream caches the results of builds in a local artifact cache, and will
avoid building an element if there is a suitable build already present in the
-local artifact cache.
+local artifact cache. Similarly it will cache sources and avoid pulling them if
+present in the local cache. See :ref:`caches <caches>` for more details.
-In addition to the local artifact cache, you can configure one or more remote
-artifact caches and BuildStream will then try to pull a suitable build from one
-of the remotes, falling back to a local build if needed.
+In addition to the local caches, you can configure one or more remote caches and
+BuildStream will then try to pull a suitable object from one of the remotes,
+falling back to performing a local build or fetching a source if needed.
Configuring BuildStream to use remote caches
--------------------------------------------
A project will often set up continuous build infrastructure that pushes
-built artifacts to a shared cache, so developers working on the project can
-make use of these pre-built artifacts instead of having to each build the whole
+cached objects to a shared cache, so developers working on the project can
+make use of these pre-made objects instead of having to each build the whole
project locally. The project can declare this cache in its
-:ref:`project configuration file <project_essentials_artifacts>`.
+project configuration file for :ref:`artifacts <project_essentials_artifacts>`
+and :ref:`sources <project_source_cache>`.
Users can declare additional remote caches in the :ref:`user configuration
<config_artifacts>`. There are several use cases for this: your project may not
define its own cache, it may be useful to have a local mirror of its cache, or
you may have a reason to share artifacts privately.
-Remote artifact caches are identified by their URL. There are currently two
-supported protocols:
+Remote caches are identified by their URL. There are currently two supported
+protocols:
* ``http``: Pull and push access, without transport-layer security
* ``https``: Pull and push access, with transport-layer security
@@ -38,23 +40,24 @@ them in a specific order:
2. Project configuration
3. User configuration
-When an artifact is built locally, BuildStream will try to push it to all the
+When an an object is created 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 artifact push command <invoking_artifact_push>`.
+artifacts to a specific cache using the :ref:`bst artifact push command
+<invoking_artifact_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
+Objects are identified using the element or sources :ref:`cache key <cachekeys>`
+so the objects provided by a cache should be interchangable with those provided
by any other cache.
-Setting up a remote artifact cache
-----------------------------------
-The rest of this page outlines how to set up a shared artifact cache.
+Setting up a remote cache
+-------------------------
+The rest of this page outlines how to set up a shared cache.
Setting up the user
~~~~~~~~~~~~~~~~~~~
-A specific user is not needed, however, a dedicated user to own the
-artifact cache is recommended.
+A specific user is not needed, however, a dedicated user to own the cache is
+recommended.
.. code:: bash
@@ -70,11 +73,11 @@ and authorization there.
Installing the server
~~~~~~~~~~~~~~~~~~~~~
-You will also need to install BuildStream on the artifact server in order
+You will also need to install BuildStream on the cache server in order
to receive uploaded artifacts over ssh. Follow the instructions for installing
BuildStream `here <https://buildstream.build/install.html>`_.
-When installing BuildStream on the artifact server, it must be installed
+When installing BuildStream on the cache server, it must be installed
in a system wide location, with ``pip3 install .`` in the BuildStream
checkout directory.
@@ -241,12 +244,14 @@ We can then check if the services are successfully running with:
For more information on systemd services see:
`Creating Systemd Service Files <https://www.devdungeon.com/content/creating-systemd-service-files>`_.
-Declaring remote artifact caches
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-Remote artifact caches can be declared within either:
+Declaring remote caches
+~~~~~~~~~~~~~~~~~~~~~~~
+Remote caches can be declared within either:
-1. The :ref:`project configuration <project_essentials_artifacts>`, or
-2. The :ref:`user configuration <config_artifacts>`.
+1. The project configuration for :ref:`artifact <project_essentials_artifacts>`
+ and :ref:`sources <project_source_cache>`, or
+2. The user configuration for :ref:`artifacts <config_artifacts>` and
+ :ref:`sources <config_sources>`.
Please follow the above links to see examples showing how we declare remote
caches in both the project configuration and the user configuration, respectively.