From 928dea568016d24f2265d9a38a1a6b4777191334 Mon Sep 17 00:00:00 2001 From: Wesley Ferreira Date: Sat, 12 Sep 2026 22:19:40 +0000 Subject: [PATCH 001/188] docs: align onboarding narrative and API conventions --- .github/workflows/docs-checks.yaml | 8 +++ docs/docs/concepts.md | 48 +++++---------- docs/docs/contributing/documentation-plan.md | 30 ++++++--- docs/docs/getting-started.md | 61 ++++++------------- docs/docs/guides/data/artifacts.md | 50 +++++++-------- docs/docs/guides/data/provenance-and-audit.md | 30 ++++----- .../guides/infrastructure/cloud-capacity.md | 40 ++++++------ .../guides/infrastructure/environments.md | 32 +++++----- .../guides/infrastructure/execution-scopes.md | 20 +++--- docs/docs/guides/infrastructure/gcp.md | 4 +- docs/docs/guides/infrastructure/hpc-slurm.md | 6 +- docs/docs/guides/infrastructure/kubernetes.md | 2 +- docs/docs/guides/infrastructure/simgrid.md | 2 +- docs/docs/guides/infrastructure/storage.md | 34 ++++++----- docs/docs/guides/interface-tour.mdx | 2 +- .../guides/operations/credentials-and-ssh.md | 32 +++++----- .../guides/operations/instance-management.md | 48 +++++++-------- .../guides/operations/interactive-console.md | 38 ++++++------ .../operations/search-and-notifications.md | 30 ++++----- .../docs/guides/operations/troubleshooting.md | 42 ++++++------- docs/docs/guides/workflows/definitions.md | 4 +- docs/docs/guides/workflows/executions.md | 2 + docs/docs/guides/workflows/first-run.md | 8 +-- docs/docs/guides/workflows/planning.md | 2 + docs/docs/modules.md | 4 +- docs/docs/reference/api-overview.md | 20 +++--- docs/docs/reference/environment-yaml.md | 2 +- .../execution-scopes-and-topologies.md | 2 +- docs/docs/runtimes.md | 2 +- docs/docs/showcase/edge-cloud-simulation.mdx | 12 ++-- docs/docs/showcase/index.mdx | 22 +++---- .../showcase/kubernetes-real-execution.mdx | 22 +++---- docs/docs/showcase/local-direct-execution.mdx | 14 ++--- docs/docs/showcase/network-fanout.mdx | 14 ++--- docs/docs/showcase/parallel-50-core.mdx | 14 ++--- docs/docs/showcase/slurm-local-fixture.mdx | 17 +++--- docs/docusaurus.config.ts | 2 +- docs/quality-plan.md | 14 +++-- docs/scripts/check-links.mjs | 12 +++- docs/scripts/generate-api-reference.mjs | 12 ++-- docs/sidebars.ts | 12 ++-- docs/src/components/ApiEndpoint.tsx | 19 ++++-- docs/src/pages/index.tsx | 7 ++- 43 files changed, 409 insertions(+), 389 deletions(-) diff --git a/.github/workflows/docs-checks.yaml b/.github/workflows/docs-checks.yaml index 91ab10fc..24686d61 100644 --- a/.github/workflows/docs-checks.yaml +++ b/.github/workflows/docs-checks.yaml @@ -5,12 +5,18 @@ on: paths: - "docs/**" - "examples/**" + - "internal/api/**" + - "internal/domain/**" + - "internal/provider/**" - ".github/workflows/docs-checks.yaml" push: branches: [main] paths: - "docs/**" - "examples/**" + - "internal/api/**" + - "internal/domain/**" + - "internal/provider/**" - ".github/workflows/docs-checks.yaml" permissions: @@ -28,6 +34,8 @@ jobs: runs-on: ubuntu-latest steps: - uses: actions/checkout@v4 + with: + fetch-depth: 0 - uses: actions/setup-node@v4 with: node-version: 20 diff --git a/docs/docs/concepts.md b/docs/docs/concepts.md index 824be749..a19a4736 100644 --- a/docs/docs/concepts.md +++ b/docs/docs/concepts.md @@ -1,50 +1,30 @@ --- id: concepts -title: System architecture -sidebar_label: System architecture -description: How AkôFlow keeps infrastructure, workflow intent, planning decisions, and execution evidence separate. +title: Core concepts +sidebar_label: Core concepts +description: Understand workflows, environments, plans, runs, artifacts, and provenance in AkôFlow. --- import useBaseUrl from '@docusaurus/useBaseUrl'; -AkôFlow is a control plane for scientific workflows. It keeps the description of the available infrastructure separate from the workflow definition, the scheduling decision, and the evidence produced by an execution. That separation lets the same immutable workflow version be compared on different infrastructure scopes without rewriting the workflow. +AkôFlow keeps the workflow you define, the resources available to it, the plan you choose, and the result you observe as separate records. That lets you try a different plan without rewriting the workflow. -This is an explanation of the records and their boundaries. For the exact YAML fields, use the [workflow specification](./internal/workflow-spec) and the [environment reference](./reference/environment-yaml). For an end-to-end task, start with [the first simulated workflow](./guides/workflows/first-run). +## From workflow to result -AkôFlow control-plane architecture: Desktop and API clients call the daemon; its workflow, planning, and execution services preserve scientific evidence in SQLite and dispatch work through SimGrid, Kubernetes, SSH/Slurm, cloud, and local adapters. +A workflow and an environment lead to candidate plans; a selected plan leads to a run, artifacts, and provenance. -*The diagram groups responsibilities rather than deployment units. AkôFlow is one daemon with application services and adapters; the cards do not imply separately deployable microservices.* +A **workflow** is a set of activities with dependencies. For example, `prepare → analyze → summarize` means that analysis waits for preparation and the summary waits for analysis. The workflow describes the work and required data; it does not choose a machine. -## The record chain +An **environment** describes where work could run: a local host, a modeled simulation platform, a Kubernetes cluster, or an HPC system. Its **resources** are the available machines or capacity. An **execution scope** limits which environment versions and network links a planning experiment can use. -Environment definitions become published versions and scopes; immutable workflow versions join planning sessions; selected plans lead to execution runs and observed task, transfer, artifact, provenance and audit records. +A **plan** assigns activities to resources and predicts timing, transfers, and possibly cost. AkôFlow can produce several candidates, or you can supply a manual plan. Selecting one does not start a run; it records the choice you want to execute. -The arrows express references, not a single mutable object. A planning session preserves a snapshot of the workflow, scope, inventory, topology, profiles, constraints, and selected algorithms. A later discovery refresh can create new inventory for future sessions, but it does not change that earlier comparison. +A **run** records what happened when that plan was submitted. It has activity statuses, observed timing, transfers, and output evidence. Compare the run with its plan to see where prediction and observation differ. -## Infrastructure is a versioned boundary +**Artifacts** are the executable inputs or observed files associated with work. **Provenance** links the workflow, plan, run, activities, and data so you can trace how a result was produced. The audit trail records operational actions separately. -An **environment** names an infrastructure boundary: a local host, Kubernetes cluster, SSH/SLURM system, modeled SimGrid platform, or cloud configuration. Its published version can contain runtimes, resources and their hierarchy, runtime bindings, storage, connection observations, and capability observations. +## Where to go next -A **resource** is capacity that may be assigned by a plan. A **runtime** says how an activity is launched and observed. A binding states which runtime may use which resource. The [runtime adapters explanation](./runtimes) describes that boundary in more detail. +Use [Workflow definitions](./guides/workflows/definitions) to create a workflow, [Planning](./guides/workflows/planning) to choose placement, and [Execution](./guides/workflows/executions) to inspect a run. The [SimGrid API tutorial](./guides/workflows/first-run) supplies a complete small example. -An **execution scope** chooses the published environment versions that an algorithm may consider. Its network topology supplies directed links between resources. This means a plan answers a constrained question—"place this workflow on this frozen universe"—rather than a claim about every resource the daemon may ever discover. - -## A workflow describes intent, not placement - -A workflow definition owns identity and namespace. Its immutable version has activities plus control and data dependencies. Activities carry executable and resource requirements and may carry a simulation profile. They do not name a target resource; that is a planning decision. - -Control dependencies establish ordering. Data dependencies identify the producer, consumer, logical data, and byte volume used for movement modeling. In the current portable importer, a data dependency contributes to scheduling only when its producer/consumer pair also has the matching control dependency. This protects the DAG semantics from a data declaration that has no ordering edge. - -## A plan is a prediction and a decision - -A planning session may produce several **candidates**. They are alternatives, not runnable plans in their own right. Selecting a candidate promotes its placement to a canonical **schedule plan** with assignments and predicted ready, start, finish, runtime, transfer, and cost values. Manual and imported plans use the same plan aggregate after validation. - -Planning does not start work. The [planning explanation](./explanations/planning) explains why candidates, objectives, and a selected plan are different records. - -## Execution creates observations - -An **execution run** binds one selected plan to real, simulation, or interactive mode. The supervisor persists task attempts, runtime handles, transfer routes, logs, artifact manifests, and timing. Those records are observations of a run; they do not retroactively alter the plan prediction. - -An executable artifact is immutable runnable input. An artifact manifest is an observed output from an activity. They are deliberately different: an input can be materialized before a task starts, while an output can become a scientific data object only after the activity has been observed. - -Read [execution and control-plane behavior](./engine) for orchestration, [network modeling](./explanations/network-modeling) for movement assumptions, and [evidence and provenance](./explanations/evidence-and-provenance) for the records used to compare a plan with a completed run. +For exact file fields, use the [workflow specification](./internal/workflow-spec) and [environment reference](./reference/environment-yaml). For implementation details, see [Architecture internals](./modules). diff --git a/docs/docs/contributing/documentation-plan.md b/docs/docs/contributing/documentation-plan.md index 1285498f..62b965ec 100644 --- a/docs/docs/contributing/documentation-plan.md +++ b/docs/docs/contributing/documentation-plan.md @@ -7,10 +7,24 @@ description: Source-of-truth, media, and review rules for AkôFlow documentation This plan keeps the documentation aligned with the shipping daemon and Desktop application. It is also the contract for parallel documentation work. +## Editorial contract + +The documentation should show how AkôFlow simplifies scientific workflow execution, not display the complexity of its implementation. + +1. Explain the task and expected result before implementation details. Give each page one main job. +2. Use workflow, environment, plan, run, artifacts, and provenance in user paths. Put supervisors, handlers, adapters, and persistence in developer architecture pages unless a task requires them. +3. Make support claims only when code and appropriate evidence support them. Label partial features and distinguish code review, local fixtures, and real-environment validation. +4. Prefer a concrete example over a list of capabilities. Remove repeated caveats and text that does not help a reader act or decide. +5. Check whether each page quickly answers what it is for, when to use it, how to use it, and what to expect. + +For each editorial pass, classify passages as **KEEP**, **SIMPLIFY**, **MOVE**, **DELETE**, or **VERIFY**. Resolve P0 (false claims and broken instructions), then P1 (confusing paths and misplaced concepts), then P2 (length and repetition), then P3 (presentation). Repeat audit → edit → build → link check → claim check → first-time-reader review until a full pass finds no P0 or P1 issues. A successful build alone is not the finish line. + +The completion gate is a new user running a first workflow without undocumented knowledge, support claims matching implementation and validation, implementation details outside the basic path, and no P0/P1 findings in the final audit. + ## Documentation principles 1. Teach complete user tasks instead of listing screens in isolation. -2. Present **AkôFlow Desktop** and **API** as equivalent paths whenever both exist. +2. Present **AkôFlow Desktop** and **API** paths only where each procedure is documented and verified; state extra prerequisites instead of calling them equivalent by default. 3. Derive behavior from code, tests, and checked-in examples; never infer an endpoint or field from a label alone. 4. Use screenshots to explain spatial relationships and short videos to explain motion or multi-step transitions. 5. Keep a text equivalent for every visual procedure. @@ -20,12 +34,12 @@ This plan keeps the documentation aligned with the shipping daemon and Desktop a | Subject | Primary source | |---|---| -| Desktop navigation | `akoflow-admin/src/App.jsx` and `src/components/AppShell.jsx` | -| Desktop operations | Page, form, and provider components in `akoflow-admin/src` | -| HTTP methods and paths | `akoflow/internal/api/httpserver/httpserver.go` | +| Desktop navigation | `akoflow-desktop/src/App.jsx` and `akoflow-desktop/src/components/AppShell.jsx` in the Desktop repository | +| Desktop operations | Page, form, and provider components in `akoflow-desktop/src` | +| HTTP methods and paths | `internal/api/httpserver/httpserver.go` in this repository | | Request and response contracts | HTTP handlers, application services, and `internal/domain` | -| Runnable scenarios | `akoflow/examples` and integration tests | -| Packaged installation | Root README, `releases/`, Electron bootstrap, and release workflows | +| Runnable scenarios | `examples/` and integration tests in this repository | +| Packaged installation | Root README, `releases/`, the Desktop repository's `electron/` bootstrap, and release workflows | Generated site output and old copied Markdown files are not sources of truth. @@ -115,7 +129,7 @@ Use the black, white, and neutral-gray visual system established by [`akoflow-co ## Definition of done for a guide -- The task has prerequisites, Desktop steps, API steps, expected result, and next steps. +- The task has prerequisites, a verified procedure for its stated interface, an expected result, and next steps. Add a second interface only when its path has been checked. - Screenshot placeholders or final captures cover only moments where the visual adds information. - API examples include authentication and use the current `/akoflow-api` prefix. - Identifiers in examples are visibly placeholders or come from a documented demo dataset. @@ -126,7 +140,7 @@ Use the black, white, and neutral-gray visual system established by [`akoflow-co Run `npm run generate:api` to rebuild the endpoint catalog from `internal/api/httpserver/httpserver.go`. The Docusaurus `prestart` and `prebuild` hooks run this automatically. Generated pages are intentionally ignored by Git; changes to method, path, or handler appear on the next documentation build without copying the router by hand. -Each generated endpoint page includes its HTTP method, registered path, path parameters, authentication example, request-body indication, owning handler, and a copyable cURL command. Domain guides remain responsible for semantic explanations and complete payload examples. +Each generated endpoint page includes its HTTP method, registered path, path parameters, authentication example, request-body indication, owning handler, and a cURL command. Inferred JSON shapes are illustrative, not guaranteed valid payloads. Priority endpoints need authored, handler-checked contracts before their commands can be treated as runnable examples. ## Reproducible media capture diff --git a/docs/docs/getting-started.md b/docs/docs/getting-started.md index 77d5ac4c..32a8f88b 100644 --- a/docs/docs/getting-started.md +++ b/docs/docs/getting-started.md @@ -1,34 +1,33 @@ --- id: getting-started -title: Choose where to start +title: Getting started with AkôFlow sidebar_label: Getting started slug: /getting-started -description: Choose the shortest AkôFlow documentation path for installation, a first run, operations, concepts, or API integration. +description: Understand AkôFlow, choose a supported path, and find the next workflow task. --- -import useBaseUrl from '@docusaurus/useBaseUrl'; +# Getting started with AkôFlow -# Choose where to start +AkôFlow helps you define a scientific workflow, choose where its activities run, compare plans, and inspect the results. A workflow describes activities and their data dependencies. A run records what happened after a plan was selected. -AkôFlow plans and executes scientific workflow DAGs on simulated or connected infrastructure, then preserves the plan, observed execution, data movement, artifacts, audit events, and provenance. This page is a map of the documentation; it does not teach an individual workflow. +Start with a local environment to learn the interface. Connecting HPC, Kubernetes, or cloud resources requires the access and checks in their own guides. -You do not need prior AkôFlow experience. Choose the path that matches what you want to accomplish. +## Start with Desktop -## I want to run AkôFlow for the first time +1. [Install AkôFlow Desktop](./installation) and complete its local environment checkup. +2. [Tour the interface](./guides/interface-tour) to find workflows, plans, runs, and results. +3. Use [Workflow definitions](./guides/workflows/definitions), [Planning](./guides/workflows/planning), and [Execution](./guides/workflows/executions) for the next tasks. -1. [Install AkôFlow](./installation) and verify that its daemon is available. -2. [Run the first simulated workflow](./guides/workflows/first-run). The tutorial uses checked-in files, requires no cluster or cloud account, and ends with concrete activity and transfer checks. -3. Use the [interface tour](./guides/interface-tour) when you want to learn where the same records appear in Desktop. +The [checked-in SimGrid example](./guides/workflows/first-run) verifies three activities and two transfers. It uses a separately managed API endpoint, Bash tools, and versioned repository files. It is not a Desktop-only first-run tutorial. -Start with the simulation even if your eventual target is Kubernetes or HPC. It separates installation problems from credentials, network access, scheduler policy, and remote storage. +## Connect another environment -## Continue after installation +- [Register HPC / SLURM](./tutorials/register-hpc) after receiving site-approved SSH and scheduler access. +- [Connect Google Cloud](./tutorials/connect-cloud) with a service account and a project you can inspect. +- [Configure Kubernetes](./guides/infrastructure/kubernetes) when you have cluster access. +- [Review cloud support](./guides/infrastructure/cloud-capacity#provider-support-in-v10) before planning a cloud run. AWS EC2 discovery and provisioning are not implemented. -Follow [installation result checks](./installation#4-installation-result), then -[register HPC / SLURM](./tutorials/register-hpc) or -[connect Google Cloud](./tutorials/connect-cloud). Each tutorial includes the -actual connection form, an API path, and expected results. For automation, start -with [API connection setup](./tutorials/api-access). +For direct API work, complete [API connection setup](./tutorials/api-access) first. ## I already have AkôFlow running @@ -42,33 +41,9 @@ with [API connection setup](./tutorials/api-access). | Reproduce a complete example | [Workflow Showcase](./showcase/) | | Query lineage, evidence, or audit records | [Provenance and audit](./guides/data/provenance-and-audit) | -## I am connecting infrastructure +## Understand the records -Choose the guide for the actual target. Provider and runtime support are not interchangeable. - -- [SimGrid first run](./guides/workflows/first-run): deterministic local simulation. -- [Kubernetes real execution](./showcase/kubernetes-real-execution): container execution on the checked-in Kind example. -- [HPC and SLURM](./guides/infrastructure/hpc-slurm): login nodes, partitions, shared storage, SSH proxies, and batch execution. -- [Google Cloud](./guides/infrastructure/gcp): service-account credentials, catalog discovery, pricing, and Terraform provisioning. -- [AWS](./guides/infrastructure/aws): S3 and S3-compatible data movement. AkôFlow v1.0 does not discover or provision EC2 capacity. - -Review the [cloud support matrix](./guides/infrastructure/cloud-capacity#provider-support-in-v10) before designing a cloud deployment. - -## I am automating through the API - -Read the [API overview](./reference/api-overview) for the base URL, authentication, content types, asynchronous operations, error envelope, and generated endpoint index. Use the [workflow specification](./internal/workflow-spec) for portable YAML authoring. - -The Desktop and HTTP API operate on the same persisted records. The API is preferable for repeatable experiments and integrations; Desktop is preferable for inspecting infrastructure, candidate Gantt charts, live activity state, and plan-versus-observed evidence. - -## I need to understand the model first - -Read [Core concepts](./concepts) for the vocabulary and record relationships. Continue to [Engine](./engine) for control-plane behavior and [Runtimes](./runtimes) for execution-provider boundaries. - -The central lifecycle is shown below. - -AkôFlow lifecycle: an infrastructure boundary and workflow version produce candidate plans; one selected plan produces an execution run and observed evidence. - -A plan is not an execution. It predicts an assignment within a frozen workflow and infrastructure boundary. A run records what happened when that plan was dispatched. +Read [Core concepts](./concepts) for workflow, environment, plan, run, artifacts, and provenance. For implementation details, see [Architecture internals](./modules). The [API overview](./reference/api-overview) and [workflow specification](./internal/workflow-spec) are reference material for automation. ## When something fails diff --git a/docs/docs/guides/data/artifacts.md b/docs/docs/guides/data/artifacts.md index e9bd7ebe..e3c4e0fa 100644 --- a/docs/docs/guides/data/artifacts.md +++ b/docs/docs/guides/data/artifacts.md @@ -1,14 +1,16 @@ --- -title: Artifacts, storage, and builds +title: Manage artifacts, storage, and builds description: Browse data, register executable artifacts, and follow materialization and build runs in Desktop or through the API. --- -# Artifacts, storage, and builds +# Manage artifacts, storage, and builds AkôFlow separates **scientific data** from **executable artifacts**. Files produced by a workflow can be promoted to the scientific record. Executable artifacts are immutable, versioned definitions whose bytes may have verified locations or be materialized on a target resource. The Desktop is the easiest way to perform these operations. Every view described below uses the same HTTP API, so the API examples are suitable for scripts and integrations. +For the API commands on this page, complete [API connection setup](../../tutorials/api-access) first. + ## Browse storage In Desktop, open **Infrastructure**, select an environment, then open **Storage**. Choose a storage card and one of its declared roots. Entries are loaded lazily; opening this view does not scan an entire filesystem. @@ -18,13 +20,13 @@ The actions offered for an entry depend on the storage capabilities reported by List the storage resources for an environment and browse a directory: ```bash -curl -H "Authorization: Bearer $AKOFLOW_TOKEN" \ - "$AKOFLOW_URL/akoflow-api/environments/$ENVIRONMENT_ID/storages/" +curl -H "Authorization: Bearer $AKOFLOW_API_TOKEN" \ + "$AKOFLOW_API_URL/environments/$ENVIRONMENT_ID/storages/" -curl -G -H "Authorization: Bearer $AKOFLOW_TOKEN" \ +curl -G -H "Authorization: Bearer $AKOFLOW_API_TOKEN" \ --data-urlencode "path=/shared/project" \ --data-urlencode "limit=100" \ - "$AKOFLOW_URL/akoflow-api/storages/$STORAGE_ID/entries/" + "$AKOFLOW_API_URL/storages/$STORAGE_ID/entries/" ``` Use the returned `nextCursor` as `cursor` to continue when the response is paginated. Paths are interpreted within a root allowed by the storage adapter; do not assume host filesystem semantics. @@ -32,15 +34,15 @@ Use the returned `nextCursor` as `cursor` to continue when the response is pagin Calculate a digest or queue a copy: ```bash -curl -X POST -H "Authorization: Bearer $AKOFLOW_TOKEN" \ +curl -X POST -H "Authorization: Bearer $AKOFLOW_API_TOKEN" \ -H "Content-Type: application/json" \ -d '{"path":"/shared/project/result.csv"}' \ - "$AKOFLOW_URL/akoflow-api/storages/$STORAGE_ID/checksum/" + "$AKOFLOW_API_URL/storages/$STORAGE_ID/checksum/" -curl -X POST -H "Authorization: Bearer $AKOFLOW_TOKEN" \ +curl -X POST -H "Authorization: Bearer $AKOFLOW_API_TOKEN" \ -H "Content-Type: application/json" \ -d '{"path":"/shared/project/result.csv","destinationStorageId":"storage-archive"}' \ - "$AKOFLOW_URL/akoflow-api/storages/$STORAGE_ID/copies/" + "$AKOFLOW_API_URL/storages/$STORAGE_ID/copies/" ``` Copy and archive operations return `202 Accepted`. Download creation returns a run that can be polled at `/storage-downloads/{downloadId}/`; fetch completed content from `/storage-downloads/{downloadId}/content/`. @@ -52,7 +54,7 @@ Use the entry menu in **Storage** to promote an existing file. **Promote data** The minimal API calls are: ```bash -curl -X POST -H "Authorization: Bearer $AKOFLOW_TOKEN" \ +curl -X POST -H "Authorization: Bearer $AKOFLOW_API_TOKEN" \ -H "Content-Type: application/json" \ -d '{ "path":"/shared/project/result.csv", @@ -60,9 +62,9 @@ curl -X POST -H "Authorization: Bearer $AKOFLOW_TOKEN" \ "runId":"run-1", "activityId":"analyse" }' \ - "$AKOFLOW_URL/akoflow-api/storages/$STORAGE_ID/promote-data/" + "$AKOFLOW_API_URL/storages/$STORAGE_ID/promote-data/" -curl -X POST -H "Authorization: Bearer $AKOFLOW_TOKEN" \ +curl -X POST -H "Authorization: Bearer $AKOFLOW_API_TOKEN" \ -H "Content-Type: application/json" \ -d '{ "path":"/shared/bin/model.sif", @@ -71,7 +73,7 @@ curl -X POST -H "Authorization: Bearer $AKOFLOW_TOKEN" \ "scope":"project", "scopeId":"project-1" }' \ - "$AKOFLOW_URL/akoflow-api/storages/$STORAGE_ID/promote-artifact/" + "$AKOFLOW_API_URL/storages/$STORAGE_ID/promote-artifact/" ``` If `id` is omitted, the server generates one. Supply meaningful provenance identifiers when promoting scientific data; an anonymous promotion is valid at the transport layer but loses useful context. @@ -84,7 +86,7 @@ The equivalent two-call API flow is: ```bash REGISTERED=$(curl -sS -X POST \ - -H "Authorization: Bearer $AKOFLOW_TOKEN" \ + -H "Authorization: Bearer $AKOFLOW_API_TOKEN" \ -H "Content-Type: application/json" \ -d '{ "artifactId":"busybox", @@ -92,11 +94,11 @@ REGISTERED=$(curl -sS -X POST \ "image":"docker.io/library/busybox:1.36", "architecture":"amd64" }' \ - "$AKOFLOW_URL/akoflow-api/artifacts/docker/") + "$AKOFLOW_API_URL/artifacts/docker/") # Read .build.id from REGISTERED, then start it: -curl -X POST -H "Authorization: Bearer $AKOFLOW_TOKEN" \ - "$AKOFLOW_URL/akoflow-api/artifact-builds/$BUILD_ID/runs/" +curl -X POST -H "Authorization: Bearer $AKOFLOW_API_TOKEN" \ + "$AKOFLOW_API_URL/artifact-builds/$BUILD_ID/runs/" ``` The Docker registry pull and SIF conversion run in the build service, not in the browser. Poll `/build-runs/{runId}/`. When complete, `/build-runs/{runId}/output/` streams the SIF file. @@ -104,9 +106,9 @@ The Docker registry pull and SIF conversion run in the build service, not in the For custom recipes, first upload a build context as multipart form data: ```bash -curl -X POST -H "Authorization: Bearer $AKOFLOW_TOKEN" \ +curl -X POST -H "Authorization: Bearer $AKOFLOW_API_TOKEN" \ -F "context=@context.tar.gz" \ - "$AKOFLOW_URL/akoflow-api/build-contexts/" + "$AKOFLOW_API_URL/build-contexts/" ``` Then create an immutable build specification at `/artifact-builds/`. It requires `id`, `artifactVersionId`, `contextDigest`, `recipeDigest`, and `cacheKey`; target and recipe fields describe the desired output. A repeated cache key returns the existing build rather than creating a duplicate. The JSON form of `/build-contexts/` only records metadata for bytes already present in the artifact store and requires `digest`, `storageUri`, and a positive `sizeBytes`. @@ -118,12 +120,12 @@ Use **Artifacts** to see executable versions, **Artifact locations** to see veri A materialization identifies a variant and digest, target resource and destination path, plus its lifecycle status: `planned`, `reconciling`, `transferring`, `verifying`, `committed`, or `failed`. A materialization is considered committed only when `verifiedDigest` equals the requested `digest`. ```bash -curl -H "Authorization: Bearer $AKOFLOW_TOKEN" \ - "$AKOFLOW_URL/akoflow-api/artifact-locations/" +curl -H "Authorization: Bearer $AKOFLOW_API_TOKEN" \ + "$AKOFLOW_API_URL/artifact-locations/" -curl -G -H "Authorization: Bearer $AKOFLOW_TOKEN" \ +curl -G -H "Authorization: Bearer $AKOFLOW_API_TOKEN" \ --data-urlencode "runId=$RUN_ID" \ - "$AKOFLOW_URL/akoflow-api/artifact-materializations/" + "$AKOFLOW_API_URL/artifact-materializations/" ``` Execution detail also shows prepared artifacts and transfer activity. Use it to relate catalog identity to the bytes actually made available for an activity. diff --git a/docs/docs/guides/data/provenance-and-audit.md b/docs/docs/guides/data/provenance-and-audit.md index 512e92af..a448d3af 100644 --- a/docs/docs/guides/data/provenance-and-audit.md +++ b/docs/docs/guides/data/provenance-and-audit.md @@ -1,9 +1,9 @@ --- -title: Provenance and audit +title: Inspect provenance and audit events description: Explore scientific lineage, run safe read-only SQL, and inspect the operational audit trail. --- -# Provenance and audit +# Inspect provenance and audit events AkôFlow exposes two complementary records: @@ -12,6 +12,8 @@ AkôFlow exposes two complementary records: Use provenance to answer “how was this result produced?” Use audit to answer “what operation happened, when, to which target, and with what outcome?” +For the API commands on this page, complete [API connection setup](../../tutorials/api-access) first. + ## Explore provenance in Desktop Open **Provenance**. The **Explore** tab loads a server-defined entity catalog. Select an entity, search across its safe projection, apply a field filter, sort a column, and page through the result. The current page can be exported as CSV or JSON. @@ -23,10 +25,10 @@ Open **Provenance**. The **Explore** tab loads a server-defined entity catalog. The API exposes the same server-defined catalog and query: ```bash -curl -H "Authorization: Bearer $AKOFLOW_TOKEN" \ - "$AKOFLOW_URL/akoflow-api/provenance/entities/" +curl -H "Authorization: Bearer $AKOFLOW_API_TOKEN" \ + "$AKOFLOW_API_URL/provenance/entities/" -curl -G -H "Authorization: Bearer $AKOFLOW_TOKEN" \ +curl -G -H "Authorization: Bearer $AKOFLOW_API_TOKEN" \ --data-urlencode "q=completed" \ --data-urlencode "filterField=status" \ --data-urlencode "filterValue=completed" \ @@ -34,7 +36,7 @@ curl -G -H "Authorization: Bearer $AKOFLOW_TOKEN" \ --data-urlencode "pageSize=50" \ --data-urlencode "sortField=created_at" \ --data-urlencode "sortOrder=desc" \ - "$AKOFLOW_URL/akoflow-api/provenance/entities/runs/" + "$AKOFLOW_API_URL/provenance/entities/runs/" ``` Entity names and fields are supplied by `/provenance/entities/`; clients should not invent them. Query responses include entity metadata, `items`, `page`, `pageSize`, `total`, and `hasNext`. @@ -59,11 +61,11 @@ From an Explore result, choose **Open lineage**, or open the **Lineage** tab and | **Export JSON** | Preserve the exact lineage response for an investigation or a report. | The export is a snapshot of the current root, direction, and depth; record those choices with the file. | ```bash -curl -G -H "Authorization: Bearer $AKOFLOW_TOKEN" \ +curl -G -H "Authorization: Bearer $AKOFLOW_API_TOKEN" \ --data-urlencode "direction=both" \ --data-urlencode "depth=2" \ --data-urlencode "maxNodes=300" \ - "$AKOFLOW_URL/akoflow-api/provenance/lineage/runs/$RUN_ID/" + "$AKOFLOW_API_URL/provenance/lineage/runs/$RUN_ID/" ``` The response contains a `root` key, `nodes`, directed `edges`, and `truncated`. Increase depth deliberately: the graph may expand quickly, and the interface caps a request at 300 nodes. @@ -91,10 +93,10 @@ The **SQL** tab presents the queryable schema, templates for common investigatio Only read-only `SELECT` and `WITH` queries are accepted. The Desktop communicates the current service limits as a 10-second execution timeout and 200 rows per page. Fetch the runtime schema instead of assuming table or column names: ```bash -curl -H "Authorization: Bearer $AKOFLOW_TOKEN" \ - "$AKOFLOW_URL/akoflow-api/provenance/sql/schema/" +curl -H "Authorization: Bearer $AKOFLOW_API_TOKEN" \ + "$AKOFLOW_API_URL/provenance/sql/schema/" -curl -X POST -H "Authorization: Bearer $AKOFLOW_TOKEN" \ +curl -X POST -H "Authorization: Bearer $AKOFLOW_API_TOKEN" \ -H "Content-Type: application/json" \ -d '{ "sql":"SELECT id, status, created_at FROM execution_runs WHERE status = :status ORDER BY created_at DESC", @@ -102,7 +104,7 @@ curl -X POST -H "Authorization: Bearer $AKOFLOW_TOKEN" \ "page":1, "pageSize":200 }' \ - "$AKOFLOW_URL/akoflow-api/provenance/sql/" + "$AKOFLOW_API_URL/provenance/sql/" ``` Send the same payload to `/provenance/sql/explain/` to inspect the query plan without running the ordinary result path. SQL results contain typed `columns`, `items`, pagination information, a `truncated` flag, and elapsed milliseconds. @@ -133,11 +135,11 @@ Open **Audit** for a chronological record of infrastructure discovery, connectio The API supports server-side filtering: ```bash -curl -G -H "Authorization: Bearer $AKOFLOW_TOKEN" \ +curl -G -H "Authorization: Bearer $AKOFLOW_API_TOKEN" \ --data-urlencode "environmentId=$ENVIRONMENT_ID" \ --data-urlencode "outcome=failed" \ --data-urlencode "limit=100" \ - "$AKOFLOW_URL/akoflow-api/audit-events/" + "$AKOFLOW_API_URL/audit-events/" ``` Available filter parameters are `eventType`, `environmentId`, `resourceId`, `connectionId`, `sessionId`, `executionId`, `outcome`, and `limit`. Outcomes currently include `started`, `succeeded`, and `failed`. The Desktop currently loads the audit list and applies its category tabs locally; use API filters for precise automation. diff --git a/docs/docs/guides/infrastructure/cloud-capacity.md b/docs/docs/guides/infrastructure/cloud-capacity.md index 6be6cb8e..adc9c890 100644 --- a/docs/docs/guides/infrastructure/cloud-capacity.md +++ b/docs/docs/guides/infrastructure/cloud-capacity.md @@ -1,5 +1,5 @@ --- -title: Cloud capacity and machine configuration +title: Configure cloud capacity --- A cloud environment separates four concerns: @@ -9,6 +9,8 @@ A cloud environment separates four concerns: 3. versioned machine configurations expressed as Ansible playbooks; 4. provisioned instances and their asynchronous lifecycle operations. +For the API commands on this page, complete [API connection setup](../../tutorials/api-access) first. + ## Provider support in v1.0 | Capability | Google Cloud | AWS | @@ -29,11 +31,11 @@ Open a cloud environment and select **Cloud capacity**. If no cached catalog exi ### Using the API ```bash -curl --fail-with-body -H "Authorization: Bearer $AKOFLOW_TOKEN" \ - -X POST "$AKOFLOW_URL/environments/gcp-lab/cloud-catalog/refresh/" +curl --fail-with-body -H "Authorization: Bearer $AKOFLOW_API_TOKEN" \ + -X POST "$AKOFLOW_API_URL/environments/gcp-lab/cloud-catalog/refresh/" -curl --fail-with-body -H "Authorization: Bearer $AKOFLOW_TOKEN" \ - "$AKOFLOW_URL/environments/gcp-lab/cloud-catalog/" +curl --fail-with-body -H "Authorization: Bearer $AKOFLOW_API_TOKEN" \ + "$AKOFLOW_API_URL/environments/gcp-lab/cloud-catalog/" ``` The GET endpoint returns `404` until a catalog has been synchronized. Provider credentials must already be stored and referenced by the cloud environment connection. @@ -50,9 +52,9 @@ The GET endpoint returns `404` until a catalog has been synchronized. Provider c ### Using the API ```bash -curl --fail-with-body -H "Authorization: Bearer $AKOFLOW_TOKEN" \ +curl --fail-with-body -H "Authorization: Bearer $AKOFLOW_API_TOKEN" \ -H 'Content-Type: application/json' -X POST \ - "$AKOFLOW_URL/environments/gcp-lab/cloud-capacity-targets/" \ + "$AKOFLOW_API_URL/environments/gcp-lab/cloud-capacity-targets/" \ -d '{ "name":"E2 standard worker", "provider":"gcp", @@ -84,22 +86,22 @@ Open **Infrastructure → Machine configurations**. Create a named configuration Validate YAML before saving it: ```bash -curl --fail-with-body -H "Authorization: Bearer $AKOFLOW_TOKEN" \ +curl --fail-with-body -H "Authorization: Bearer $AKOFLOW_API_TOKEN" \ -H 'Content-Type: application/json' -X POST \ - "$AKOFLOW_URL/machine-configuration-validations/" \ + "$AKOFLOW_API_URL/machine-configuration-validations/" \ -d '{"playbookYaml":"---\n- name: Configure worker\n hosts: all\n become: true\n tasks:\n - name: Install curl\n ansible.builtin.package:\n name: curl\n state: present\n"}' ``` Create the configuration and then its first version: ```bash -curl --fail-with-body -H "Authorization: Bearer $AKOFLOW_TOKEN" \ - -H 'Content-Type: application/json' -X POST "$AKOFLOW_URL/machine-configurations/" \ +curl --fail-with-body -H "Authorization: Bearer $AKOFLOW_API_TOKEN" \ + -H 'Content-Type: application/json' -X POST "$AKOFLOW_API_URL/machine-configurations/" \ -d '{"id":"analysis-worker","name":"Analysis worker","description":"Packages used by analysis jobs"}' -curl --fail-with-body -H "Authorization: Bearer $AKOFLOW_TOKEN" \ +curl --fail-with-body -H "Authorization: Bearer $AKOFLOW_API_TOKEN" \ -H 'Content-Type: application/json' -X POST \ - "$AKOFLOW_URL/machine-configurations/analysis-worker/versions/" \ + "$AKOFLOW_API_URL/machine-configurations/analysis-worker/versions/" \ -d '{"version":1,"status":"published","playbookYaml":"---\n- name: Configure worker\n hosts: all\n tasks: []\n","compatibility":{"providers":["gcp"]}}' ``` @@ -114,15 +116,15 @@ Open a cloud resource or the environment **Provisioning** tab and start provisio ### Using the API ```bash -curl --fail-with-body -H "Authorization: Bearer $AKOFLOW_TOKEN" \ +curl --fail-with-body -H "Authorization: Bearer $AKOFLOW_API_TOKEN" \ -H 'Content-Type: application/json' -X POST \ - "$AKOFLOW_URL/environments/gcp-lab/cloud-provisioning/" \ + "$AKOFLOW_API_URL/environments/gcp-lab/cloud-provisioning/" \ -d '{"capacityTargetId":""}' -# Follow all operations, then inspect the selected operation and its events -curl --fail-with-body -H "Authorization: Bearer $AKOFLOW_TOKEN" "$AKOFLOW_URL/cloud-operations/" -curl --fail-with-body -H "Authorization: Bearer $AKOFLOW_TOKEN" "$AKOFLOW_URL/cloud-operations//" -curl --fail-with-body -H "Authorization: Bearer $AKOFLOW_TOKEN" "$AKOFLOW_URL/cloud-operations//events/" +# Configure cloud capacity +curl --fail-with-body -H "Authorization: Bearer $AKOFLOW_API_TOKEN" "$AKOFLOW_API_URL/cloud-operations/" +curl --fail-with-body -H "Authorization: Bearer $AKOFLOW_API_TOKEN" "$AKOFLOW_API_URL/cloud-operations//" +curl --fail-with-body -H "Authorization: Bearer $AKOFLOW_API_TOKEN" "$AKOFLOW_API_URL/cloud-operations//events/" ``` The provisioning request queues an operation; it does not wait for the instance to become ready. Lifecycle endpoints also exist for configure, validate, start, stop, and destroy. Before destructive lifecycle actions, inspect the instance and active operation state in Desktop or through the API. diff --git a/docs/docs/guides/infrastructure/environments.md b/docs/docs/guides/infrastructure/environments.md index 56381036..46bf2a71 100644 --- a/docs/docs/guides/infrastructure/environments.md +++ b/docs/docs/guides/infrastructure/environments.md @@ -1,5 +1,5 @@ --- -title: Environments +title: Create and inspect environments --- An environment describes where AkôFlow can plan or run work. A **real environment** has an execution runtime such as local, SSH, Kubernetes, SLURM, or cloud. A **simulation environment** uses the SimGrid runtime and models resources without connecting to physical infrastructure. @@ -27,17 +27,17 @@ Simulation creation collects a SimGrid platform model and can also define an exe Set the daemon address and token once: ```bash -export AKOFLOW_URL='http://127.0.0.1:/akoflow-api' -export AKOFLOW_TOKEN='' +export AKOFLOW_API_URL='http://127.0.0.1:/akoflow-api' +export AKOFLOW_API_TOKEN='' ``` The creation body is an `EnvironmentDefinition`, not only an environment name. This minimal local example includes one version, runtime, resource, and runtime binding: ```bash curl --fail-with-body \ - -H "Authorization: Bearer $AKOFLOW_TOKEN" \ + -H "Authorization: Bearer $AKOFLOW_API_TOKEN" \ -H 'Content-Type: application/json' \ - -X POST "$AKOFLOW_URL/environments/" \ + -X POST "$AKOFLOW_API_URL/environments/" \ -d '{ "environment":{"id":"local-lab","name":"Local lab","status":"defined"}, "version":{"id":"local-lab-v1","environmentId":"local-lab","version":1,"status":"published"}, @@ -51,9 +51,9 @@ Before storing a remote connection, test the same connection object independentl ```bash curl --fail-with-body \ - -H "Authorization: Bearer $AKOFLOW_TOKEN" \ + -H "Authorization: Bearer $AKOFLOW_API_TOKEN" \ -H 'Content-Type: application/json' \ - -X POST "$AKOFLOW_URL/connection-tests/" \ + -X POST "$AKOFLOW_API_URL/connection-tests/" \ -d '{"id":"hpc-ssh","name":"HPC login","type":"ssh","endpoint":"login.example.org:22","username":"researcher","credentialRef":""}' ``` @@ -73,17 +73,17 @@ Health and discovery are different operations: health verifies access; discovery ### Using the API ```bash -# Persisted connection health check -curl --fail-with-body -H "Authorization: Bearer $AKOFLOW_TOKEN" \ - -X POST "$AKOFLOW_URL/environment-connections/hpc-ssh/health/" +# Create and inspect environments +curl --fail-with-body -H "Authorization: Bearer $AKOFLOW_API_TOKEN" \ + -X POST "$AKOFLOW_API_URL/environment-connections/hpc-ssh/health/" # Discovery through that connection -curl --fail-with-body -H "Authorization: Bearer $AKOFLOW_TOKEN" \ - -X POST "$AKOFLOW_URL/environment-connections/hpc-ssh/discover/" +curl --fail-with-body -H "Authorization: Bearer $AKOFLOW_API_TOKEN" \ + -X POST "$AKOFLOW_API_URL/environment-connections/hpc-ssh/discover/" # Recent health history -curl --fail-with-body -H "Authorization: Bearer $AKOFLOW_TOKEN" \ - "$AKOFLOW_URL/environment-connections/hpc-ssh/history/?limit=20" +curl --fail-with-body -H "Authorization: Bearer $AKOFLOW_API_TOKEN" \ + "$AKOFLOW_API_URL/environment-connections/hpc-ssh/history/?limit=20" ``` Discovery returns a `snapshots` array. A successful request does not imply that every possible resource type was found; inspect the returned snapshots and the environment inventory. @@ -97,8 +97,8 @@ The detail page is the hub for the environment map, version, runtimes, connectio ### Using the API ```bash -curl --fail-with-body -H "Authorization: Bearer $AKOFLOW_TOKEN" \ - "$AKOFLOW_URL/environments/local-lab/" +curl --fail-with-body -H "Authorization: Bearer $AKOFLOW_API_TOKEN" \ + "$AKOFLOW_API_URL/environments/local-lab/" ``` The response is the full definition, including the current version and related runtimes, resources, connections, and discovered storage when present. diff --git a/docs/docs/guides/infrastructure/execution-scopes.md b/docs/docs/guides/infrastructure/execution-scopes.md index 10a42974..c5e3d954 100644 --- a/docs/docs/guides/infrastructure/execution-scopes.md +++ b/docs/docs/guides/infrastructure/execution-scopes.md @@ -1,9 +1,11 @@ --- -title: Execution scopes and network topologies +title: Define execution scopes and network links --- An execution scope is a reusable set of environment versions available to planning. A network topology describes transfer links between resources. The scope stores a `networkTopologyId`; the topology stores its `executionScopeId`. Use stable IDs and create the scope before the topology when building them through the current API. +For the API commands on this page, complete [API connection setup](../../tutorials/api-access) first. + ## Create a scope ### Using AkôFlow Desktop @@ -25,9 +27,9 @@ A scope is not a copy of its environments and does not create connections or res ```bash curl --fail-with-body \ - -H "Authorization: Bearer $AKOFLOW_TOKEN" \ + -H "Authorization: Bearer $AKOFLOW_API_TOKEN" \ -H 'Content-Type: application/json' \ - -X POST "$AKOFLOW_URL/execution-scopes/" \ + -X POST "$AKOFLOW_API_URL/execution-scopes/" \ -d '{ "id":"hybrid-research", "name":"Hybrid research", @@ -39,8 +41,8 @@ curl --fail-with-body \ List or inspect scopes with: ```bash -curl --fail-with-body -H "Authorization: Bearer $AKOFLOW_TOKEN" "$AKOFLOW_URL/execution-scopes/" -curl --fail-with-body -H "Authorization: Bearer $AKOFLOW_TOKEN" "$AKOFLOW_URL/execution-scopes/hybrid-research/" +curl --fail-with-body -H "Authorization: Bearer $AKOFLOW_API_TOKEN" "$AKOFLOW_API_URL/execution-scopes/" +curl --fail-with-body -H "Authorization: Bearer $AKOFLOW_API_TOKEN" "$AKOFLOW_API_URL/execution-scopes/hybrid-research/" ``` ## Add a network topology @@ -55,9 +57,9 @@ Topology values affect transfer estimates. They do not test the physical network ```bash curl --fail-with-body \ - -H "Authorization: Bearer $AKOFLOW_TOKEN" \ + -H "Authorization: Bearer $AKOFLOW_API_TOKEN" \ -H 'Content-Type: application/json' \ - -X POST "$AKOFLOW_URL/network-topologies/" \ + -X POST "$AKOFLOW_API_URL/network-topologies/" \ -d '{ "id":"hybrid-network-v1", "name":"HPC to cloud", @@ -79,8 +81,8 @@ curl --fail-with-body \ Retrieve the stored model before using it for planning: ```bash -curl --fail-with-body -H "Authorization: Bearer $AKOFLOW_TOKEN" \ - "$AKOFLOW_URL/network-topologies/hybrid-network-v1/" +curl --fail-with-body -H "Authorization: Bearer $AKOFLOW_API_TOKEN" \ + "$AKOFLOW_API_URL/network-topologies/hybrid-network-v1/" ``` Use resource IDs that belong to environment versions in the scope. The API validates persistence constraints but does not measure whether the bandwidth and latency values match the real infrastructure. diff --git a/docs/docs/guides/infrastructure/gcp.md b/docs/docs/guides/infrastructure/gcp.md index 55dcfb5a..1085db84 100644 --- a/docs/docs/guides/infrastructure/gcp.md +++ b/docs/docs/guides/infrastructure/gcp.md @@ -88,10 +88,10 @@ Use the API when automating onboarding. Store the secret through the credentials ```bash export AKOFLOW_API_URL="http://127.0.0.1:8080/akoflow-api" -curl --fail-with-body -H "Authorization: Bearer $AKOFLOW_TOKEN" \ +curl --fail-with-body -H "Authorization: Bearer $AKOFLOW_API_TOKEN" \ -X POST "$AKOFLOW_API_URL/environments/gcp-lab/cloud-catalog/refresh/" -curl --fail-with-body -H "Authorization: Bearer $AKOFLOW_TOKEN" \ +curl --fail-with-body -H "Authorization: Bearer $AKOFLOW_API_TOKEN" \ "$AKOFLOW_API_URL/environments/gcp-lab/cloud-catalog/" ``` diff --git a/docs/docs/guides/infrastructure/hpc-slurm.md b/docs/docs/guides/infrastructure/hpc-slurm.md index 003a3c1c..19cc4b3c 100644 --- a/docs/docs/guides/infrastructure/hpc-slurm.md +++ b/docs/docs/guides/infrastructure/hpc-slurm.md @@ -50,9 +50,9 @@ In Desktop, add the connection under **Infrastructure → Environments**, assign ```bash curl --fail-with-body \ - -H "Authorization: Bearer $AKOFLOW_TOKEN" \ + -H "Authorization: Bearer $AKOFLOW_API_TOKEN" \ -H 'Content-Type: application/json' \ - -X PUT "$AKOFLOW_URL/environment-connections/research-hpc-ssh/" \ + -X PUT "$AKOFLOW_API_URL/environment-connections/research-hpc-ssh/" \ --data @research-hpc-connection.json ``` @@ -60,7 +60,7 @@ The exact `PUT` body must contain `id`, `environmentId`, `type`, endpoint, usern ## 2. Define the SLURM runtime and the infrastructure boundary -The versioned [`examples/slurm/environment.yaml`](https://github.com/UFFeScience/akoflow/blob/main/examples/slurm/environment.yaml) provides the catalog portion: runtime, cluster, partition, representative compute node, storage resources, and runtime bindings. Add a real connection like the preceding one before submitting it. +The versioned [`examples/slurm/environment.yaml`](https://github.com/UFFeScience/akoflow/blob/v1.0.8/examples/slurm/environment.yaml) provides the catalog portion: runtime, cluster, partition, representative compute node, storage resources, and runtime bindings. Add a real connection like the preceding one before submitting it. ```yaml title="examples/slurm/environment.yaml" runtimes: diff --git a/docs/docs/guides/infrastructure/kubernetes.md b/docs/docs/guides/infrastructure/kubernetes.md index 0a999264..88d659e6 100644 --- a/docs/docs/guides/infrastructure/kubernetes.md +++ b/docs/docs/guides/infrastructure/kubernetes.md @@ -177,7 +177,7 @@ Before launching a production workflow, verify image pull access from the select In Desktop, test the connection, run discovery, inspect the resource inventory, then import a small workflow. Create a scope containing the environment version, generate or create a plan, choose **Real execution**, and inspect the completed run's activity logs and artifacts. -For an equivalent API validation, follow the complete [Kind README](https://github.com/UFFeScience/akoflow/tree/main/examples/kind). It applies the cluster access and PVC, stores a short-lived token, and submits the environment, scope, topology, workflow, plan, and execution request in that order. +For an equivalent API validation, follow the complete [Kind README](https://github.com/UFFeScience/akoflow/tree/v1.0.8/examples/kind). It applies the cluster access and PVC, stores a short-lived token, and submits the environment, scope, topology, workflow, plan, and execution request in that order. The exact Kind bundle completed on 2026-09-11 as `kind-dag-run-v8`. It created two Kubernetes Jobs, transferred 9 bytes through its workspace, and produced matching `result.txt` and `consumed.txt` files with checksum `sha256:cb064c1339ffa3d7777bcb0459de3dceddb9146156dde58065a4ac826b029aa7`. diff --git a/docs/docs/guides/infrastructure/simgrid.md b/docs/docs/guides/infrastructure/simgrid.md index a272cbec..96a2ac04 100644 --- a/docs/docs/guides/infrastructure/simgrid.md +++ b/docs/docs/guides/infrastructure/simgrid.md @@ -11,7 +11,7 @@ Use SimGrid when the question is about a modeled platform: placement, parallel c ## Prerequisites -- A running AkôFlow daemon with the SimGrid runner available. The server image includes it; source builds can follow [`examples/simulation/README.md`](https://github.com/UFFeScience/akoflow/blob/main/examples/simulation/README.md). +- A running AkôFlow daemon with the SimGrid runner available. The server image includes it; source builds can follow [`examples/simulation/README.md`](https://github.com/UFFeScience/akoflow/blob/v1.0.8/examples/simulation/README.md). - A local checkout of the repository if you will submit the versioned YAML bundle. - A workflow with explicit `simulation.durationSeconds` or `simulation.flops` for every activity whose execution time should be modeled. diff --git a/docs/docs/guides/infrastructure/storage.md b/docs/docs/guides/infrastructure/storage.md index 74ee581f..72f586af 100644 --- a/docs/docs/guides/infrastructure/storage.md +++ b/docs/docs/guides/infrastructure/storage.md @@ -4,6 +4,8 @@ title: Browse and manage storage AkôFlow exposes storage through environment discovery or configured storage connectors. Browsing is constrained to approved roots and operations are capability-driven: a read-only or unavailable storage does not expose the same actions as a healthy writable storage. +For the API commands on this page, complete [API connection setup](../../tutorials/api-access) first. + ## Browse files ### Using AkôFlow Desktop @@ -19,17 +21,17 @@ Entries are loaded lazily for the selected path; opening Storage does not scan t ```bash # Discover storage IDs for an environment -curl --fail-with-body -H "Authorization: Bearer $AKOFLOW_TOKEN" \ - "$AKOFLOW_URL/environments/hpc/storages/" +curl --fail-with-body -H "Authorization: Bearer $AKOFLOW_API_TOKEN" \ + "$AKOFLOW_API_URL/environments/hpc/storages/" # Inspect approved roots -curl --fail-with-body -H "Authorization: Bearer $AKOFLOW_TOKEN" \ - "$AKOFLOW_URL/storages/hpc-scratch/roots/" +curl --fail-with-body -H "Authorization: Bearer $AKOFLOW_API_TOKEN" \ + "$AKOFLOW_API_URL/storages/hpc-scratch/roots/" # Browse one path; preserve nextCursor when the response is paginated -curl --fail-with-body -G -H "Authorization: Bearer $AKOFLOW_TOKEN" \ +curl --fail-with-body -G -H "Authorization: Bearer $AKOFLOW_API_TOKEN" \ --data-urlencode 'path=/scratch/project-a' --data-urlencode 'limit=100' \ - "$AKOFLOW_URL/storages/hpc-scratch/entries/" + "$AKOFLOW_API_URL/storages/hpc-scratch/entries/" ``` Do not construct paths outside the returned roots. The server validates the requested path against storage policy. @@ -44,21 +46,21 @@ The actions column can download a file, archive and download a directory, copy a ```bash # Prepare a file download (POST /archives/ for a directory) -curl --fail-with-body -H "Authorization: Bearer $AKOFLOW_TOKEN" \ +curl --fail-with-body -H "Authorization: Bearer $AKOFLOW_API_TOKEN" \ -H 'Content-Type: application/json' -X POST \ - "$AKOFLOW_URL/storages/hpc-scratch/downloads/" \ + "$AKOFLOW_API_URL/storages/hpc-scratch/downloads/" \ -d '{"path":"/scratch/project-a/result.csv","id":"download-result-1"}' # Copy to another registered storage -curl --fail-with-body -H "Authorization: Bearer $AKOFLOW_TOKEN" \ +curl --fail-with-body -H "Authorization: Bearer $AKOFLOW_API_TOKEN" \ -H 'Content-Type: application/json' -X POST \ - "$AKOFLOW_URL/storages/hpc-scratch/copies/" \ + "$AKOFLOW_API_URL/storages/hpc-scratch/copies/" \ -d '{"path":"/scratch/project-a/result.csv","destinationStorageId":"archive-store","id":"copy-result-1"}' # Calculate a checksum -curl --fail-with-body -H "Authorization: Bearer $AKOFLOW_TOKEN" \ +curl --fail-with-body -H "Authorization: Bearer $AKOFLOW_API_TOKEN" \ -H 'Content-Type: application/json' -X POST \ - "$AKOFLOW_URL/storages/hpc-scratch/checksum/" \ + "$AKOFLOW_API_URL/storages/hpc-scratch/checksum/" \ -d '{"path":"/scratch/project-a/result.csv"}' ``` @@ -73,14 +75,14 @@ Use **Register as DataObject** for a file that should enter the workflow data mo ### Using the API ```bash -curl --fail-with-body -H "Authorization: Bearer $AKOFLOW_TOKEN" \ +curl --fail-with-body -H "Authorization: Bearer $AKOFLOW_API_TOKEN" \ -H 'Content-Type: application/json' -X POST \ - "$AKOFLOW_URL/storages/hpc-scratch/promote-data/" \ + "$AKOFLOW_API_URL/storages/hpc-scratch/promote-data/" \ -d '{"path":"/scratch/project-a/result.csv","id":"data-result-1","workflowVersionId":"analysis-v3","runId":"run-42","activityId":"aggregate"}' -curl --fail-with-body -H "Authorization: Bearer $AKOFLOW_TOKEN" \ +curl --fail-with-body -H "Authorization: Bearer $AKOFLOW_API_TOKEN" \ -H 'Content-Type: application/json' -X POST \ - "$AKOFLOW_URL/storages/hpc-scratch/promote-artifact/" \ + "$AKOFLOW_API_URL/storages/hpc-scratch/promote-artifact/" \ -d '{"path":"/scratch/images/solver.sif","id":"solver-sif-1","name":"Solver","version":"1.2.0","scope":"environment","scopeId":"hpc"}' ``` diff --git a/docs/docs/guides/interface-tour.mdx b/docs/docs/guides/interface-tour.mdx index 92d58196..1496177a 100644 --- a/docs/docs/guides/interface-tour.mdx +++ b/docs/docs/guides/interface-tour.mdx @@ -9,7 +9,7 @@ description: Learn how the AkôFlow Desktop navigation maps to the control-plane import AnnotatedScreenshot from '@site/src/components/AnnotatedScreenshot'; import useBaseUrl from '@docusaurus/useBaseUrl'; -AkôFlow Desktop is the visual client for the AkôFlow daemon. The application does not run infrastructure commands from the browser renderer: it requests the daemon API, and the daemon performs discovery, planning, execution, data movement, and infrastructure operations. +AkôFlow Desktop lets you see your workflows, environments, plans, runs, and results in one place. Start on **Overview** to check the current instance, then use the sidebar to open the record you need. /tmp/akoflow-ssh-key.json curl --fail-with-body \ - -H "Authorization: Bearer $AKOFLOW_TOKEN" \ + -H "Authorization: Bearer $AKOFLOW_API_TOKEN" \ -H 'Content-Type: application/json' \ - -X POST "$AKOFLOW_URL/ssh-keys/import/" \ + -X POST "$AKOFLOW_API_URL/ssh-keys/import/" \ --data-binary @/tmp/akoflow-ssh-key.json ``` @@ -66,8 +68,8 @@ List public metadata at any time: ```bash curl --fail-with-body \ - -H "Authorization: Bearer $AKOFLOW_TOKEN" \ - "$AKOFLOW_URL/ssh-keys/" + -H "Authorization: Bearer $AKOFLOW_API_TOKEN" \ + "$AKOFLOW_API_URL/ssh-keys/" ``` There is currently no SSH-key deletion endpoint. Manage key lifecycle deliberately and rotate authorization on remote systems when a key should no longer be trusted. @@ -91,9 +93,9 @@ Read the current environment definition first so you preserve every connection f ```bash curl --fail-with-body \ - -H "Authorization: Bearer $AKOFLOW_TOKEN" \ + -H "Authorization: Bearer $AKOFLOW_API_TOKEN" \ -H 'Content-Type: application/json' \ - -X PUT "$AKOFLOW_URL/environment-connections/hpc-ssh/" \ + -X PUT "$AKOFLOW_API_URL/environment-connections/hpc-ssh/" \ -d '{ "id":"hpc-ssh", "environmentId":"plafrim", @@ -111,9 +113,9 @@ The Desktop environment connection flow stores a Kubernetes token and retains on ```bash curl --fail-with-body \ - -H "Authorization: Bearer $AKOFLOW_TOKEN" \ + -H "Authorization: Bearer $AKOFLOW_API_TOKEN" \ -H 'Content-Type: application/json' \ - -X POST "$AKOFLOW_URL/kubernetes-tokens/" \ + -X POST "$AKOFLOW_API_URL/kubernetes-tokens/" \ -d '{"id":"research-cluster","token":""}' ``` diff --git a/docs/docs/guides/operations/instance-management.md b/docs/docs/guides/operations/instance-management.md index 8bd25aef..8d87a59a 100644 --- a/docs/docs/guides/operations/instance-management.md +++ b/docs/docs/guides/operations/instance-management.md @@ -1,17 +1,17 @@ --- -title: Instance management +title: Manage an instance description: Configure an AkôFlow instance, export and import sanitized snapshots, switch instances, and reset local state. --- -# Instance management +# Manage an instance -An AkôFlow **instance** is one control-plane installation and its catalog. Its identity contains an ID, name, optional description, organization and location, plus the transfer relay buffer. The Engine creates an identity automatically from the machine hostname during startup; the Desktop cannot proceed when `GET /instance/` is unavailable. +An AkôFlow **instance** contains your environments, workflows, plans, runs, and settings. Use this guide to inspect its identity, export a snapshot, open a read-only archive, or return to the writable instance. Export a snapshot before changing versions or resetting local state. -Set these variables for the API examples: +For direct API use, complete [API connection setup](../../tutorials/api-access). The examples below use these variables: ```bash -export AKOFLOW_URL='http://127.0.0.1:/akoflow-api' -export AKOFLOW_TOKEN='' +export AKOFLOW_API_URL='http://127.0.0.1:/akoflow-api' +export AKOFLOW_API_TOKEN='' ``` ## Inspect the active identity @@ -26,17 +26,17 @@ The relay is an in-memory buffer per active transfer. It streams source output t ```bash curl --fail-with-body \ - -H "Authorization: Bearer $AKOFLOW_TOKEN" \ - "$AKOFLOW_URL/instance/" + -H "Authorization: Bearer $AKOFLOW_API_TOKEN" \ + "$AKOFLOW_API_URL/instance/" ``` To change the relay size, first preserve the identity returned by `GET`, then send the complete object: ```bash curl --fail-with-body \ - -H "Authorization: Bearer $AKOFLOW_TOKEN" \ + -H "Authorization: Bearer $AKOFLOW_API_TOKEN" \ -H 'Content-Type: application/json' \ - -X PUT "$AKOFLOW_URL/instance/" \ + -X PUT "$AKOFLOW_API_URL/instance/" \ -d '{ "id":"akoflow-lab", "name":"AkôFlow lab", @@ -67,14 +67,14 @@ The client ID must contain 8–128 characters. The only accepted themes are `lig CLIENT_ID='docs-client-01' curl --fail-with-body \ - -H "Authorization: Bearer $AKOFLOW_TOKEN" \ + -H "Authorization: Bearer $AKOFLOW_API_TOKEN" \ -H 'Content-Type: application/json' \ - -X PUT "$AKOFLOW_URL/user-preferences/$CLIENT_ID/" \ + -X PUT "$AKOFLOW_API_URL/user-preferences/$CLIENT_ID/" \ -d '{"theme":"dark","animationsEnabled":false}' curl --fail-with-body \ - -H "Authorization: Bearer $AKOFLOW_TOKEN" \ - "$AKOFLOW_URL/user-preferences/$CLIENT_ID/" + -H "Authorization: Bearer $AKOFLOW_API_TOKEN" \ + "$AKOFLOW_API_URL/user-preferences/$CLIENT_ID/" ``` ## Export a sanitized instance @@ -91,8 +91,8 @@ The Engine uses SQLite `VACUUM INTO` to create a consistent database snapshot. T ```bash curl --fail-with-body \ - -H "Authorization: Bearer $AKOFLOW_TOKEN" \ - "$AKOFLOW_URL/instances/default/export/?includeArtifacts=false" \ + -H "Authorization: Bearer $AKOFLOW_API_TOKEN" \ + "$AKOFLOW_API_URL/instances/default/export/?includeArtifacts=false" \ --output akoflow-instance.zip ``` @@ -115,19 +115,19 @@ The Desktop waits up to 90 seconds for the daemon after switching. When server-s ```bash curl --fail-with-body \ - -H "Authorization: Bearer $AKOFLOW_TOKEN" \ + -H "Authorization: Bearer $AKOFLOW_API_TOKEN" \ -H 'Content-Type: application/zip' \ --data-binary @akoflow-instance.zip \ - "$AKOFLOW_URL/instances/import/" + "$AKOFLOW_API_URL/instances/import/" curl --fail-with-body \ - -H "Authorization: Bearer $AKOFLOW_TOKEN" \ - "$AKOFLOW_URL/instances/" + -H "Authorization: Bearer $AKOFLOW_API_TOKEN" \ + "$AKOFLOW_API_URL/instances/" SNAPSHOT_ID='' curl --fail-with-body \ - -H "Authorization: Bearer $AKOFLOW_TOKEN" \ - -X POST "$AKOFLOW_URL/instance-activations/$SNAPSHOT_ID/" + -H "Authorization: Bearer $AKOFLOW_API_TOKEN" \ + -X POST "$AKOFLOW_API_URL/instance-activations/$SNAPSHOT_ID/" ``` Import accepts at most 8 GiB compressed data, at most 10,000 archive entries, and at most 64 GiB expanded data. Symbolic links and unsafe or unsupported archives are rejected with `422`. Activation returns `202 Accepted` with `instance` and a `restarting` boolean. @@ -158,8 +158,8 @@ Factory reset permanently removes the active AkôFlow catalog, environments, wor ```bash curl --fail-with-body \ - -H "Authorization: Bearer $AKOFLOW_TOKEN" \ - -X POST "$AKOFLOW_URL/factory-reset/" + -H "Authorization: Bearer $AKOFLOW_API_TOKEN" \ + -X POST "$AKOFLOW_API_URL/factory-reset/" ``` Success is `204 No Content`. The endpoint returns `503` when reset support is unavailable and `422` when the reset operation fails. It cannot run while a read-only snapshot is active because the read-only guard returns `423` first. diff --git a/docs/docs/guides/operations/interactive-console.md b/docs/docs/guides/operations/interactive-console.md index 76ceb54d..89860ade 100644 --- a/docs/docs/guides/operations/interactive-console.md +++ b/docs/docs/guides/operations/interactive-console.md @@ -1,18 +1,18 @@ --- -title: Interactive console and commands +title: Use the interactive console description: Run one-shot remote commands and open streamed terminal sessions on AkôFlow resources. --- import {ConnectionPath, TerminalPanelGuide} from '@site/src/components/InfrastructureWalkthrough'; -# Interactive console and commands +# Use the interactive console -AkôFlow exposes two related mechanisms: +Use the console to inspect a connected resource or run a short diagnostic command. Choose the action that fits the task: - a **console command** runs one command, records stdout, stderr and exit status, and returns a durable command record; -- an **interactive session** opens a remote terminal owned by the Engine and streams terminal bytes over WebSocket. +- an **interactive session** opens a remote terminal for a longer conversation. -Both resolve the selected resource to a runtime and connection. They are operational access paths and produce audit events. +Both require a resource with a usable runtime and connection. AkôFlow records these operations in the audit trail. @@ -35,13 +35,13 @@ The action appears only after AkôFlow can resolve all three layers: a resource, ## Open and manage a session through the API ```bash -export AKOFLOW_URL='http://127.0.0.1:/akoflow-api' -export AKOFLOW_TOKEN='' +export AKOFLOW_API_URL='http://127.0.0.1:/akoflow-api' +export AKOFLOW_API_TOKEN='' curl --fail-with-body \ - -H "Authorization: Bearer $AKOFLOW_TOKEN" \ + -H "Authorization: Bearer $AKOFLOW_API_TOKEN" \ -H 'Content-Type: application/json' \ - -X POST "$AKOFLOW_URL/console-sessions/" \ + -X POST "$AKOFLOW_API_URL/console-sessions/" \ -d '{"resourceId":"hpc-login","actorId":"researcher@example.org"}' ``` @@ -50,12 +50,12 @@ The created session has `starting`, `connected`, `closed`, or `failed` status an List and close sessions: ```bash -curl -H "Authorization: Bearer $AKOFLOW_TOKEN" \ - "$AKOFLOW_URL/console-sessions/" +curl -H "Authorization: Bearer $AKOFLOW_API_TOKEN" \ + "$AKOFLOW_API_URL/console-sessions/" curl --fail-with-body \ - -H "Authorization: Bearer $AKOFLOW_TOKEN" \ - -X DELETE "$AKOFLOW_URL/console-sessions/$SESSION_ID/" + -H "Authorization: Bearer $AKOFLOW_API_TOKEN" \ + -X DELETE "$AKOFLOW_API_URL/console-sessions/$SESSION_ID/" ``` Closure succeeds with `204 No Content`; an unknown session returns `404`. @@ -80,8 +80,8 @@ Download the archived session log: ```bash curl --fail-with-body \ - -H "Authorization: Bearer $AKOFLOW_TOKEN" \ - "$AKOFLOW_URL/console-sessions/$SESSION_ID/log/" \ + -H "Authorization: Bearer $AKOFLOW_API_TOKEN" \ + "$AKOFLOW_API_URL/console-sessions/$SESSION_ID/log/" \ --output "akoflow-$SESSION_ID.log" ``` @@ -93,9 +93,9 @@ The current Desktop focuses on the interactive terminal. Use the HTTP API for re ```bash curl --fail-with-body \ - -H "Authorization: Bearer $AKOFLOW_TOKEN" \ + -H "Authorization: Bearer $AKOFLOW_API_TOKEN" \ -H 'Content-Type: application/json' \ - -X POST "$AKOFLOW_URL/console-commands/" \ + -X POST "$AKOFLOW_API_URL/console-commands/" \ -d '{ "resourceId":"hpc-login", "actorId":"researcher@example.org", @@ -114,9 +114,9 @@ List recent commands: ```bash curl --get --fail-with-body \ - -H "Authorization: Bearer $AKOFLOW_TOKEN" \ + -H "Authorization: Bearer $AKOFLOW_API_TOKEN" \ --data-urlencode 'limit=50' \ - "$AKOFLOW_URL/console-commands/" + "$AKOFLOW_API_URL/console-commands/" ``` Command creation returns `422` for an unknown/unbound resource, invalid input, an excessive timeout, or runner failure. It returns `503` if console commands are unavailable. diff --git a/docs/docs/guides/operations/search-and-notifications.md b/docs/docs/guides/operations/search-and-notifications.md index 90dfe96e..7c0db832 100644 --- a/docs/docs/guides/operations/search-and-notifications.md +++ b/docs/docs/guides/operations/search-and-notifications.md @@ -1,11 +1,11 @@ --- -title: Search and notifications +title: Find records and follow notifications description: Find control-plane entities and follow long-running operations in AkôFlow Desktop. --- -# Search and notifications +# Find records and follow notifications -Global search is backed by the Engine catalogs. Notifications are a Desktop convenience built by tracking operations and polling their existing APIs; there is no notification collection endpoint. +Use search to open a workflow, run, environment, or other record by name or ID. Notifications point to operations that need attention. For a full history, open the record or its audit events. ## Search from Desktop @@ -34,15 +34,15 @@ The Engine ranks an exact field match above a prefix match, which ranks above a ## Search through the API ```bash -export AKOFLOW_URL='http://127.0.0.1:/akoflow-api' -export AKOFLOW_TOKEN='' +export AKOFLOW_API_URL='http://127.0.0.1:/akoflow-api' +export AKOFLOW_API_TOKEN='' curl --get --fail-with-body \ - -H "Authorization: Bearer $AKOFLOW_TOKEN" \ + -H "Authorization: Bearer $AKOFLOW_API_TOKEN" \ --data-urlencode 'q=science' \ --data-urlencode 'types=workflow,execution,artifact' \ --data-urlencode 'limit=20' \ - "$AKOFLOW_URL/search/" + "$AKOFLOW_API_URL/search/" ``` The response shape is: @@ -93,20 +93,20 @@ There is no `/notifications/` endpoint. Automation should query the resource tha ```bash # Planning session -curl -H "Authorization: Bearer $AKOFLOW_TOKEN" \ - "$AKOFLOW_URL/planning-sessions/$PLANNING_SESSION_ID/" +curl -H "Authorization: Bearer $AKOFLOW_API_TOKEN" \ + "$AKOFLOW_API_URL/planning-sessions/$PLANNING_SESSION_ID/" # Execution run -curl -H "Authorization: Bearer $AKOFLOW_TOKEN" \ - "$AKOFLOW_URL/execution-runs/$RUN_ID/" +curl -H "Authorization: Bearer $AKOFLOW_API_TOKEN" \ + "$AKOFLOW_API_URL/execution-runs/$RUN_ID/" # Active interactive sessions -curl -H "Authorization: Bearer $AKOFLOW_TOKEN" \ - "$AKOFLOW_URL/console-sessions/" +curl -H "Authorization: Bearer $AKOFLOW_API_TOKEN" \ + "$AKOFLOW_API_URL/console-sessions/" # Provisioned cloud instances for one environment -curl -H "Authorization: Bearer $AKOFLOW_TOKEN" \ - "$AKOFLOW_URL/environments/$ENVIRONMENT_ID/cloud-instances/" +curl -H "Authorization: Bearer $AKOFLOW_API_TOKEN" \ + "$AKOFLOW_API_URL/environments/$ENVIRONMENT_ID/cloud-instances/" ``` For a durable cross-domain timeline, query `/audit-events/` with the appropriate execution, session, connection, resource or environment filter. diff --git a/docs/docs/guides/operations/troubleshooting.md b/docs/docs/guides/operations/troubleshooting.md index 7b481620..240ec654 100644 --- a/docs/docs/guides/operations/troubleshooting.md +++ b/docs/docs/guides/operations/troubleshooting.md @@ -1,12 +1,12 @@ --- -title: Troubleshooting +title: Troubleshoot AkôFlow description: Diagnose daemon access, authentication, connection, discovery, planning, execution, storage, and snapshot problems. --- import useBaseUrl from '@docusaurus/useBaseUrl'; -# Troubleshooting +# Troubleshoot AkôFlow Start at the first failing boundary. Desktop is a client of the Engine API; the Engine then talks to Docker/BuildKit, runtimes, remote connections, storage and cloud providers. @@ -15,8 +15,8 @@ Start at the first failing boundary. Desktop is a client of the Engine API; the Set the endpoint and token before using the checks below: ```bash -export AKOFLOW_URL='http://127.0.0.1:' -export AKOFLOW_TOKEN='' +export AKOFLOW_API_URL='http://127.0.0.1:/akoflow-api' +export AKOFLOW_API_TOKEN='' ``` ## 1. Check the Engine and prerequisites @@ -24,15 +24,15 @@ export AKOFLOW_TOKEN='' The root endpoint is the basic health check: ```bash -curl --fail-with-body "$AKOFLOW_URL/" +curl --fail-with-body "${AKOFLOW_API_URL%/akoflow-api}/" ``` Then run the authenticated preflight: ```bash curl --fail-with-body \ - -H "Authorization: Bearer $AKOFLOW_TOKEN" \ - "$AKOFLOW_URL/akoflow-api/preflight/" + -H "Authorization: Bearer $AKOFLOW_API_TOKEN" \ + "$AKOFLOW_API_URL/preflight/" ``` The first-run Desktop screen performs this check before environment onboarding. It reports the AkôFlow daemon, host Docker daemon, and BuildKit readiness exposed by the current runtime. @@ -41,13 +41,11 @@ If Desktop shows **Instance identity unavailable**, the Engine did not provide ` ## 2. Fix authentication -`401 Unauthorized` or `403 Forbidden` means the API token is missing or rejected. +For direct API calls, `401 Unauthorized` usually means a missing or invalid bearer token. Set `AKOFLOW_API_TOKEN` to the token configured for the daemon and retry with `Authorization: Bearer `. -1. Open **Settings → General → API access token**. -2. Paste the token configured for this Engine and select **Save token**. -3. Retry the protected request. +The packaged Desktop manages its own local API connection; you do not need to paste its token into the application. In a separate web development client, **Settings → General → API access token** can supply a token for that client. A `403 Forbidden` response can also mean the request is outside a loopback-only access boundary; check the daemon listen address and caller location before changing credentials. -For API calls, send `Authorization: Bearer `. Avoid putting the token in URLs, screenshots, workflow files or shell history committed to source control. +Avoid putting tokens in URLs, screenshots, workflow files, or committed shell history. ## 3. Recognize read-only mode @@ -55,8 +53,8 @@ If a write returns `423 Locked` with `the selected instance is a read-only snaps ```bash curl --fail-with-body \ - -H "Authorization: Bearer $AKOFLOW_TOKEN" \ - -X POST "$AKOFLOW_URL/akoflow-api/instance-activations/default/" + -H "Authorization: Bearer $AKOFLOW_API_TOKEN" \ + -X POST "$AKOFLOW_API_URL/instance-activations/default/" ``` The daemon may restart. Desktop waits up to 90 seconds; a temporary connection failure is expected during that restart. @@ -78,8 +76,8 @@ Typical SSH causes are an unauthorized public key, wrong user/port, missing gate For historical evidence: ```bash -curl -H "Authorization: Bearer $AKOFLOW_TOKEN" \ - "$AKOFLOW_URL/akoflow-api/environment-connections/$CONNECTION_ID/history/?limit=20" +curl -H "Authorization: Bearer $AKOFLOW_API_TOKEN" \ + "$AKOFLOW_API_URL/environment-connections/$CONNECTION_ID/history/?limit=20" ``` ## 5. Diagnose search and missing data @@ -142,18 +140,18 @@ Useful endpoints: ```bash # Durable operational events -curl --get -H "Authorization: Bearer $AKOFLOW_TOKEN" \ +curl --get -H "Authorization: Bearer $AKOFLOW_API_TOKEN" \ --data-urlencode 'outcome=failed' \ --data-urlencode 'limit=100' \ - "$AKOFLOW_URL/akoflow-api/audit-events/" + "$AKOFLOW_API_URL/audit-events/" # Available instance modes -curl -H "Authorization: Bearer $AKOFLOW_TOKEN" \ - "$AKOFLOW_URL/akoflow-api/instances/" +curl -H "Authorization: Bearer $AKOFLOW_API_TOKEN" \ + "$AKOFLOW_API_URL/instances/" # Current Engine identity -curl -H "Authorization: Bearer $AKOFLOW_TOKEN" \ - "$AKOFLOW_URL/akoflow-api/instance/" +curl -H "Authorization: Bearer $AKOFLOW_API_TOKEN" \ + "$AKOFLOW_API_URL/instance/" ``` Factory reset is a last resort, not a diagnostic step. Export a sanitized snapshot first and use reset only when loss of local control-plane state is intentional. diff --git a/docs/docs/guides/workflows/definitions.md b/docs/docs/guides/workflows/definitions.md index b5050b5e..3c199877 100644 --- a/docs/docs/guides/workflows/definitions.md +++ b/docs/docs/guides/workflows/definitions.md @@ -1,8 +1,8 @@ --- -title: Workflow definitions +title: Define a workflow --- -# Workflow definitions +# Define a workflow A workflow definition is the reusable description of a scientific computation. AkôFlow stores a stable definition and an immutable, versioned graph of activities. Plans and runs refer to the workflow **version ID**, so a past execution remains traceable to the graph that produced it. diff --git a/docs/docs/guides/workflows/executions.md b/docs/docs/guides/workflows/executions.md index 455afaff..1c1f2f4f 100644 --- a/docs/docs/guides/workflows/executions.md +++ b/docs/docs/guides/workflows/executions.md @@ -6,6 +6,8 @@ title: Execute and monitor a workflow An execution run applies one immutable schedule plan to the workflow and infrastructure snapshots supplied in its request. Real and simulated runs share the same run, activity, timing, transfer, and cost model, which makes planned-versus-observed comparison possible. +For the API commands on this page, complete [API connection setup](../../tutorials/api-access) first. + ## Modes and run types - **Real** runs dispatch activities through execution runtimes such as a Kubernetes or SLURM adapter configured by the environment. diff --git a/docs/docs/guides/workflows/first-run.md b/docs/docs/guides/workflows/first-run.md index 2312bee3..df0e9058 100644 --- a/docs/docs/guides/workflows/first-run.md +++ b/docs/docs/guides/workflows/first-run.md @@ -1,13 +1,13 @@ --- -title: Run your first simulated workflow +title: Run the SimGrid example through the API description: Register the checked-in SimGrid example, execute it, and verify computation and network evidence. --- -# Run your first simulated workflow +# Run the SimGrid example through the API -This tutorial is for a first-time AkôFlow user with a running local daemon. You will submit a three-activity workflow to SimGrid and verify that all activities and both data transfers completed. Nothing is dispatched to Kubernetes, SLURM, or a cloud account. +This tutorial is for a reader with a separately managed AkôFlow API endpoint. You will submit a three-activity workflow to SimGrid and verify that all activities and both data transfers completed. Nothing is dispatched to Kubernetes, SLURM, or a cloud account. -Use this tutorial to confirm a new installation. Do not use it to learn automatic scheduling—the example imports a fixed plan so that the first result is reproducible. Continue to [Plan a workflow](./planning.md) after this run succeeds. +Use this tutorial to verify the simulation path. Do not use it to learn automatic scheduling—the example imports a fixed plan so that the first result is reproducible. Continue to [Plan a workflow](./planning.md) after this run succeeds. ## Before you begin diff --git a/docs/docs/guides/workflows/planning.md b/docs/docs/guides/workflows/planning.md index b1e14336..d8c2f0e5 100644 --- a/docs/docs/guides/workflows/planning.md +++ b/docs/docs/guides/workflows/planning.md @@ -8,6 +8,8 @@ Planning is separate from execution. A planning session freezes a workflow versi Only a selected candidate becomes a canonical schedule plan that can be executed. +For the API commands on this page, complete [API connection setup](../../tutorials/api-access) first. + ## Sessions, algorithms, and candidates A session records its workflow version, execution scope, network topology, selected algorithms, optional deadline and budget, progress, and final selection. Its status is `queued`, `running`, `completed`, `failed`, or `cancelled`. diff --git a/docs/docs/modules.md b/docs/docs/modules.md index d988a66b..c345c651 100644 --- a/docs/docs/modules.md +++ b/docs/docs/modules.md @@ -1,8 +1,8 @@ --- id: modules -title: AkôFlow components and boundaries -sidebar_label: Components and boundaries +title: Architecture internals +sidebar_label: Architecture internals --- import useBaseUrl from '@docusaurus/useBaseUrl'; diff --git a/docs/docs/reference/api-overview.md b/docs/docs/reference/api-overview.md index 4b2e021c..9d31c5ba 100644 --- a/docs/docs/reference/api-overview.md +++ b/docs/docs/reference/api-overview.md @@ -5,18 +5,18 @@ description: Authentication, conventions, and current AkôFlow HTTP endpoint gro # API overview -The AkôFlow Desktop is an HTTP client of the same API available to automation. API paths below are relative to the daemon origin and begin with `/akoflow-api/`. +The AkôFlow Desktop uses the same API available to automation. Paths in the tables below are relative to `AKOFLOW_API_URL`, which includes `/akoflow-api`. ## Connect and authenticate -Set the daemon URL and token in your shell: +Set the API base URL (including `/akoflow-api`) and token in your shell: ```bash -export AKOFLOW_URL="http://127.0.0.1:8080" -export AKOFLOW_TOKEN="replace-with-the-configured-token" +export AKOFLOW_API_URL="http://127.0.0.1:8080/akoflow-api" +export AKOFLOW_API_TOKEN="replace-with-the-configured-token" -curl -H "Authorization: Bearer $AKOFLOW_TOKEN" \ - "$AKOFLOW_URL/akoflow-api/environments/" +curl -H "Authorization: Bearer $AKOFLOW_API_TOKEN" \ + "$AKOFLOW_API_URL/environments/" ``` The listen address is configuration-dependent; do not assume the example port in production. When an API token is configured, send `Authorization: Bearer `. `GET` or `HEAD` requests for `/akoflow-api/instance/` and `GET /akoflow-api/preflight/` are public bootstrap operations. All other operations require the token. A daemon without a token is restricted to loopback access. @@ -37,8 +37,8 @@ Browser origins are controlled by the daemon's allowed-origin configuration. Aut Check daemon and local build capabilities: ```bash -curl "$AKOFLOW_URL/" -curl "$AKOFLOW_URL/akoflow-api/preflight/" +curl "${AKOFLOW_API_URL%/akoflow-api}/" +curl "$AKOFLOW_API_URL/preflight/" ``` The root health check returns `ok`. Preflight reports server, Docker, and BuildKit availability. @@ -149,10 +149,10 @@ The root health check returns `ok`. Preflight reports server, Docker, and BuildK Create a workflow by posting the current workflow definition document: ```bash -curl -X POST -H "Authorization: Bearer $AKOFLOW_TOKEN" \ +curl -X POST -H "Authorization: Bearer $AKOFLOW_API_TOKEN" \ -H "Content-Type: application/json" \ --data-binary @workflow.json \ - "$AKOFLOW_URL/akoflow-api/workflow-definitions/" + "$AKOFLOW_API_URL/workflow-definitions/" ``` ## Executions diff --git a/docs/docs/reference/environment-yaml.md b/docs/docs/reference/environment-yaml.md index 00d75a08..08c6bbdf 100644 --- a/docs/docs/reference/environment-yaml.md +++ b/docs/docs/reference/environment-yaml.md @@ -14,7 +14,7 @@ This reference describes the `EnvironmentDefinition` document accepted by `POST - Declare performance values deliberately. Omitting a numeric value decodes it as `0` (except `computeSpeedup`, which the database defaults to `1`); that is rarely a useful planning model. - Keep credentials out of the file. `credentialRef` and `credentialReference` name a credential already stored in AkôFlow; they are not the secret itself. -The smallest useful simulation definition is versioned in [`examples/simulation/environment.yaml`](https://github.com/UFFeScience/akoflow/blob/main/examples/simulation/environment.yaml). It is a better starting point than an empty document because it includes a runtime, schedulable resources, and their bindings. +The smallest useful simulation definition is versioned in [`examples/simulation/environment.yaml`](https://github.com/UFFeScience/akoflow/blob/v1.0.8/examples/simulation/environment.yaml). It is a better starting point than an empty document because it includes a runtime, schedulable resources, and their bindings. ## Document shape diff --git a/docs/docs/reference/execution-scopes-and-topologies.md b/docs/docs/reference/execution-scopes-and-topologies.md index 3800c348..9e15b786 100644 --- a/docs/docs/reference/execution-scopes-and-topologies.md +++ b/docs/docs/reference/execution-scopes-and-topologies.md @@ -115,7 +115,7 @@ The HEFT baseline finds a matching direct link for its transfer estimate. PRISM ## API sequence -The checked-in [SimGrid bundle](https://github.com/UFFeScience/akoflow/tree/main/examples/simulation) supplies a compatible `scope.yaml` and `topology.yaml`. Submit them in this order after creating the environment: +The checked-in [SimGrid bundle](https://github.com/UFFeScience/akoflow/tree/v1.0.8/examples/simulation) supplies a compatible `scope.yaml` and `topology.yaml`. Submit them in this order after creating the environment: ```bash curl --fail-with-body \ diff --git a/docs/docs/runtimes.md b/docs/docs/runtimes.md index 06d1432f..df4ae7a7 100644 --- a/docs/docs/runtimes.md +++ b/docs/docs/runtimes.md @@ -6,7 +6,7 @@ sidebar_label: Runtime adapters A runtime adapter translates an assigned activity into operations on an execution technology. Runtimes belong to an environment version and connect to resources through bindings. Workflows do not select a runtime through a legacy top-level YAML `runtime` field; a selected plan assigns resources and execution resolves their bindings. -This explanation focuses on the adapter boundary. Read [system architecture](./concepts) for the surrounding records and [execution control plane](./engine) for how the supervisor uses adapters. +This explanation focuses on runtime adapters. Read [Architecture internals](./modules) for the surrounding services and [Execution control plane](./engine) for how the server uses adapters. ## Runtime model diff --git a/docs/docs/showcase/edge-cloud-simulation.mdx b/docs/docs/showcase/edge-cloud-simulation.mdx index 4e885bf3..04ab24d4 100644 --- a/docs/docs/showcase/edge-cloud-simulation.mdx +++ b/docs/docs/showcase/edge-cloud-simulation.mdx @@ -28,12 +28,12 @@ The diagram and the workflow YAML show the same topology: `prepare` produces `da ## Download the inputs - Environment YAML ↓ - Execution scope YAML ↓ - Network topology YAML ↓ - Workflow YAML ↓ - Manual plan envelope ↓ - Execution envelope ↓ + Environment YAML ↓ + Execution scope YAML ↓ + Network topology YAML ↓ + Workflow YAML ↓ + Manual plan envelope ↓ + Execution envelope ↓ - Kind cluster ↓ - AkôFlow access ↓ - Persistent storage YAML ↓ - Environment YAML ↓ - Execution scope YAML ↓ - Network topology YAML ↓ - Workflow YAML ↓ - Plan envelope ↓ - Execution envelope ↓ + Kind cluster ↓ + AkôFlow access ↓ + Persistent storage YAML ↓ + Environment YAML ↓ + Execution scope YAML ↓ + Network topology YAML ↓ + Workflow YAML ↓ + Plan envelope ↓ + Execution envelope ↓ } api={

Run through the API

-

After creating the cluster and token as described in the complete Kind README, submit the same objects:

+

After creating the cluster and token as described in the complete Kind README, submit the same objects:

{`export AKOFLOW_API_URL="http://127.0.0.1:8080/akoflow-api"
 export AKOFLOW_API_TOKEN=""
 
@@ -71,4 +71,4 @@ A successful run produces two Kubernetes Jobs, a workspace PVC for each activity
 
 The checked-in bundle was executed from a clean Kind cluster on 2026-09-11 as `kind-dag-run-v8`: both activities completed, 9 bytes were transferred, and both files had checksum `sha256:cb064c1339ffa3d7777bcb0459de3dceddb9146156dde58065a4ac826b029aa7`. Its observed makespan was 17.776 s. Kubernetes scheduling and Pod startup are included in that wall-clock result.
 
-If the consumer Job remains `Pending`, use `kubectl describe pod ` to inspect PVC/node affinity. The full setup, verification, and cleanup procedure is in the [Kind README](https://github.com/UFFeScience/akoflow/tree/main/examples/kind).
+If the consumer Job remains `Pending`, use `kubectl describe pod ` to inspect PVC/node affinity. The full setup, verification, and cleanup procedure is in the [Kind README](https://github.com/UFFeScience/akoflow/tree/v1.0.8/examples/kind).
diff --git a/docs/docs/showcase/local-direct-execution.mdx b/docs/docs/showcase/local-direct-execution.mdx
index 76bae307..b52c35b8 100644
--- a/docs/docs/showcase/local-direct-execution.mdx
+++ b/docs/docs/showcase/local-direct-execution.mdx
@@ -25,13 +25,13 @@ The bundle declares `busybox:1.36` as an executable reference because portable r
 ## Download the inputs
 
 
-  Environment YAML ↓
-  Execution scope YAML ↓
-  Network topology YAML ↓
-  Workflow YAML ↓
-  Manual plan envelope ↓
-  Execution envelope ↓
-  Submission script ↓
+  Environment YAML ↓
+  Execution scope YAML ↓
+  Network topology YAML ↓
+  Workflow YAML ↓
+  Manual plan envelope ↓
+  Execution envelope ↓
+  Submission script ↓
 
 
 
-  Environment YAML ↓
-  Execution scope YAML ↓
-  Network topology YAML ↓
-  Workflow YAML ↓
-  Plan envelope ↓
-  Execution envelope ↓
-  Submission script ↓
+  Environment YAML ↓
+  Execution scope YAML ↓
+  Network topology YAML ↓
+  Workflow YAML ↓
+  Plan envelope ↓
+  Execution envelope ↓
+  Submission script ↓
 
 
 
-  Environment YAML ↓
-  Execution scope YAML ↓
-  Network topology YAML ↓
-  Workflow YAML ↓
-  Plan envelope ↓
-  Execution envelope ↓
-  Runnable shell script ↓
+  Environment YAML ↓
+  Execution scope YAML ↓
+  Network topology YAML ↓
+  Workflow YAML ↓
+  Plan envelope ↓
+  Execution envelope ↓
+  Runnable shell script ↓
 
 
 
-  Environment YAML ↓
-  Execution scope YAML ↓
-  Network topology YAML ↓
-  Workflow YAML ↓
-  Manual plan YAML ↓
-  Execution envelope ↓
-  Fixture daemon script ↓
-  Submission script ↓
+  Environment YAML ↓
+  Execution scope YAML ↓
+  Network topology YAML ↓
+  Workflow YAML ↓
+  Manual plan YAML ↓
+  Execution envelope ↓
+  Fixture daemon script ↓
+  Submission script ↓

The daemon uses no token by default. If your local configuration requires one, set AKOFLOW_API_TOKEN before running the supplied script.

diff --git a/docs/docusaurus.config.ts b/docs/docusaurus.config.ts index a0c894cd..247e1bcc 100644 --- a/docs/docusaurus.config.ts +++ b/docs/docusaurus.config.ts @@ -118,7 +118,7 @@ const config: Config = { title: "Docs", items: [ { label: "Getting Started", to: "/docs/getting-started" }, - { label: "Modules", to: "/docs/modules" }, + { label: "Architecture internals", to: "/docs/modules" }, { label: "Installation", to: "/docs/installation" }, { label: "Downloads", to: "/docs/downloads" }, { label: "Interface Tour", to: "/docs/guides/interface-tour" }, diff --git a/docs/quality-plan.md b/docs/quality-plan.md index 981766be..fde49299 100644 --- a/docs/quality-plan.md +++ b/docs/quality-plan.md @@ -2,7 +2,7 @@ This file is the editorial backlog for preparing the AkôFlow documentation for external open-source users. Update it after each documentation unit. A checked item must point to evidence in the repository or to a recorded verification command; absence of a known defect is not sufficient evidence. -Last audited: 2026-09-11 after the verified SimGrid first-run exercise. +Last audited: 2026-09-12. The current editorial pass found an unresolved Desktop first-workflow gap and generated-reference defects. Earlier checks below describe their historical scope, not a clean completion gate. ## Editorial contract @@ -25,7 +25,7 @@ Showcases are extended tutorials. They may link to how-to and reference pages, b - [x] Existing Showcase download URLs use `raw.githubusercontent.com` and the 50-core bundle was checked against repository files on 2026-09-11. - [x] No screenshot markers remain. `rg '