From 991fcf7412befb45185690f792500707c78a2f79 Mon Sep 17 00:00:00 2001
From: vanous <petr@linuks.cz>
Date: Sun, 14 Aug 2022 16:43:06 +0200
Subject: [PATCH] Add more documentation for local backend (#1107)

---
 .../30-administration/22-backends/20-local.md | 117 +++++++++++++++++-
 1 file changed, 111 insertions(+), 6 deletions(-)

diff --git a/docs/docs/30-administration/22-backends/20-local.md b/docs/docs/30-administration/22-backends/20-local.md
index 6acb6f663..7fb2fa265 100644
--- a/docs/docs/30-administration/22-backends/20-local.md
+++ b/docs/docs/30-administration/22-backends/20-local.md
@@ -5,13 +5,118 @@ The local backend will execute the pipelines on the local system without any iso
 :::
 
 :::note
-This backend is still pretty new and can not be treated as stable. Its implementation and configuration can change at any time.
+This backend is still pretty new and can not be treated as stable. Its
+implementation and configuration can change at any time. Binary releases of the
+agent will be available with the release of the [1.0.0
+milestone](https://github.com/woodpecker-ci/woodpecker/milestone/4), so for now
+you must compile the agent by yourself, to get the local backend functionality.
+<!-- TODO: remove the self-compile note after the release of the agent -->
 :::
 
-Since the code run directly in the same context as the agent (same user, same filesystem), a malicious pipeline could 
-be used to access the agent configuration especially the `WOODPECKER_AGENT_SECRET` variable.
+Since the code runs directly in the same context as the agent (same user, same
+filesystem), a malicious pipeline could be used to access the agent
+configuration especially the `WOODPECKER_AGENT_SECRET` variable.
 
-It is recommended to use this backend only for private setup where the code and pipeline can be trusted. You shouldn't
-use it for a public facing CI where anyone can submit code or add new repositories.
+It is recommended to use this backend only for private setup where the code and
+pipeline can be trusted. You shouldn't use it for a public facing CI where
+anyone can submit code or add new repositories. You shouldn't execute the agent
+as a privileged user (root).
+
+The local backend will use a random directory in $TMPDIR to store the cloned
+code and execute commands.
+
+In order to use this backend, you need to download (or build) the
+[binary](https://github.com/woodpecker-ci/woodpecker/releases/latest) of the
+agent, configure it and run it on the host machine.
+
+## Configuration
+
+### Server
+
+Enable connection to the server from the outside of the docker environment by
+exposing the port 9000:
+
+```yaml
+# docker-compose.yml for the server
+version: '3'
+
+services:
+  woodpecker-server:
+  [...]
+    ports:
+      - 9000:9000
+      [...]
+    environment:
+      - [...]
+```
+
+### Agent
+
+You can use the `.env` file to store environmental variables for configuration.
+At the minimum you need the following information:
+
+```ini
+# .env for the agent
+WOODPECKER_AGENT_SECRET=replace_with_your_server_secret
+WOODPECKER_HOST=replace_with_your_server_address:9000
+```
+
+## Running the agent
+
+Start the agent from the directory with the `.env` file: 
+
+`woodpecker-agent`
+
+:::note
+When using the `local` backend, the
+[plugin-git](https://github.com/woodpecker-ci/plugin-git) binary must be in
+your `$PATH` for the default clone step to work. If not, you can still write a
+manual clone step.
+:::
+
+## Further configuration
+
+### Specify the shell to be used for a pipeline step
+
+The `image` entry is used to specify the shell, such as Bash or Fish, that is
+used to run the commands.
+
+
+```yaml
+# .woodpecker.yml
+
+pipeline:
+  build:
+    image: bash
+    commands:
+      [...]
+```
+
+### Using labels to filter tasks
+
+You can use the [agent configuration
+options](/docs/administration/agent-config#woodpecker_filter_labels) and the
+[pipeline syntax](/docs/usage/pipeline-syntax#labels) to only run certain
+pipelines on certain agents. Example:
+
+Define a `label` `type` with value `exec` for a particular agent:
+
+```ini
+# .env for the agent
+
+WOODPECKER_FILTER_LABELS=type=exec
+```
+
+Then, use this `label` `type` with value `exec` in the pipeline definition, to
+only run on this agent:
+
+```yaml
+# .woodpecker.yml
+
+labels:
+  type: exec
+
+pipeline:
+  [...]
+```
 
-The backend will use a random directory in $TMPDIR to store the clone code and execute commands.