This is an automated email from the ASF dual-hosted git repository. zky pushed a commit to branch main in repository https://gitbox.apache.org/repos/asf/incubator-devlake-website.git
commit 4074b999321daa479a55d74664a157dc71c5f17f Author: Hezheng Yin <[email protected]> AuthorDate: Wed Oct 12 22:42:19 2022 -0700 docs: convert steps 9 and onward into separate sections --- docs/DeveloperManuals/DeveloperSetup.md | 85 ++++++++++++--------------------- 1 file changed, 31 insertions(+), 54 deletions(-) diff --git a/docs/DeveloperManuals/DeveloperSetup.md b/docs/DeveloperManuals/DeveloperSetup.md index 4b523d1e7..eb33c703c 100644 --- a/docs/DeveloperManuals/DeveloperSetup.md +++ b/docs/DeveloperManuals/DeveloperSetup.md @@ -17,7 +17,8 @@ sidebar_position: 1 ## How to setup dev environment -The following guide will walk you through the procedure to run local config-ui and devlake servers against dockerized MySQL and Grafana containers. +The following guide will walk through how to run DevLake's frontend (`config-ui`) and backend in dev mode. + 1. Navigate to where you would like to install this project and clone the repository: @@ -57,89 +58,65 @@ The following guide will walk you through the procedure to run local config-ui a 7. Run `devlake` and `config-ui` in dev mode in two separate terminals: ```sh - # install mockery - go install github.com/vektra/mockery/v2@latest - # generate mocking stubs - make mock # run devlake make dev # run config-ui make configure-dev ``` - Q: I got an error saying: `libgit2.so.1.3: cannot open share object file: No such file or directory` + For common errors, please see [Troubleshooting](#troubleshotting). - A: This library is needed by the git-extractor plugin. Make sure your program can find `libgit2.so.1.3`. `LD_LIBRARY_PATH` can be assigned like this if your `libgit2.so.1.3` is located at `/usr/local/lib`: +8. Config UI is running at `localhost:4000` + - For how to use Config UI, please refer to our [tutorial](UserManuals/ConfigUI/Tutorial.md) - ```sh - export LD_LIBRARY_PATH=$LD_LIBRARY_PATH:/usr/local/lib - ``` - - Note that the version has to be pinned to 1.3.0. If you don't have it, you may need to build it manually with CMake from [source](https://github.com/libgit2/libgit2/releases/tag/v1.3.0). +## Running Tests -8. Visit config UI at `localhost:4000` to configure data connections. - - Please follow the [tutorial](UserManuals/ConfigUI/Tutorial.md) - - Submit the form to update the values by clicking on the **Save Connection** button on each form page +```sh +# install mockery +go install github.com/vektra/mockery/v2@latest +# generate mocking stubs +make mock +# run tests +make test +``` -9. Visit `localhost:4000/pipelines/create` to RUN a Pipeline and trigger data collection. +## DB migrations +Please refer to the [Migration Doc](../DeveloperManuals/DBMigration.md). - Pipelines Runs can be initiated by the new "Create Run" Interface. Simply enable the **Data Connection Providers** you wish to run collection for, and specify the data you want to collect, for instance, **Project ID** for Gitlab and **Repository Name** for GitHub. +## Using DevLake API - Once a valid pipeline configuration has been created, press **Create Run** to start/run the pipeline. - After the pipeline starts, you will be automatically redirected to the **Pipeline Activity** screen to monitor collection activity. +All DevLake APIs (core service + plugin API) are documented with swagger. To see API doc live with swagger: - **Pipelines** is accessible from the main menu of the config-ui for easy access. + - Install [swag](https://github.com/swaggo/swag). + - Run `make swag` to generate the swagger documentation. + - Visit `http://localhost:8080/swagger/index.html` while `devlake` is running. - - Manage All Pipelines: `http://localhost:4000/pipelines` - - Create Pipeline RUN: `http://localhost:4000/pipelines/create` - - Track Pipeline Activity: `http://localhost:4000/pipelines/activity/[RUN_ID]` - For advanced use cases and complex pipelines, please use the Raw JSON API to manually initiate a run using **cURL** or graphical API tool such as **Postman**. `POST` the following request to the DevLake API Endpoint. +## Developing dashboards - ```json - [ - [ - { - "plugin": "github", - "options": { - "repo": "lake", - "owner": "merico-dev" - } - } - ] - ] - ``` +To access Grafana, click *View Dashboards* button in the top left corner of Config UI, or visit `localhost:3002` (username: `admin`, password: `admin`). - Please refer to [Pipeline Advanced Mode](../UserManuals/ConfigUI/AdvancedMode.md) for in-depth explanation. +For provisioning, customizing, and creating dashboards, please refer to our [Grafana Doc](../UserManuals/Dashboards/GrafanaUserGuide.md). -10. Click *View Dashboards* button in the top left when done, or visit `localhost:3002` (username: `admin`, password: `admin`). +## Troubleshooting - We use <a href="https://grafana.com/"; target="_blank">Grafana</a> as a visualization tool to build charts for the [data stored in our database](../DataModels/DevLakeDomainLayerSchema). Using SQL queries, we can add panels to build, save, and edit customized dashboards. - All the details on provisioning and customizing a dashboard can be found in the [Grafana Doc](../UserManuals/Dashboards/GrafanaUserGuide.md). + Q: Running `make dev` yields error: `libgit2.so.1.3: cannot open share object file: No such file or directory` -11. (Optional) To run the tests: + A: `libgit2.so.1.3` is required by the gitextractor plugin and should be . Make sure your program can find `libgit2.so.1.3`. `LD_LIBRARY_PATH` can be assigned like this if your `libgit2.so.1.3` is located at `/usr/local/lib`: ```sh - make test + export LD_LIBRARY_PATH=$LD_LIBRARY_PATH:/usr/local/lib ``` + + Note that the version has to be pinned to 1.3.0. If you don't have it, you may need to build it manually with CMake from [source](https://github.com/libgit2/libgit2/releases/tag/v1.3.0). -12. For DB migrations, please refer to [Migration Doc](../DeveloperManuals/DBMigration.md). - -13. Swagger documentation. - - - Install the `swag` package by following instruction on [swaggo](https://github.com/swaggo/swag). - - Run `make swag` to generate the Swagger Documentation. - - Visit `http://localhost:8080/swagger/index.html` while `devlake` is running. -14. Compiling +## Compiling - Compile all plugins: `make build-plugin` - Compile specific plugins: `PLUGIN=<PLUGIN_NAME> make build-plugin` - Compile server: `make build` - Compile worker: `make build-worker` - - -
