From 8d6f4b692222498a2957ca0ef144a8feadb29d15 Mon Sep 17 00:00:00 2001
From: Yoann Schneider <yschneider@teklia.com>
Date: Tue, 23 Jan 2024 10:50:40 +0000
Subject: [PATCH] Document worker publication
---
docs/contents/workers/publication.md | 29 ++++++++++++++++++++++++++++
mkdocs.yml | 1 +
2 files changed, 30 insertions(+)
create mode 100644 docs/contents/workers/publication.md
diff --git a/docs/contents/workers/publication.md b/docs/contents/workers/publication.md
new file mode 100644
index 00000000..2d2a982d
--- /dev/null
+++ b/docs/contents/workers/publication.md
@@ -0,0 +1,29 @@
+# Publishing your worker on Arkindex
+
+## Publication process
+
+While workers may be [run locally](./run-local.md), they are usually written to launch on an Arkindex instance. A worker version on Arkindex is basically a configuration and an URL towards a Docker image, used at runtime during processes. The worker [template](./template-structure.md) includes an automatic publication process towards any Arkindex instance.
+
+## How it works
+
+The template implements a new CI job, `publish-worker`, at the last stage of the pipeline. When every job of the previous stages have passed, this one will try to publish a new worker version, using the newly built Docker image, on every Arkindex instance specified by the `ARKINDEX_INSTANCE` variable. The publication is done using the [Arkindex CLI tool](<https://cli.arkindex.org/workers/#publish-workers>).
+
+!!! warning
+
+ If you change the `docker_image_tag` positional argument value, it might not be in sync with the tag produced during the `docker-build` job. Make sure these match to link the version with the right Docker image.
+
+!!! note
+
+ If your repository defines multiple workers, one worker version will be pushed per worker. However, there will still only be one job per instance.
+
+
+## Authentication in CI
+
+Since the publication is done during a GitLab CI, no optional arguments are [needed](<https://cli.arkindex.org/workers/#running-the-command-in-a-gitlab-ci-pipeline>). There are multiple ways to authenticate to an Arkindex instance when using the CLI tool. During a GitLab CI, the best way is through a [Project-level Secure File](<https://docs.gitlab.com/ee/ci/secure_files/>). Make sure to create one that follows the format [supported by the CLI](<https://cli.arkindex.org/login/#gitlab-secure-file>). The template expects that secure file to be named `arkindex-cli.yaml`.
+
+## Specifying another instance
+
+In the template, a publication to <https://demo.arkindex.org> (slug `demo`) is presented. To publish to another instance, make sure that:
+
+- the authentication credentials for that instance are present in the secure file,
+- the slug is listed as a potential value for `ARKINDEX_INSTANCE` in the `publish-worker` job configuration.
diff --git a/mkdocs.yml b/mkdocs.yml
index 324af634..6180b8cd 100644
--- a/mkdocs.yml
+++ b/mkdocs.yml
@@ -64,6 +64,7 @@ nav:
- contents/workers/index.md
- Setting up a new worker: contents/workers/create.md
- Running your worker locally: contents/workers/run-local.md
+ - Publishing your worker on Arkindex: contents/workers/publication.md
- Maintaining a worker: contents/workers/maintenance.md
- GitLab CI for workers: contents/workers/ci/index.md
- YAML configuration: contents/workers/yaml.md
--
GitLab