refactor: docs for local setup

.env.example

@@ -9,23 +9,32 @@
 #                #
 ##################
 
-# These are used by the ui service
-# defined in the docker compose stack
+# These are used by the ui service defined in the docker compose stack
 
-# customize the location where you want users to provide feedback
+# customize the location for the Vela server address
 #
-# default: https://github.com/go-vela/ui/issues/new
-# VELA_FEEDBACK_URL=
+# Should match the "VELA_ADDR" value in docker-compose.yml when running locally.
+VELA_API=http://localhost:8080
 
 # customize the location where users can review documentation
 #
 # default: https://go-vela.github.io/docs
 # VELA_DOCS_URL=
 
-# customize the location for the Vela server address
+# customize the location where you want users to provide feedback
 #
-# Should match the "VELA_ADDR" value in docker-compose.yml when running locally.
-VELA_API=http://localhost:8080
+# default: https://github.com/go-vela/ui/issues/new
+# VELA_FEEDBACK_URL=
+
+# customize the number of bytes for size of logs the UI will attempt to render
+#
+# default: 20000 (2 MB)
+# VELA_LOG_BYTES_LIMIT=
+
+# customize the number of concurrent builds for a repo the UI will allow configuring
+#
+# default: 30
+# VELA_MAX_BUILD_LIMIT=
 
 ############################################################
 #  _______  _______  ______    __   __  _______  ______    #
@@ -38,16 +47,15 @@ VELA_API=http://localhost:8080
 #                                                          #
 ############################################################
 
-# These are used by the server service
-# defined in the docker compose stack
+# These are used by the server service defined in the docker compose stack
 
 # github web url (only required if using GitHub Enterprise)
 #
 # default: https://github.com
 # VELA_SCM_ADDR=
 
 # github client id from oauth application
-VELA_SCM_CLIENT=
+# VELA_SCM_CLIENT=
 
 # github client secret from oauth application
-VELA_SCM_SECRET=
+# VELA_SCM_SECRET=

DOCS.md

@@ -2,15 +2,15 @@
 
 This document intends to provide information on how to get the Vela application running locally.
 
-For more information, please see our [installation docs](https://go-vela.github.io/docs/install/).
+For more information, please see our [administration docs](https://go-vela.github.io/docs/administration/).
 
 ## Prerequisites
 
 This section covers the dependencies required to get the Vela application running locally.
 
 * [Docker](https://docs.docker.com/install/) - building block for local development
 * [Docker Compose](https://docs.docker.com/compose/install/) - start up local development
-* [Github OAuth Client](https://developer.github.com/apps/building-oauth-apps/creating-an-oauth-app/) - building block for local development
+* [GitHub OAuth Client](https://developer.github.com/apps/building-oauth-apps/creating-an-oauth-app/) - building block for local development
 * [Golang](https://golang.org/dl/) - for source code and [dependency management](https://github.com/golang/go/wiki/Modules)
 * [Make](https://www.gnu.org/software/make/) - start up local development
 
@@ -34,26 +34,26 @@ git clone [email protected]:go-vela/server.git $HOME/go-vela/server
 cd $HOME/go-vela/server
 ```
 
-* If using GitHub Enterprise (default: `https://github.com/`), add the Web URL to a local `.env` file:
+* If using GitHub Enterprise (default: `https://github.com`), add the Web URL to a local `.env` file:
 
 ```bash
 # add Github Enterprise Web URL to local `.env` file for `docker-compose`
-echo "VELA_SOURCE_ADDR=<GitHub Enterprise Web URL>" >> .env
+echo "VELA_SCM_ADDR=<GitHub Enterprise Web URL>" >> .env
 ```
 
 * Create an [OAuth App](https://developer.github.com/apps/building-oauth-apps/creating-an-oauth-app/) and obtain secrets for local development:
   * `Application name` = `Vela - local` (name of the OAuth application shouldn't matter)
-  * `Homepage URL` = `http://localhost:8080` (base URL of the server)
+  * `Homepage URL` = `http://localhost:8888` (base URL of the web UI)
   * `Authorization callback URL` = `http://localhost:8080/authenticate` (authenticate endpoint of the base URL of the server)
 
 * Add OAuth client secrets to a local `.env` file:
 
 ```bash
 # add Github Client ID to local `.env` file for `docker-compose`
-echo "VELA_SOURCE_CLIENT=<Github OAuth Client ID>" >> .env
+echo "VELA_SCM_CLIENT=<Github OAuth Client ID>" >> .env
 
 # add Github Client Secret to local `.env` file for `docker-compose`
-echo "VELA_SOURCE_SECRET=<Github OAuth Client Secret>" >> .env
+echo "VELA_SCM_SECRET=<Github OAuth Client Secret>" >> .env
 ```
 
 ## Start
@@ -93,15 +93,15 @@ In order to run a build in Vela, you'll need to add a repo to the locally runnin
 <p>
 
 1. Navigate to the `Source Repositories` page @ http://localhost:8888/account/source-repos
-  * For conveinence, you can reference our documentation to [learn how to enable a repo](https://go-vela.github.io/docs/usage/enable_repo/).
+   * For convenience, you can reference our documentation to [learn how to enable a repo](https://go-vela.github.io/docs/usage/enable_repo/).
 
-2. Click the blue drop down arrow on the left side next to the org that contains the repo you want to enable.
+2. Click the blue drop-down arrow on the left side next to the org that contains the repo you want to enable.
 
-3. Find the repo you want to enable in the drop down list and click the blue `Enable` button on the right side.
-  * You should received a `success` message telling you `<org>/<repo> enabled.`
+3. Find the repo you want to enable in the drop-down list and click the blue `Enable` button on the right side.
+   * You should receive a `success` message telling you `<org>/<repo> enabled.`
 
 4. Click the blue `View` button to navigate directly to the repo.
-  * You should be redirected to http://localhost:8888/<org>/<repo>
+   * You should be redirected to http://localhost:8888/<org>/<repo>
 
 </p>
 </details>
@@ -116,7 +116,7 @@ In order to run a build in Vela, you'll need to add a pipeline to the repo that
 <p>
 
 1. Create a Vela [pipeline](https://go-vela.github.io/docs/tour/) to define a workflow for Vela to run.
-  * For convenience, you can reference our documentation to use [one of our example pipelines](https://go-vela.github.io/docs/usage/examples/).
+   * For convenience, you can reference our documentation to use [one of our example pipelines](https://go-vela.github.io/docs/usage/examples/).
 
 2. Add the pipeline to the repo that was enabled above.
 
@@ -137,8 +137,8 @@ In order to run a build in Vela, you'll need to capture a valid webhook payload
 2. Find the [recent delivery](https://developer.github.com/webhooks/testing/#listing-recent-deliveries) for the pipeline that was added to your repo.
 
 3. Create a request locally for http://localhost:8080/webhook and replicate all parts from the recent delivery.
-  * You should use whatever tool feels most comfortable and natural to you (`curl`, `Postman`, `Insomnia` etc.).
-  * You should replicate all the request headers and the request body from the recent delivery.
+   * You should use whatever tool feels most comfortable and natural to you (`curl`, `Postman`, `Insomnia` etc.).
+   * You should replicate all the request headers and the request body from the recent delivery.
 
 4. Send the request and navigate directly to the repo (http://localhost:8888/<org>/<repo>) to watch the build run live.
 
@@ -156,19 +156,33 @@ This section covers the different services in the stack when the Vela applicatio
 
 The `server` Docker compose service hosts the Vela server and API.
 
-This component is used for processing web requests and managing resources in the database and publishing builds to the FIFO queue.
+Known as the brains of the Vela application, this service is responsible for managing the state of application resources.
+
+This includes managing resources in the system (repositories, users etc.) and storing resource data in the database.
+
+Additionally, the server responds to event-driven requests (webhooks) which creates new builds to run on a worker.
+
+For more information, please review [the official documentation](https://go-vela.github.io/docs/administration/server/).
 
 ### Worker
 
 The `worker` Docker compose service hosts the Vela build daemon.
 
-This component is used for pulling builds from the FIFO queue and executing them based off their configuration.
+Known as the brawn of the Vela application, this service is responsible for managing the state of build resources.
+
+This includes pulling the build, provided by the server, from the queue to be run.
+
+For more information, please review [the official documentation](https://go-vela.github.io/docs/administration/worker/).
 
 ### UI
 
 The `ui` Docker compose service hosts the Vela UI.
 
-This component is used for providing a user-friendly interface for triggering actions in the Vela system.
+Known as the user interface for the Vela application, often referred to as the Vela UI, this service provides a means for utilizing and interacting with the Vela platform.
+
+The Vela UI aims to provide users with an easy-to-use toolbox that supplies most of the functionality necessary for managing, investigating, and successfully troubleshooting Vela pipelines.
+
+For more information, please review [the official documentation](https://go-vela.github.io/docs/administration/ui/).
 
 ### Redis
 

docker-compose.yml

@@ -12,7 +12,7 @@ services:
   # managing resources in the database and publishing
   # builds to the FIFO queue.
   #
-  # https://go-vela.github.io/docs/concepts/infrastructure/server/
+  # https://go-vela.github.io/docs/administration/server/
   server:
     build:
       context: .
@@ -56,23 +56,26 @@ services:
   # This component is used for pulling builds from the FIFO
   # queue and executing them based off their configuration.
   #
-  # https://go-vela.github.io/docs/concepts/infrastructure/worker/
+  # https://go-vela.github.io/docs/administration/worker/
   worker:
     container_name: worker
     image: target/vela-worker:latest
     networks:
       - vela
     environment:
+      EXECUTOR_DRIVER: linux
+      EXECUTOR_LOG_METHOD: 'time-chunks'
       QUEUE_DRIVER: redis
       QUEUE_ADDR: 'redis://redis:6379'
       VELA_BUILD_LIMIT: 1
       VELA_BUILD_TIMEOUT: 30m
       VELA_LOG_LEVEL: trace
       VELA_RUNTIME_DRIVER: docker
+      VELA_RUNTIME_PRIVILEGED_IMAGES: 'target/vela-docker'
       VELA_SERVER_ADDR: 'http://server:8080'
       VELA_SERVER_SECRET: 'zB7mrKDTZqNeNTD8z47yG4DHywspAh'
       WORKER_ADDR: 'http://worker:8080'
-      WORKER_CHECK_IN: 15m
+      WORKER_CHECK_IN: 5m
     restart: always
     ports:
       - '8081:8080'
@@ -86,7 +89,7 @@ services:
   # This component is used for providing a user-friendly
   # interface for triggering actions in the Vela system.
   #
-  # https://go-vela.github.io/docs/concepts/infrastructure/ui/
+  # https://go-vela.github.io/docs/administration/ui/
   ui:
     container_name: ui
     image: target/vela-ui:latest