GitBook: [#84] moderne agent docker config file

2026-03-10 08:31:21 +00:00 · 2022-07-25 15:56:17 +00:00
parent f14140e40b
commit 561b6cb43b
3 changed files with 86 additions and 2 deletions
--- a/SUMMARY.md
+++ b/SUMMARY.md
@@ -30,6 +30,7 @@
 * [Interactions with git when applying changes](references/how-moderne-applies-changes.md)
 * [Routing requests to agents](references/routing-requests-to-agents.md)
 * [How AST artifacts are produced](references/how-ast-artifacts-are-produced.md)
+* [Docker configuration for agent](references/docker-configuration-for-agent.md)

 ## Legal

--- a/how-to/on-premise-agent/README.md
+++ b/how-to/on-premise-agent/README.md
@@ -10,9 +10,11 @@ The purpose of the Moderne on-premise agent is to encrypt and ship AST artifacts

 ## Getting Started

+### Basic Usage
+
 ### Run the agent container

-The Moderne on-premise agent is available as an OCI image or as a spring-boot executable jar artifact. Contact Moderne to obtain access. Moderne will provide access details appropriate for your chosen platform. In example commands below we will refer to this as `${MODERNE_AGENT_IMAGE_NAME}.` The latest one will be displayed in the "Agent" section of [the releases page](https://docs.moderne.io/releases/releases).
+The Moderne on-premise agent is available as an OCI image or as a spring-boot executable jar artifact. Contact Moderne to obtain access. Moderne will provide access details appropriate for your chosen platform. In example commands below we will refer to this as `${MODERNE_AGENT_IMAGE_NAME}.` The latest one will be displayed in the "Agent" section of [the releases page](../releases/releases.md).

 {% tabs %}
 {% tab title="OCI Container" %}
@@ -34,6 +36,11 @@ docker run \
 -e MODERNE_AGENT_API_GATEWAY_RSOCKET_URI=https://api.tenant.moderne.io/rsocket \
 -e MODERNE_AGENT_TOKEN=W43qp4h952T4w2qV \
 -e MODERNE_AGENT_CRYPTO_SYMMETRICKEY=546A576E5A7234753778217A25432A462D4A614E645267556B58703273357638 \
+-e MODERNE_AGENT_ARTIFACTORY_0_URL=https://myartifactory.example.com/artifactory/ \
+-e MODERNE_AGENT_ARTIFACTORY_0_USERNAME=admin \
+-e MODERNE_AGENT_ARTIFACTORY_0_PASSWORD=password \
+-e MODERNE_AGENT_ARTIFACTORY_0_ASTSQUERYFILTERS_0='{"name":{"$match":"*-ast.jar"}}' \
+-e MODERNE_AGENT_ARTIFACTORY_0_ASTSQUERYFILTERS_1='{"repo":{"$eq":"example-maven"}}' \
 ${MODERNE_AGENT_IMAGE_NAME}
 ```
 {% endtab %}
@@ -45,6 +52,10 @@ The agent application requires several arguments:
 * `--moderne.agent.token` - Moderne SaaS agent connection token, provided by Moderne
 * `--moderne.agent.crypto.symmetricKey` - 256 bit AES encryption key, hex encoded
  * example openssl command to generate: `openssl enc -aes-256-cbc -k secret -P` (use key from the output)
+* `--moderne.agent.artifactory[0].url` - Artifactory URL
+* `--moderne.agent.artifactory[0].username` - username used to connect to Artifactory, requires permission to run AQL queries
+* `--moderne.agent.artifactory[0].password` - password used to connect to Artifactory
+* `--moderne.agent.artifactory[0].astQueryFilters[0]` - AQL query fragment used to select AST artifacts to send to Moderne

 Note: system properties can be used in place of arguments. As an example, use `-Dmoderne.agent.token={token_value}` as an argument instead of `--moderne.agent.token={token_value}` as an argument.

@@ -54,7 +65,12 @@ Example (note that agent token and symmetric key are random examples)
 java -jar moderne-agent-{version}.jar \
 --moderne.agent.api-gateway-roscket-uri==https://api.tenant.moderne.io/rsocket \
 --moderne.agent.token=W43qp4h952T4w2qV \
--moderne.agent.crypto.symmetricKey=546A576E5A7234753778217A25432A462D4A614E645267556B58703273357638
+--moderne.agent.crypto.symmetricKey=546A576E5A7234753778217A25432A462D4A614E645267556B58703273357638 \
+--moderne.agent.artifactory[0].url=https://myartifactory.example.com/artifactory/ \
+--moderne.agent.artifactory[0].username=admin \
+--moderne.agent.artifactory[0].password=password \
+--moderne.agent.artifactory[0].astQueryFilters[0]='{"name":{"$match":"*-ast.jar"}}' \
+--moderne.agent.artifactory[0].astQueryFilters[1]='{"repo":{"$eq":"example-maven"}}'
 ```
 {% endtab %}
 {% endtabs %}
@@ -70,3 +86,34 @@ To upgrade your version of the OCI container, just follow the instructions above
 To update your version of the Executable JAR, change the numbered version of {agent} in the instructions above to the latest on [the releases page](../../releases/releases.md).
 {% endtab %}
 {% endtabs %}
+
+### Advanced Usage
+
+#### Hashicorp Vault
+
+The Moderne agent optionally fetches secret configuration from Vault. It reads from a KV secret engine named "secret", and reads secret keys at path "moderne-agent". To configure the secret key/value pairs, follow the following procedure:
+
+1. In the Vault management web application, go to Secrets. If there's not already a KV engine named "secret", create it.
+2. In the "secret" KV secrets engine, create a new secret using "moderne-agent" as the "Path for this secret".
+3. Add the following keys to the moderne-agent secret:
+   * `moderne.agent.token` - Moderne SaaS agent connection token, provided by Moderne
+   * `moderne.agent.crypto.symmetricKey` - 256 bit AES encryption key, hex encoded
+   * `moderne.agent.artifactory[0].password` - Artifactory user password
+
+{% tabs %}
+{% tab title="OCI Container" %}
+To enable vault integration in the agent, omit environment variables that match keys specified in vault, and specify the following additional environment variables for the agent container:
+
+* `SPRING_PROFILES_ACTIVE` - `vault`
+* `SPRING_CLOUD_VAULT_URI` - Vault URI used to retrieve the secret configuration properties below
+* `SPRING_CLOUD_VAULT_TOKEN` - Vault authentication token
+{% endtab %}
+
+{% tab title="Executable JAR" %}
+To enable vault integration in the agent, omit arguments that match keys specified in vault, and specify the following additional arguments for the agent application:
+
+* `spring.profiles.active` - vault
+* `spring.cloud.vault.uri` `SPRING_CLOUD_VAULT_URI` - Vault URI used to retrieve the secret configuration properties below
+* `SPRING_CLOUD_VAULT_TOKEN` - Vault authentication token
+{% endtab %}
+{% endtabs %}
--- a/references/docker-configuration-for-agent.md
+++ b/references/docker-configuration-for-agent.md
@@ -0,0 +1,36 @@
+# Docker configuration for agent
+
+### Running Moderne Agent Docker container
+
+```
+docker run --env-file sample-agent.env moderne-dev/moderne/moderne-agent:0.65.0
+```
+
+### Example `sample-agent.env` file
+
+```
+# Required
+MODERNE_AGENT_TOKEN=token_provided_by_moderne
+MODERNE_AGENT_APIGATEWAYRSOCKETURI=https://api.YOUR_TENANT_NAME.moderne.io/rsocket
+MODERNE_AGENT_CRYPTO_SYMMETRICKEY=some_key
+
+# Bitbucket Server
+MODERNE_AGENT_BITBUCKET_0_URL=https://mybitbucket.your-domain.com
+MODERNE_AGENT_BITBUCKET_0_PRIVATE_KEY=REALLY_LONG_PRIVATE_KEY_AS_ONE_LINE
+
+# GitHub Configuration with GitHub OAuth Client
+MODERNE_AGENT_GITHUB_0_URL=https://github.com # https://github.on-prem.your-domain.com
+MODERNE_AGENT_GITHUB_0_OAUTH_CLIENTID=your_provided_github_client_id
+MODERNE_AGENT_GITHUB_0_OAUTH_CLIENTSECRET=your_provided_github_client_secret
+MODERNE_AGENT_GITHUB_0_OAUTH_INCLUDEPRIVATEREPOS=true # false
+
+# Artifactory 
+MODERNE_AGENT_ARTIFACTORY_0_URL=https://myartifactory.your-domain.com
+MODERNE_AGENT_ARTIFACTORY_0_USERNAME=myartifactory
+MODERNE_AGENT_ARTIFACTORY_0_PASSWORD==myartifactory_password
+MODERNE_AGENT_ARTIFACTORY_0_ASTQUERYFILTERS_0='{"name":{"$match":"*-ast.jar"}}'
+MODERNE_AGENT_ARTIFACTORY_0_ASTQUERYFILTERS_1='{"repo":{"$eq":"example-maven"}}'
+
+# (Optional) Artifactory Recipes
+MODERNE_AGENT_ARTIFACTORY_0_RECIPEREPOSITORIES_0=custom_recipes
+```