diff options
author | Chandan Singh <csingh43@bloomberg.net> | 2018-10-05 21:54:45 -0400 |
---|---|---|
committer | Chandan Singh <csingh43@bloomberg.net> | 2018-10-05 22:20:19 -0400 |
commit | b417dfba05b66cbee6445d3e7f61a90052f006d1 (patch) | |
tree | b42eb0ea56bf4ab25eef9c8ab585240a7957f8fa | |
parent | d3921ab8bd515fb3dc890c831b7fb33d34d6de05 (diff) | |
download | buildstream-b417dfba05b66cbee6445d3e7f61a90052f006d1.tar.gz |
doc: Add new document about Docker integrations
Add a new section under "Additional writings" section about how
BuildStream integrates with Docker. At present, this section includes
only two sections:
- "Run BuildStream inside Docker", that refers to existing instructions
for doing so
- "Generate Docker images", that adds instructions for using the newly
added `contrib/bst-docker-import` script
In future, this document can be extended to include the following
things:
- Importing Docker sources via `docker` source plugin - if/when the
Docker source plguin is moved from bst-external to BuildStream proper
- A Docker sandbox, if/when that is added
-rw-r--r-- | doc/source/additional_docker.rst | 53 | ||||
-rw-r--r-- | doc/source/core_additional.rst | 1 |
2 files changed, 54 insertions, 0 deletions
diff --git a/doc/source/additional_docker.rst b/doc/source/additional_docker.rst new file mode 100644 index 000000000..6193cc44e --- /dev/null +++ b/doc/source/additional_docker.rst @@ -0,0 +1,53 @@ + +.. _bst_and_docker: + + +BuildStream and Docker +====================== + +BuildStream integrates with Docker in multiple ways. Here are some ways in +which these integrations work. + +Run BuildStream inside Docker +----------------------------- + +Refer to the :ref:`BuildStream inside Docker <_docker>` documentaion for +instructions on how to run BuildStream as a Docker container. + +Generate Docker images +---------------------- + +The +`bst-docker-import script <https://gitlab.com/BuildStream/buildstream/blob/master/contrib/bst-docker-import>`_ +can be used to generate a Docker image from built artifacts. + +You can download it and make it executable like this: + +.. code:: bash + + mkdir -p ~/.local/bin + curl --get https://gitlab.com/BuildStream/buildstream/raw/master/contrib/bst-docker-import > ~/.local/bin/bst-docker-import + chmod +x ~/.local/bin/bst-docker-import + +Check if ``~/.local/bin`` appears in your PATH environment variable -- if it +doesn't, you should +`edit your ~/.profile so that it does <https://stackoverflow.com/questions/14637979/>`_. + +Once the script is available in your PATH and assuming you have Docker +installed, you can start using the ``bst-docker-import`` script. Here is a +minimal example to generate an image called ``bst-hello`` from an element +called ``hello.bst`` assuming it is already built: + +.. code:: bash + + bst-docker-import -t bst-hello hello.bst + +This script can also be used if you are running BuildStream inside Docker. In +this case, you will need to supply the command that you are using to run +BuildStream using the ``-c`` option. If you are using the +`bst-here wrapper script <https://gitlab.com/BuildStream/buildstream/blob/master/contrib/bst-here>`_ +, you can achieve the same results as the above example like this: + +.. code:: bash + + bst-docker-import -c bst-here -t bst-hello hello.bst diff --git a/doc/source/core_additional.rst b/doc/source/core_additional.rst index 76e523ee8..08c445630 100644 --- a/doc/source/core_additional.rst +++ b/doc/source/core_additional.rst @@ -8,3 +8,4 @@ Additional writings additional_cachekeys additional_sandboxing + additional_docker |