chore: merging main (#42)

* chore: sed syntax in CLI version workflow (#24)

* chore: syntax in CLI version workflow (#26)

* chore: syntax in CLI version workflow (#28)

* chore: syntax in CLI version workflow (#30)

* chore: syntax in CLI version workflow (#31)

* docs: akka CLI docs (#32)

Co-authored-by: GitHub <noreply@github.com>

* chore: remove static methods from the quickstart domain model (#25)

* docs: automatically publish docs-current (#35)

* docs: updated docker credentials management (#38)

* docs: CLI 3.0.6

* chore: update GH bot name (#40)

* docs: make Antora errors stop the build; fix most warnings (#41)

* chore: pass runtime version as arg (#43)

---------

Co-authored-by: Enno Runne <458526+ennru@users.noreply.github.com>
Co-authored-by: github-actions[bot] <41898282+github-actions[bot]@users.noreply.github.com>
Co-authored-by: GitHub <noreply@github.com>
Co-authored-by: Andrzej Ludwikowski <aludwiko@users.noreply.github.com>
Co-authored-by: James Roper <james@jazzy.id.au>

.github/workflows/docs-cli-updates.yml

@@ -19,18 +19,18 @@ jobs:
       with:
         ruby-version: '3.1'
 
-    - name: Install Akka CLI
+    - name: Install Akka CLI and create the CLI docs
       id: install-cli
       run: |
         export CLI_INSTALL_PATH=$HOME/.akka/bin
+        export PATH=${PATH}:${CLI_INSTALL_PATH}
         mkdir -p ${CLI_INSTALL_PATH}
-        curl -sL https://docs.akka.io/install-cli.sh | bash -s -- -y -P ${CLI_INSTALL_PATH}
-        echo ${CLI_INSTALL_PATH} >> ${GITHUB_PATH}
-        echo "CLI_VERSION=$(${CLI_INSTALL_PATH}/akka version)" >> ${GITHUB_OUTPUT}
-
-    - name: Script
-      run: |
-        sed -i '' "s/\(echo \":akka-cli-version: \)[^\"]*/\1${CLI_VERSION}/" Makefile
+        chmod +x docs/src-static/install-cli.sh
+        docs/src-static/install-cli.sh --force --prefix=${CLI_INSTALL_PATH}
+        CLI_VERSION=$(akka version)
+        echo "setting CLI version to ${CLI_VERSION}"
+        sed -i.bak "s/\(echo \":akka-cli-version: \)[^\"]*/\1${CLI_VERSION}/" Makefile
+        rm Makefile.bak
         gem install kramdown-asciidoc
         ./docs/bin/generate_cli_docs.sh gen-index
 

.github/workflows/docs-prod.yml

@@ -1,9 +1,9 @@
 name: Documentation to doc.akka.io
 on:
   workflow_dispatch:
-#  push:
-#    branches:
-#      - 'docs-current'
+  push:
+    branches:
+      - 'docs-current'
 
 permissions:
   contents: read

.github/workflows/update-sdk-version.yml

@@ -68,8 +68,8 @@ jobs:
           ./updateSdkVersions.sh all
           BRANCH=bump-sdk-versions-${SDK_VERSION}
           git checkout -b ${BRANCH}
-          git config user.name "Kalix Bot"
-          git config user.email "kalix.github@lightbend.com"
+          git config user.name "Akka Bot"
+          git config user.email "github-actions@users.noreply.github.com"
           git commit . -m "chore: bump SDK versions to ${SDK_VERSION}"
           git remote add origin-rw https://${GH_TOKEN}@github.com/akka/akka-sdk
           git push --set-upstream origin-rw ${BRANCH}

Makefile

@@ -44,7 +44,7 @@ attributes: prepare
 		> "${managed_partials}/attributes.adoc"
 	docs/bin/version.sh | xargs -0  printf ":akka-javasdk-version: %s" \
 		> "${managed_partials}/attributes.adoc"
-	echo ":akka-cli-version: 3.0.5"     >> "${managed_partials}/attributes.adoc"
+	echo ":akka-cli-version: 3.0.6"     >> "${managed_partials}/attributes.adoc"
 	echo ":akka-cli-min-version: 3.0.4" >> "${managed_partials}/attributes.adoc"
 	# see https://adoptium.net/marketplace/
 	echo ":java-version: 21" \
@@ -88,7 +88,7 @@ antora-local:
 		-v ${ROOT_DIR}:/antora \
 		--rm \
 		-t ${antora_docker_image}:${antora_docker_image_tag} \
-		--cache-dir=.cache/antora --stacktrace --log-failure-level=fatal \
+		--cache-dir=.cache/antora --stacktrace --log-failure-level=error \
 		docs/antora-playbook-local.yml
 
 antora-prod:

docs/src/modules/ROOT/partials/include.adoc

@@ -1,5 +1,7 @@
 // global attributes
 
 :sample-base-url: https://github.com/akka/akka-sdk/blob/main/samples
+// Docker Registry HTTP API Version
+:docker_registry_http_api_version: v1
 
 include::partial$attributes.adoc[]

docs/src/modules/java/pages/http-endpoints.adoc

@@ -131,7 +131,7 @@ include::example$shopping-cart-quickstart/src/main/java/shoppingcart/api/Shoppin
 <3> GET endpoint path is combined with a path parameter name, e.g. `/carts/123`.
 <4> The component client can be used to interact with other components.
 <5> Result of a request to a component is a `CompletionStage<T>`, it can be returned directly to let Akka serialize it.
-<6> Use path parameter `{cartId}` in combination with request body `ShoppingCart.LineItem`.
+<6> Use path parameter `+{cartId}+` in combination with request body `ShoppingCart.LineItem`.
 <7> Result of request mapped to a more suitable response, in this case, `200 Ok` with an empty body.
 
 For more details see xref:component-and-service-calls.adoc[]

docs/src/modules/java/pages/shopping-cart-quickstart.adoc

@@ -126,7 +126,7 @@ include::example$shopping-cart-quickstart/src/main/java/shoppingcart/api/Shoppin
 <3> GET endpoint path is combined with a path parameter name, e.g. `/carts/123`.
 <4> `ComponentClient` calling a command handler on an Event Sourced Entity from inside an Endpoint.
 <5> Result of request is a `CompletionStage<T>`, in this case a `CompletionStage<ShoppingCart>`.
-<6> Use path parameter `{cartId}` in combination with request body `ShoppingCart.LineItem`.
+<6> Use path parameter `+{cartId}+` in combination with request body `ShoppingCart.LineItem`.
 <7> Map request to a more suitable response, in this case an `HTTP 200 OK` response.
 
 

docs/src/modules/operations/pages/observability-and-monitoring/observability-exports.adoc

@@ -59,6 +59,7 @@ This will open the observability descriptor in a text editor. After saving and e
 After updating your observability configuration, you will need to restart a service to apply the new configuration. Akka automatically makes that a rolling restart.
 ====
 
+[#activating_tracing]
 === Activating tracing (Beta)
 
 The generation of traces is disabled by default. To enable it you need to set xref:reference:descriptors/service-descriptor.adoc#_servicespec[telemetry/tracing/enabled] to `true` in the service descriptor. Like the following:

docs/src/modules/operations/pages/observability-and-monitoring/traces.adoc

@@ -1,6 +1,6 @@
 = View traces 
 
-Akka projects have the traces dashboard built-in as part of the Control Tower in the Akka Console. This is available out-of-the-box. You can find your traces here as long as you have xref:operations:observability-and-monitoring/observability-exports.adoc#_activating_tracing_beta[enabled the traces] in your service.
+Akka projects have the traces dashboard built-in as part of the Control Tower in the Akka Console. This is available out-of-the-box. You can find your traces here as long as you have xref:operations:observability-and-monitoring/observability-exports.adoc#activating_tracing[enabled the traces] in your service.
 
 In the top panel you have the list of traces you can inspect. When you click on one of them, the contents of the trace are displayed in the panel below. As shown in the figure. 
 

docs/src/modules/operations/pages/observability-and-monitoring/view-logs.adoc

@@ -1,5 +1,6 @@
 = View logs
 include::ROOT:partial$include.adoc[]
+
 :page-supergroup-browser-cli: Interface
 
 Akka provides logs that you can view in the Console or access with the CLI. For each service instance we aggregate a maximum of 1MB of log data. You can capture all log output by attaching a logging provider, such as Google Cloud's operations suite (formerly Stackdriver), as described xref:observability-and-monitoring/observability-exports.adoc#_google_cloud[here].
@@ -31,7 +32,7 @@ Logs can be exported for searching, reporting, alerting and long term storage by
 
 == Correlating logs
 
-You can correlate your log statements, those that you write in your application, by adding the MDC pattern `%mdc{trace_id}` to your log file when tracing is xref:operations:observability-and-monitoring/observability-exports.adoc#_activating_tracing_beta[enabled]. Like the following:
+You can correlate your log statements, those that you write in your application, by adding the MDC pattern `%mdc{trace_id}` to your log file when tracing is xref:operations:observability-and-monitoring/observability-exports.adoc#activating_tracing[enabled]. Like the following:
 
 [source,xml]
 .logback.xml

docs/src/modules/operations/pages/organizations/manage-users.adoc

@@ -44,7 +44,7 @@ fd21044c-b973-4220-8f65-0f7d317bb23b   superuser   jane.citizen   jane.citizen@e
 
 You can grant a role to a user in two ways:
 
-==== 1. Invite a User by Email
+=== 1. Invite a User by Email
 Send an email invitation with the following command:
 
 [source,command window]
@@ -56,7 +56,7 @@ akka organizations invitations create --organization <organization name> \
 The user will receive an email to join the organization. Once accepted, the role binding will be created.
 
 
-==== 2. Add a Role Directly
+=== 2. Add a Role Directly
 
 If the user is already a member, you can assign roles directly:
 

docs/src/modules/operations/pages/projects/external-container-registries.adoc

@@ -6,6 +6,8 @@ To use an external container registry with Akka, you need to give Akka permissio
 [NOTE]
 If the container registry you're using does not require authentication, you don't have to add any credentials. Akka will automatically pull the container image using the URL you use to deploy your service.
 
+External container registries are configured by creating an Akka secret, and then configuring your Akka project to use that secret as docker registry credentials. The secret, and project configuration, are both managed by the `akka docker` command.
+
 There are four parameters you need to specify, depending on the registry you want to connect to:
 
 - Server: The first part of the container image URL. For example, if your image is at `us.gcr.io/my-project/my-image`, the server is `\https://us.gcr.io` (_mandatory_).
@@ -28,6 +30,12 @@ akka docker add-credentials --docker-server <my-server> \ <1>
 <3> Email
 <4> Password
 
+If you wish to specify the name of the secret that you want to use, that can be done using the `--secret-name` parameter. By default, if not specified, the name of the secret will be `docker-credentials`.
+
+== Updating credentials
+
+The `add-credentials` command can also be used to update existing credentials. Simply ensure that the `--secret-name` argument matches the secret name used when the credentials were added, if it was specified then.
+
 == Listing credentials
 
 To list all container registry credentials for your Akka project, you can use the Akka CLI or the Akka Console. For security purposes, neither the CLI nor the Console will show the password of the configured registry.
@@ -42,19 +50,26 @@ akka docker list-credentials
 The results should look something like:
 
 ----
-ID                                     SERVER              USERNAME    EMAIL
-xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx   https://us.gcr.io   _json_key   user@example.com
+NAME                STATUS  SERVER             EMAIL             USERNAME
+docker-credentials  OK      https://us.gcr.io  user@example.com  _json_key
 ----
 
 == Removing credentials
 
 To remove container registry credentials from your Akka project, you can use the Akka CLI or the Akka Console.
 
-Use the 'ID' returned from the `akka docker list-credentials` command as the `ID` in the `akka docker delete-credentials` command:
+If you specified a `--secret-name` when creating the credentials, this is the name that you must pass to the command to remove. Otherwise, you should pass the default secret name of `docker-credentials`. The name of the secret appears in the `NAME` column when listing credentials.
+
+[source, command line]
+----
+akka docker delete-credentials docker-credentials
+----
+
+Note that this will only remove the credentials from the configuration for the project, it will not delete the underlying secret. To delete the secret as well, run:
 
 [source, command line]
 ----
-akka docker delete-credentials <credentials-id>
+akka secrets delete docker-credentials
 ----
 
 == Supported external registries

docs/src/modules/operations/pages/projects/manage-project-access.adoc

@@ -59,7 +59,7 @@ akka config set project <project name>
 
 You can grant a project role to a user in two ways:
 
-==== 1. Invite a user to the project by e-mail
+=== 1. Invite a user to the project by e-mail
 Invite a user to join the project and assign them a role by using the following command:
 
 [source,command window]
@@ -69,7 +69,7 @@ akka roles invitations invite-user <email address> --role <role>
 
 The user will receive an email inviting them to join the project. Upon acceptance, the role binding will be created.
 
-==== 2. Add a role directly
+=== 2. Add a role directly
 If the user is already a member of the project, or the project is part of an organization and the user belongs to that organization, you can assign roles directly without sending an invitation.
 
 * By e-mail:

docs/src/modules/reference/pages/cli/akka-cli/akka.adoc

@@ -26,21 +26,21 @@ Welcome to the Akka CLI, for more information on its usage please visit the docu
 
 * link:akka_auth.html[akka auth]	 - Manage Akka authentication.
 * link:akka_completion.html[akka completion]	 - Generate shell completion scripts
-* link:akka_config.html[akka config]	 - Manage the local Akka configuration.
-* link:akka_container-registry.html[akka container-registry]	 - Manage the Akka Container Registry.
-* link:akka_docker.html[akka docker]	 - Manage Docker credentials for Akka projects.
-* link:akka_docs.html[akka docs]	 - Opens the Akka documentation page
-* link:akka_local.html[akka local]	 - Helps with local development.
+* link:akka_config.html[akka config]	 - Manage configuration and context for the Akka CLI.
+* link:akka_container-registry.html[akka container-registry]	 - Manage and push service images to the Akka Container Registry.
+* link:akka_docker.html[akka docker]	 - Manage credentials for projects using private Docker registries.
+* link:akka_docs.html[akka docs]	 - Open the Akka documentation page
+* link:akka_local.html[akka local]	 - Interact with and manage Akka services running locally.
 * link:akka_logs.html[akka logs]	 - Display the last few lines of logs for a specific service.
 * link:akka_organizations.html[akka organizations]	 - Manage your organizations on Akka
 * link:akka_projects.html[akka projects]	 - Manage your Akka projects.
 * link:akka_quickstart.html[akka quickstart]	 - Akka quickstart project samples.
-* link:akka_regions.html[akka regions]	 - Manage regions on Akka
+* link:akka_regions.html[akka regions]	 - Manage available regions.
 * link:akka_roles.html[akka roles]	 - Manage the user roles for an Akka project.
 * link:akka_routes.html[akka routes]	 - Manage routes for your Akka project.
 * link:akka_secrets.html[akka secrets]	 - Manage secrets for an Akka project.
 * link:akka_services.html[akka services]	 - Manage and deploy services on Akka.
-* link:akka_version.html[akka version]	 - Prints the akka version
+* link:akka_version.html[akka version]	 - Print the akka CLI version
 
 [discrete]
 

docs/src/modules/reference/pages/cli/akka-cli/akka_auth.adoc

@@ -31,12 +31,12 @@ When authorized, you can use the CLI to perform the same operations available in
 == SEE ALSO
 
 * link:akka.html[akka]	 - Akka control
-* link:akka_auth_container-registry.html[akka auth container-registry]	 - Manage the Akka Container Registry configuration.
+* link:akka_auth_container-registry.html[akka auth container-registry]	 - Manage configuration for Akka Container Registry.
 * link:akka_auth_current-login.html[akka auth current-login]	 - Get details for the current logged in user.
 * link:akka_auth_login.html[akka auth login]	 - Log in to Akka.
 * link:akka_auth_logout.html[akka auth logout]	 - Log out the current user.
-* link:akka_auth_signup.html[akka auth signup]	 - Opens the registration page.
-* link:akka_auth_tokens.html[akka auth tokens]	 - Manage Akka authentication tokens.
+* link:akka_auth_signup.html[akka auth signup]	 - Open the registration page.
+* link:akka_auth_tokens.html[akka auth tokens]	 - Manage Akka authentication tokens for your user.
 * link:akka_auth_use-token.html[akka auth use-token]	 - Login using a token.
 
 [discrete]

docs/src/modules/reference/pages/cli/akka-cli/akka_auth_container-registry.adoc

@@ -1,10 +1,14 @@
 = akka auth container-registry
 
-Manage the Akka Container Registry configuration.
+Manage configuration for Akka Container Registry.
 
 == Synopsis
 
-The Akka Container Registry (ACR) can be used by all Akka users to deploy services and is available in all Akka regions.
+The Akka Container Registry (ACR) can be used by all users to deploy their services.
+ACR uses an access token generated via Akka for authentication.
+This command allows you to configure the Docker credential helper for ACR.
+
+NOTE: to use this command, the current user must be logged into Akka and Docker must be installed and accessible for the current user.
 
 == Options
 
@@ -32,8 +36,8 @@ The Akka Container Registry (ACR) can be used by all Akka users to deploy servic
 * link:akka_auth.html[akka auth]	 - Manage Akka authentication.
 * link:akka_auth_container-registry_clear-cached-token.html[akka auth container-registry clear-cached-token]	 - Clear the cached Akka Container Registry access token.
 * link:akka_auth_container-registry_configure.html[akka auth container-registry configure]	 - Configure the Akka Container Registry docker credential helper.
-* link:akka_auth_container-registry_credentials.html[akka auth container-registry credentials]	 - Retrieves an Akka Container Registry access token for the current user.
-* link:akka_auth_container-registry_install-helper.html[akka auth container-registry install-helper]	 - Installs the Akka Docker credential helper in the selected directory.
+* link:akka_auth_container-registry_credentials.html[akka auth container-registry credentials]	 - Retrieve an Akka Container Registry access token for the current user.
+* link:akka_auth_container-registry_install-helper.html[akka auth container-registry install-helper]	 - Install the Akka Docker credential helper in the selected directory.
 
 [discrete]
 

docs/src/modules/reference/pages/cli/akka-cli/akka_auth_container-registry_clear-cached-token.adoc

@@ -31,7 +31,7 @@ akka auth container-registry clear-cached-token [flags]
 
 == SEE ALSO
 
-* link:akka_auth_container-registry.html[akka auth container-registry]	 - Manage the Akka Container Registry configuration.
+* link:akka_auth_container-registry.html[akka auth container-registry]	 - Manage configuration for Akka Container Registry.
 
 [discrete]
 

docs/src/modules/reference/pages/cli/akka-cli/akka_auth_container-registry_configure.adoc

@@ -33,7 +33,7 @@ akka auth container-registry configure [flags]
 
 == SEE ALSO
 
-* link:akka_auth_container-registry.html[akka auth container-registry]	 - Manage the Akka Container Registry configuration.
+* link:akka_auth_container-registry.html[akka auth container-registry]	 - Manage configuration for Akka Container Registry.
 
 [discrete]
 

docs/src/modules/reference/pages/cli/akka-cli/akka_auth_container-registry_credentials.adoc

@@ -1,6 +1,6 @@
 = akka auth container-registry credentials
 
-Retrieves an Akka Container Registry access token for the current user.
+Retrieve an Akka Container Registry access token for the current user.
 
 ----
 akka auth container-registry credentials [flags]
@@ -32,7 +32,7 @@ akka auth container-registry credentials [flags]
 
 == SEE ALSO
 
-* link:akka_auth_container-registry.html[akka auth container-registry]	 - Manage the Akka Container Registry configuration.
+* link:akka_auth_container-registry.html[akka auth container-registry]	 - Manage configuration for Akka Container Registry.
 
 [discrete]
 

docs/src/modules/reference/pages/cli/akka-cli/akka_auth_container-registry_install-helper.adoc

@@ -1,6 +1,6 @@
 = akka auth container-registry install-helper
 
-Installs the Akka Docker credential helper in the selected directory.
+Install the Akka Docker credential helper in the selected directory.
 
 == Synopsis
 
@@ -33,7 +33,7 @@ akka auth container-registry install-helper [flags]
 
 == SEE ALSO
 
-* link:akka_auth_container-registry.html[akka auth container-registry]	 - Manage the Akka Container Registry configuration.
+* link:akka_auth_container-registry.html[akka auth container-registry]	 - Manage configuration for Akka Container Registry.
 
 [discrete]
 

docs/src/modules/reference/pages/cli/akka-cli/akka_auth_signup.adoc

@@ -1,6 +1,6 @@
 = akka auth signup
 
-Opens the registration page.
+Open the registration page.
 
 ----
 akka auth signup [flags]

docs/src/modules/reference/pages/cli/akka-cli/akka_auth_tokens.adoc

@@ -1,6 +1,10 @@
 = akka auth tokens
 
-Manage Akka authentication tokens.
+Manage Akka authentication tokens for your user.
+
+== Synopsis
+
+The command `akka auth tokens`  manage the authentication tokens for your user allowing you to revoke any token at any time, but also to create new tokens for use in CI/CD pipelines for machine-user accounts.
 
 == Options
 

docs/src/modules/reference/pages/cli/akka-cli/akka_auth_tokens_create.adoc

@@ -43,7 +43,7 @@ Token created: 0123456789abcdef0123456789abcdef0123456789abcdef
 
 == SEE ALSO
 
-* link:akka_auth_tokens.html[akka auth tokens]	 - Manage Akka authentication tokens.
+* link:akka_auth_tokens.html[akka auth tokens]	 - Manage Akka authentication tokens for your user.
 
 [discrete]
 

docs/src/modules/reference/pages/cli/akka-cli/akka_auth_tokens_list.adoc

@@ -35,7 +35,7 @@ akka auth tokens list [flags]
 
 == SEE ALSO
 
-* link:akka_auth_tokens.html[akka auth tokens]	 - Manage Akka authentication tokens.
+* link:akka_auth_tokens.html[akka auth tokens]	 - Manage Akka authentication tokens for your user.
 
 [discrete]
 

docs/src/modules/reference/pages/cli/akka-cli/akka_auth_tokens_revoke.adoc

@@ -37,7 +37,7 @@ akka auth tokens revoke ID [flags]
 
 == SEE ALSO
 
-* link:akka_auth_tokens.html[akka auth tokens]	 - Manage Akka authentication tokens.
+* link:akka_auth_tokens.html[akka auth tokens]	 - Manage Akka authentication tokens for your user.
 
 [discrete]