jlengrand/moderne-docs
1
0
Fork 0
mirror of https://github.com/jlengrand/moderne-docs.git synced 2026-03-10 08:31:21 +00:00
Code Issues Packages Projects Releases Wiki Activity

feat: adding documentation for using repos.csv and associated files

Browse Source 
We have added the option to no run an organization service and instead provide the required files on the Agent.
This commit is contained in:
leanne
2025-03-10 11:12:04 -07:00
parent 6eacf154bf
commit c55fcbbd07
5 changed files with 125 additions and 19 deletions
Download Patch File Download Diff File Expand all files Collapse all files

24
docs/administrator-documentation/moderne-platform/how-to-guides/agent-configuration/agent-config.md
View File

@@ -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 \
```
</TabItem>
</Tabs>
@@ -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
```
</TabItem>
@@ -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}`.

4
docs/administrator-documentation/moderne-platform/how-to-guides/agent-configuration/agent-variables.md
View File

@@ -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
```
</TabItem>

93
docs/administrator-documentation/moderne-platform/how-to-guides/agent-configuration/configure-agent-files-service.md Normal file
View File

@@ -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.
<Tabs groupId="agent-type">
<TabItem value="oci-container" label="OCI Container">
**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
```
</TabItem>
<TabItem value="executable-jar" label="Executable JAR">
**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
```
</TabItem>
</Tabs>
## 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).

4
docs/administrator-documentation/moderne-platform/how-to-guides/dev-center.md
View File

@@ -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.

19
docs/administrator-documentation/moderne-platform/how-to-guides/organizations-service.md
View File

@@ -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: