github.com/argoproj/argo-cd/v3@v3.2.1/docs/developer-guide/debugging-locally.md (about)

     1  # Debugging a local Argo CD instance
     2  
     3  ## Prerequisites
     4  1. [Development Environment](development-environment.md)   
     5  2. [Toolchain Guide](toolchain-guide.md)
     6  3. [Development Cycle](development-cycle.md)
     7  4. [Running Locally](running-locally.md)
     8  
     9  ## Preface
    10  Please make sure you are familiar with running Argo CD locally using the [local toolchain](running-locally.md#start-local-services-local-toolchain).
    11  
    12  When running Argo CD locally for manual tests, the quickest way to do so is to run all the Argo CD components together, as described in [Running Locally](running-locally.md), 
    13  
    14  However, when you need to debug a single Argo CD component (for example, `api-server`, `repo-server`, etc), you will need to run this component separately in your IDE, using your IDE launch and debug configuration, while the other components will be running as described previously, using the local toolchain.
    15  
    16  For the next steps, we will use Argo CD `api-server` as an example of running a component in an IDE.
    17  
    18  ## Configure your IDE
    19  
    20  ### Locate your component configuration in `Procfile`
    21  The `Procfile` is used by Goreman when running Argo CD locally with the local toolchain. The file is located in the top-level directory in your cloned Argo CD repo folder, you can view it's latest version [here](https://github.com/argoproj/argo-cd/blob/master/Procfile). It contains all the needed component run configuration, and you will need to copy parts of this configuration to your IDE. 
    22  
    23  Example for `api-server` configuration in `Procfile`:
    24  ``` text
    25  api-server: [ "$BIN_MODE" = 'true' ] && COMMAND=./dist/argocd || COMMAND='go run ./cmd/main.go' && sh -c "GOCOVERDIR=${ARGOCD_COVERAGE_DIR:-/tmp/coverage/api-server} FORCE_LOG_COLORS=1 ARGOCD_FAKE_IN_CLUSTER=true ARGOCD_TLS_DATA_PATH=${ARGOCD_TLS_DATA_PATH:-/tmp/argocd-local/tls} ARGOCD_SSH_DATA_PATH=${ARGOCD_SSH_DATA_PATH:-/tmp/argocd-local/ssh} ARGOCD_BINARY_NAME=argocd-server $COMMAND --loglevel debug --redis localhost:${ARGOCD_E2E_REDIS_PORT:-6379} --disable-auth=${ARGOCD_E2E_DISABLE_AUTH:-'true'} --insecure --dex-server http://localhost:${ARGOCD_E2E_DEX_PORT:-5556} --repo-server localhost:${ARGOCD_E2E_REPOSERVER_PORT:-8081} --port ${ARGOCD_E2E_APISERVER_PORT:-8080} --otlp-address=${ARGOCD_OTLP_ADDRESS} --application-namespaces=${ARGOCD_APPLICATION_NAMESPACES:-''} --hydrator-enabled=${ARGOCD_HYDRATOR_ENABLED:='false'}"
    26  ```
    27  This configuration example will be used as the basis for the next steps.
    28  
    29  !!! note
    30      The Procfile for a component may change with time. Please go through the Procfile and make sure you use the latest configuration for debugging.
    31  
    32  ### Configure component env variables
    33  The component that you will run in your IDE for debugging (`api-server` in our case) will need env variables. Copy the env variables from `Procfile`, located in the `argo-cd` root folder of your development branch. The env variables are located before the `$COMMAND` section in the `sh -c` section of the component run command.
    34  You can keep them in `.env` file and then have the IDE launch configuration point to that file. Obviously, you can adjust the env variables to your needs when debugging a specific configuration.
    35  
    36  Example for an `api-server.env` file:
    37  ``` bash
    38  ARGOCD_BINARY_NAME=argocd-server
    39  ARGOCD_FAKE_IN_CLUSTER=true
    40  ARGOCD_GNUPGHOME=/tmp/argocd-local/gpg/keys
    41  ARGOCD_GPG_DATA_PATH=/tmp/argocd-local/gpg/source
    42  ARGOCD_GPG_ENABLED=false
    43  ARGOCD_LOG_FORMAT_ENABLE_FULL_TIMESTAMP=1
    44  ARGOCD_SSH_DATA_PATH=/tmp/argocd-local/ssh
    45  ARGOCD_TLS_DATA_PATH=/tmp/argocd-local/tls
    46  ARGOCD_TRACING_ENABLED=1
    47  FORCE_LOG_COLORS=1
    48  KUBECONFIG=/Users/<YOUR_USERNAME>/.kube/config # Must be an absolute full path
    49  ... 
    50  # and so on, for example: when you test the app-in-any-namespace feature, 
    51  # you'll need to add ARGOCD_APPLICATION_NAMESPACES to this list 
    52  # only for testing this functionality and remove it afterwards.
    53  ```
    54  
    55  ### Install DotENV / EnvFile plugin
    56  Using the market place / plugin manager of your IDE. The below example configurations require the plugin to be installed.
    57  
    58  
    59  ### Configure component IDE launch configuration
    60  #### VSCode example
    61  Next, you will need to create a launch configuration, with the relevant args. Copy the args from `Procfile`, located in the `argo-cd` root folder of your development branch. The args are located after the `$COMMAND` section in the `sh -c` section of the component run command.
    62  Example for an `api-server` launch configuration, based on our above example for `api-server` configuration in `Procfile`: 
    63  ``` json
    64      {
    65        "name": "api-server",
    66        "type": "go",
    67        "request": "launch",
    68        "mode": "auto",
    69        "program": "YOUR_CLONED_ARGO_CD_REPO_PATH/argo-cd/cmd",
    70        "args": [
    71          "--loglevel",
    72          "debug",
    73          "--redis",
    74          "localhost:6379",
    75          "--repo-server",
    76          "localhost:8081",
    77          "--dex-server",
    78          "http://localhost:5556",
    79          "--port",
    80          "8080",
    81          "--insecure"
    82        ],
    83        "envFile": "YOUR_ENV_FILES_PATH/api-server.env", # Assuming you installed DotENV plugin
    84      }
    85  ```
    86  
    87  #### Goland example
    88  Next, you will need to create a launch configuration, with the relevant parameters. Copy the parameters from `Procfile`, located in the `argo-cd` root folder of your development branch. The parameters are located after the `$COMMAND` section in the `sh -c` section of the component run command.
    89  Example for an `api-server` launch configuration snippet, based on our above example for `api-server` configuration in `Procfile`: 
    90  ``` xml 
    91  <component name="ProjectRunConfigurationManager">
    92    <configuration default="false" name="api-server" type="GoApplicationRunConfiguration" factoryName="Go Application">
    93      <module name="argo-cd" />
    94      <working_directory value="$PROJECT_DIR$" />
    95      <parameters value="--loglevel debug --redis localhost:6379 --insecure --dex-server http://localhost:5556 --repo-server localhost:8081 --port 8080" />
    96      <EXTENSION ID="net.ashald.envfile"> <!-- Assuming you installed the EnvFile plugin-->
    97        <option name="IS_ENABLED" value="true" />
    98        <option name="IS_SUBST" value="false" />
    99        <option name="IS_PATH_MACRO_SUPPORTED" value="false" />
   100        <option name="IS_IGNORE_MISSING_FILES" value="false" />
   101        <option name="IS_ENABLE_EXPERIMENTAL_INTEGRATIONS" value="false" />
   102        <ENTRIES>
   103          <ENTRY IS_ENABLED="true" PARSER="runconfig" IS_EXECUTABLE="false" />
   104          <ENTRY IS_ENABLED="true" PARSER="env" IS_EXECUTABLE="false" PATH="<YOUR_ENV_FILES_PATH>/api-server.env" />
   105        </ENTRIES>
   106      </EXTENSION>
   107      <kind value="DIRECTORY" />
   108      <directory value="$PROJECT_DIR$/cmd" />
   109      <filePath value="$PROJECT_DIR$" />
   110      <method v="2" />
   111    </configuration>
   112  </component>
   113  ```
   114  
   115  !!! note
   116      As an alternative to importing the above file to Goland, you can create a Run/Debug Configuration using the official [Goland docs](https://www.jetbrains.com/help/go/go-build.html) and just copy the `parameters`, `directory` and `PATH` sections from the example above (specifying `Run kind` as `Directory` in the Run/Debug Configurations wizard)
   117  
   118  ## Run Argo CD without the debugged component
   119  Next, we need to run all Argo CD components, except for the debugged component (cause we will run this component separately in the IDE).
   120  There is a mix-and-match approach to running the other components - you can run them in your K8s cluster or locally with the local toolchain.
   121  Below are the different options.
   122  
   123  ### Run the other components locally
   124  #### Run with "make start-local"
   125  `make start-local` runs all the components by default, but it is also possible to run it with a whitelist of components, enabling the separation we need.
   126  
   127  So for the case of debugging the `api-server`, run:
   128  `make start-local ARGOCD_START="notification applicationset-controller repo-server redis dex controller ui"` 
   129  
   130  #### Run with "make run"
   131  `make run` runs all the components by default, but it is also possible to run it with a blacklist of components, enabling the separation we need.
   132  
   133  So for the case of debugging the `api-server`, run:
   134  `make run exclude=api-server` 
   135  
   136  #### Run with "goreman start"
   137  `goreman start` runs all the components by default, but it is also possible to run it with a whitelist of components, enabling separation as needed.
   138  
   139  To debug the `api-server`, run:
   140  `goreman start notification applicationset-controller repo-server redis dex controller ui` 
   141  
   142  ## Run Argo CD debugged component from your IDE
   143  Finally, run the component you wish to debug from your IDE and make sure it does not have any errors.
   144  
   145  ## Important
   146  When running Argo CD components separately, ensure components aren't creating conflicts - each component needs to be up exactly once, be it running locally with the local toolchain or running from your IDE. Otherwise you may get errors about ports not available or even debugging a process that does not contain your code changes.