diff --git a/docs/administrator-documentation/moderne-platform/how-to-guides/agent-configuration/agent-config.md b/docs/administrator-documentation/moderne-platform/how-to-guides/agent-configuration/agent-config.md index 84f0a58f..1e1dc109 100644 --- a/docs/administrator-documentation/moderne-platform/how-to-guides/agent-configuration/agent-config.md +++ b/docs/administrator-documentation/moderne-platform/how-to-guides/agent-configuration/agent-config.md @@ -465,8 +465,8 @@ docker run \ -e MODERNE_AGENT_MAVEN_0_LOCALREPOSITORY=~/.moderne-maven \ -e MODERNE_AGENT_MAVEN_0_USERNAME \ -e MODERNE_AGENT_MAVEN_0_PASSWORD \ --e MODERNE_AGENT_ORGANIZATION_URL=http://localhost:8091 \ --e MODERNE_AGENT_ORGANIZATION_UPDATE_INTERVAL_SECONDS=600 \ +-e MODERNE_AGENT_ORGANIZATION_SERVICE_URL=http://localhost:8091 \ +-e MODERNE_AGENT_ORGANIZATION_SERVICE_UPDATE_INTERVAL_SECONDS=600 \ -p 8080:8080 moderne-agent:latest ``` @@ -498,8 +498,8 @@ java -jar moderne-agent-{version}.jar \ --moderne.agent.artifactory[0].astQueryFilters[1]='{"repo":{"$eq":"example-maven"}}' \ --moderne.agent.maven[0].url=https://myartifactory.example.com/artifactory/libs-releases-local \ --moderne.agent.maven[0].localRepository=~/.moderne-maven \ ---moderne.agent.organization.url=http://localhost:8091 \ ---moderne.agent.organization.updateIntervalSeconds=600 \ +--moderne.agent.organization.service.url=http://localhost:8091 \ +--moderne.agent.organization.service.updateIntervalSeconds=600 \ ``` @@ -545,8 +545,8 @@ docker run \ -e MODERNE_AGENT_MAVEN_0_LOCALREPOSITORY=~/.moderne-maven \ -e MODERNE_AGENT_MAVEN_0_USERNAME \ -e MODERNE_AGENT_MAVEN_0_PASSWORD \ --e MODERNE_AGENT_ORGANIZATION_URL=http://localhost:8091 \ --e MODERNE_AGENT_ORGANIZATION_UPDATE_INTERVAL_SECONDS=600 \ +-e MODERNE_AGENT_ORGANIZATION_SERVICE_URL=http://localhost:8091 \ +-e MODERNE_AGENT_ORGANIZATION_SERVICE_UPDATE_INTERVAL_SECONDS=600 \ -e MODERNE_AGENT_RECIPE_USEONLYCONFIGURED=true \ -p 8080:8080 moderne-agent:latest @@ -580,8 +580,8 @@ java -jar moderne-agent-{version}.jar \ --moderne.agent.artifactory[0].astQueryFilters[1]='{"repo":{"$eq":"example-maven"}}' \ --moderne.agent.maven[0].url=https://myartifactory.example.com/artifactory/libs-releases-local \ --moderne.agent.maven[0].localRepository=~/.moderne-maven \ ---moderne.agent.organization.url=http://localhost:8091 \ ---moderne.agent.organization.updateIntervalSeconds=600 \ +--moderne.agent.organization.service.url=http://localhost:8091 \ +--moderne.agent.organization.service.updateIntervalSeconds=600 \ --moderne.agent.recipe.useOnlyConfigured=true ``` @@ -646,8 +646,8 @@ docker run \ -e MODERNE_AGENT_MAVEN_0_LOCALREPOSITORY=~/.moderne-maven \ -e MODERNE_AGENT_MAVEN_0_USERNAME \ -e MODERNE_AGENT_MAVEN_0_PASSWORD \ --e MODERNE_AGENT_ORGANIZATION_URL=http://localhost:8091 \ --e MODERNE_AGENT_ORGANIZATION_UPDATE_INTERVAL_SECONDS=600 \ +-e MODERNE_AGENT_ORGANIZATION_SERVICE_URL=http://localhost:8091 \ +-e MODERNE_AGENT_ORGANIZATION_SERVICE_UPDATE_INTERVAL_SECONDS=600 \ -p 8080:8080 moderne-agent:latest ``` @@ -681,8 +681,8 @@ java -jar moderne-agent-{version}.jar \ --moderne.agent.artifactory[0].astQueryFilters[1]='{"repo":{"$eq":"example-maven"}}' \ --moderne.agent.maven[0].url=https://myartifactory.example.com/artifactory/libs-releases-local \ --moderne.agent.maven[0].localRepository=~/.moderne-maven \ ---moderne.agent.organization.url=http://localhost:8091 \ ---moderne.agent.organization.updateIntervalSeconds=600 \ +--moderne.agent.organization.service.url=http://localhost:8091 \ +--moderne.agent.organization.service.updateIntervalSeconds=600 \ ``` * Note: System properties can be used in place of arguments. For example, you can use `-Dmoderne.agent.token={token_value}` as an argument instead of `--moderne.agent.token={token_value}`. diff --git a/docs/administrator-documentation/moderne-platform/how-to-guides/agent-configuration/agent-variables.md b/docs/administrator-documentation/moderne-platform/how-to-guides/agent-configuration/agent-variables.md index 0a8b0f32..60033b38 100644 --- a/docs/administrator-documentation/moderne-platform/how-to-guides/agent-configuration/agent-variables.md +++ b/docs/administrator-documentation/moderne-platform/how-to-guides/agent-configuration/agent-variables.md @@ -414,8 +414,8 @@ docker run \ ```bash java -jar moderne-agent-{version}.jar \ # ... Existing arguments ---moderne.agent.organization.url=http://localhost:8091 \ ---moderne.agent.organization.updateIntervalSeconds=600 \ +--moderne.agent.organization.service.url=http://localhost:8091 \ +--moderne.agent.organization.service.updateIntervalSeconds=600 \ # ... Additional arguments ``` diff --git a/docs/administrator-documentation/moderne-platform/how-to-guides/agent-configuration/configure-agent-files-service.md b/docs/administrator-documentation/moderne-platform/how-to-guides/agent-configuration/configure-agent-files-service.md new file mode 100644 index 00000000..dd62e046 --- /dev/null +++ b/docs/administrator-documentation/moderne-platform/how-to-guides/agent-configuration/configure-agent-files-service.md @@ -0,0 +1,93 @@ +import Tabs from '@theme/Tabs'; +import TabItem from '@theme/TabItem'; + +# Configure the agent with the Agent with file sources + +In order for Moderne to obtain information about your organizational structure, you will need to configure the Moderne +agent to have access to the required files. This guide will explain how to do that. + + + + +**Variables:** + +| Argument Name | Required | Default | Description | +|-----------------------------------------------------|----------|--------------------------------------------|------------------------------------------------------------------------------------------------------| +| `MODERNE_AGENT_ORGANIZATION_FILE_REPOSCSVPATH` | `true` | | File path to the CSV file which outlines your organization structure | +| `MODERNE_AGENT_ORGANIZATION_FILE_COMMITOPTIONSPATH` | `false` | All options available. | File path a text file which set commit options for specific repositories | +| `MODERNE_AGENT_ORGANIZATION_FILE_IDMAPPINGPATH` | `false` | Organization use provided ID as their name | File path to a text which overrides any organization name to a different name then the provided ID | +| `MODERNE_AGENT_ORGANIZATION_FILE_DEVCENTERPATH` | `false` | A default Devcenter is provided | File path to a JSON file which outlines the DevCenter for specific organizations | + +**Example:** + +```bash +docker run \ +# ... Existing variables +-e MODERNE_AGENT_ORGANIZATION_FILE_REPOSCSVPATH=/Users/MY_USER/Documents/repos.csv \ +# ... Additional variables +``` + + + + + +**Arguments:** + +| Argument Name | Required | Default | Description | +|-------------------------------------------------------|----------|--------------------------------------------|------------------------------------------------------------------------------------------------------| +| `--moderne.agent.organization.file.reposCsvPath` | `true` | | File path to the CSV file which outlines your organization structure | +| `--moderne.agent.organization.file.commitOptionsPath` | `false` | All options available. | File path a text file which sets commit options for specific repositories | +| `--moderne.agent.organization.file.idMappingPath` | `false` | Organization use provided ID as their name | File path to a text which overrides any organizations name to a different name then the provided ID | +| `--moderne.agent.organization.file.devCenterPath` | `false` | A default Devcenter is provided | File path to a JSON file which outlines the DevCenter for specific organizations | + +**Example:** + +```bash +java -jar moderne-agent-{version}.jar \ +# ... Existing arguments +--moderne.agent.organization.file.reposCsvPath=/Users/MY_USER/Documents/repos.csv \ +# ... Additional arguments +``` + + + + +## Generating repos.csv +When provided your organization details, they must be provided in a CSV file with the following format: + +| cloneUrl | branch | org1 | org2 | org3 | +|---------------|----------|---------|-------------|------| +| `https://github.com/openrewrite/rewrite-recipe-bom` | main | Open Source | ALL | | +| `https://github.com/Netflix/spectator-go` | main | Netflix | Open Source | ALL | + +The organizations under `org1`, `org2`, `org3`, etc. represent the hierarchy of organizations. There is no limit to the number of organizations that can be provided via this CSV. + +The above example would be used in Moderne DX to generate an organizational listing of the following: + +* ALL + * Open Source + * `https://github.com/openrewrite/rewrite-recipe-bom:main` + * Netflix + * `https://github.com/Netflix/spectator-go:main` + +To generate this `repos.csv`, we recommend using "[repo fetchers](https://github.com/moderneinc/repository-fetchers)". + +## Generating commitOptions.txt +If you want to provide specific commit options for specific repositories, these can be provided in a text file with the following format: +```text +My_Organzation_ID_1=Branch,PullRequest +My_Organzation_ID_2=Branch,Direct,PullRequest +``` + +Any organization not listed in this file will fall back to either default commit options. + +## Generating idMapping.txt +By default an organization name is the same as its ID, if you want to change an organization name, these can be provided in a text file with the following format: +```text +My_Organzation_ID_1=My_Organzation_Name_1 +My_Organzation_ID_2=My_Organzation_Name_2 +``` + +## Generating devCenter.json +The provided devCenter.json should follow the structure of this [file](https://github.com/moderneinc/moderne-organizations/blob/main/src/main/resources/devcenter.json). +For more details about configuring your DevCenter please reference this [guide](../dev-center.md#step-3-create-and-configure-the-devcenter). diff --git a/docs/administrator-documentation/moderne-platform/how-to-guides/dev-center.md b/docs/administrator-documentation/moderne-platform/how-to-guides/dev-center.md index 8a0b14d9..a83e03af 100644 --- a/docs/administrator-documentation/moderne-platform/how-to-guides/dev-center.md +++ b/docs/administrator-documentation/moderne-platform/how-to-guides/dev-center.md @@ -13,7 +13,7 @@ In this doc, we'll walk you through everything you need to know to configure you In order to configure any DevCenters, there are two things you need to do (which we'll walk through in more detail below): -1. You must have [configured an Organizations service](./organizations-service.md). +1. You must have [configured an Organizations service](./organizations-service.md). If you are not using an organization service your agent must be [configured to return a devCenter.json](./organizations-service.md). 2. You must ensure that the [Moderne agent Maven configuration](./agent-configuration/configure-an-agent-with-maven-repository-access.md) only has **one** entry where the recipe source is set to `true`. (Note: this does not apply to one Maven repository configured identically in multiple agents. Only that you cannot have two distinct Maven repositories configured where recipe source is set to `true`.) ### Organizations service @@ -69,7 +69,7 @@ The [DevCenter object](https://github.com/moderneinc/moderne-organizations/blob/ ## Step 3: Create and configure the DevCenter -Your service must fulfill the [GraphQL contract mentioned in the previous step](https://github.com/moderneinc/moderne-organizations/blob/main/src/main/resources/schema/organizations.graphqls). If you chose to use [our template repository](https://github.com/moderneinc/moderne-organizations) for your Organizations service, you will need to run `./gradlew generateGraphqlJava copyGeneratedGraphql` to [get the latest types](https://github.com/moderneinc/moderne-organizations/pull/61/files), and then you will need to configure your own [devcenter.json file](https://github.com/moderneinc/moderne-organizations/blob/main/src/main/resources/devcenter.json). +Your organization service must fulfill the [GraphQL contract mentioned in the previous step](https://github.com/moderneinc/moderne-organizations/blob/main/src/main/resources/schema/organizations.graphqls), or your agent must be set up to return the devCenter.json. If you chose to use [our template repository](https://github.com/moderneinc/moderne-organizations) for your Organizations service, you will need to run `./gradlew generateGraphqlJava copyGeneratedGraphql` to [get the latest types](https://github.com/moderneinc/moderne-organizations/pull/61/files), and then you will need to configure your own [devcenter.json file](https://github.com/moderneinc/moderne-organizations/blob/main/src/main/resources/devcenter.json). The `devcenter.json` file is where all of the configuration lies for DevCenters. In this file, you can configure things like which organizations should have a DevCenter, what cards should appear on said DevCenter, and what the keys should be on the cards. This file must follow the GraphQL schema mentioned above. diff --git a/docs/administrator-documentation/moderne-platform/how-to-guides/organizations-service.md b/docs/administrator-documentation/moderne-platform/how-to-guides/organizations-service.md index 9f5a92da..4e9e1626 100644 --- a/docs/administrator-documentation/moderne-platform/how-to-guides/organizations-service.md +++ b/docs/administrator-documentation/moderne-platform/how-to-guides/organizations-service.md @@ -11,12 +11,25 @@ Let's walk through everything you need to know to build and integrate such a ser ## Integration requirements +This can be done by either providing the required files on the Agent service or by setting up an organization service. +Running an Organization service allows for more flexibility when setting up the required GraphQL and REST endpoint. While +providing the requisite files on the Agent requires less setup. + +Note: When selecting which option is best for you, keep in mind that you can change the approach you have taken later. + +## Providing the files on the Agent service +When providing files on the Agent service, + +1. Create and deploy an Organizations service that fulfills [this GraphQL contract](https://github.com/moderneinc/moderne-organizations/blob/main/src/main/resources/schema/organizations.graphqls) and [this REST contract](https://github.com/moderneinc/moderne-organizations/blob/main/src/main/java/io/moderne/organizations/OrganizationController.java) your environment_ +2. [Configure your Moderne agent to point to this service](./agent-configuration/configure-agent-file-service.md) + +## Running an Organization service In order to dynamically control the organizational structure in Moderne, you will need to: -1. Create and deploy an Organizations service that fulfills [this GraphQL contract](https://github.com/moderneinc/moderne-organizations/blob/main/src/main/resources/schema/organizations.graphqls) _in your environment_ +1. Create and deploy an Organizations service that fulfills [this GraphQL contract](https://github.com/moderneinc/moderne-organizations/blob/main/src/main/resources/schema/organizations.graphqls) and [this REST contract](https://github.com/moderneinc/moderne-organizations/blob/main/src/main/java/io/moderne/organizations/OrganizationController.java) your environment_ 2. [Configure your Moderne agent to point to this service](./agent-configuration/configure-organizations-service.md) -## Coding the Organizations service +### Coding the Organizations service You have two main options for building this service. You can: @@ -25,7 +38,7 @@ You have two main options for building this service. You can: We generally recommend forking the template and modifying it as, in most cases, that will be faster and easier than building it yourself. Regardless of which one you choose, however, some developer time will be required on your end. -## Deploying the service +### Deploying the service How you deploy the service is largely up to your company. With that being said, there are a few important things to be aware of: