docs(templates): update template docs

docs/source/agent.rst

@@ -13,8 +13,8 @@ Containers, networks, volumes and images are node specific resources, not cluste
 
 The purpose of the agent aims to allows previously node specific resources to be cluster-aware, all while keeping the Docker API request format. As aforementioned, this means that you only need to execute one Docker API request to retrieve all these resources from every node inside the cluster. In all bringing a better Docker user experience when managing Swarm clusters.
 
-Deployment
-==========
+Agent deployment
+================
 
 Here follow the instructions to deploy the Agent, and to connect it to Portainer.
 
@@ -127,8 +127,8 @@ Alternatively, you can deploy the agent using the following stack:
       driver: overlay
       attachable: true
 
-Configuration
--------------
+Agent configuration
+-------------------
 
 You can change the configuration of the agent by using environment variables.
 

docs/source/configuration.rst

@@ -106,9 +106,36 @@ Use your own templates
 
 Portainer allows you to rapidly deploy containers using App Templates.
 
-By default `Portainer templates <https://raw.githubusercontent.com/portainer/templates/master/templates.json>`_ will be used but you can also define your own templates.
+By default `Portainer templates <https://raw.githubusercontent.com/portainer/portainer/master/templates.json>`_ will be used but you can also define your own templates.
 
-Add the ``--templates`` flag and specify the external location of your templates when starting Portainer:
+Note: at the moment, templates are only loaded once at first Portainer startup. If you already deployed a Portainer instance and want to use your own templates after this,
+you'll need to clear any existing templates (default templates) via the HTTP API.
+
+There are two ways to specify your own templates:
+
+Bind-mount your own templates
+-----------------------------
+
+Using the `--template-file` flag you can specify the path to your own template file on the file-system. By default, it points to `/templates.json` on both Linux and Windows hosts.
+
+For example, you can mount your own template file inside the container:
+
+.. code-block:: bash
+
+  $ docker run -d -p 9000:9000 -v /var/run/docker.sock:/var/run/docker.sock -v /path/to/my/templates.json:/templates.json portainer/portainer
+
+
+Or using the `--template-file` to specify a specific path to the templates file:
+
+.. code-block:: bash
+
+  $ docker run -d -p 9000:9000 -v /var/run/docker.sock:/var/run/docker.sock -v /path/to/template/folder:/templates portainer/portainer --template-file /templates/templates.json
+
+
+Host your template file
+-----------------------
+
+Using the `--templates` flag you can specify an URL where the template file can be accessed via HTTP.
 
 .. code-block:: bash
 
@@ -154,4 +181,5 @@ The following CLI flags are available:
 * ``--sslkey``: Path to the SSL key used to secure the Portainer instance (default: ``/certs/portainer.key``, ``C:\certs\portainer.key`` on Windows)
 * ``--hide-label``, ``-l``: Hide containers with a specific label in the UI
 * ``--logo``: URL to a picture to be displayed as a logo in the UI, use Portainer logo if not specified
-* ``--templates``, ``-t``: URL to templates (apps) definitions (default: ``https://raw.githubusercontent.com/portainer/templates/master/templates.json``)
+* ``--templates``, ``-t``: URL to templates (apps) definitions
+* ``--template-file``: Path on disk to templates (apps) definitions (default: ``/templates.json``)

docs/source/templates.rst

@@ -580,7 +580,10 @@ This field is **optional**.
 Build and host your own templates
 =================================
 
-You can build your own container that will use `Nginx <https://hub.docker.com/_/nginx/>`_ to serve the templates definitions.
+
+The simplest way to use your own templates is to bind mount your own template file directly into the Portainer container, see :doc:`Configuration <configuration>`.
+
+You can also build your own container that will use `Nginx <https://hub.docker.com/_/nginx/>`_ to serve the templates definitions.
 
 Clone the `Portainer templates repository <https://github.com/portainer/templates>`_, edit the templates file, build and run the container: