Quick Start: Cloud Agent startup paths do not resolve after cloning
Nobody has claimed this yet.
Assessment
- Difficulty
- 2/5
- Estimated time
- 1-3 hours
- Newbie friendliness
- 82/100
- Issue type
- Bug
- Clarity
- Clearly specified
- Activity status
- Active
- Tech stack
- docker-compose, markdown, shell
- Domain
- documentation
Research direction
Read documentation/develop/quick-start.md, especially lines 20–89, and trace the clone, file creation, and startup commands from the same parent directory. Make the documented issuer and verifier paths resolve without an unstated directory change, then verify both sequences in the supported shell variants; done when both startup scripts and environment files resolve as written.
Written by the indexing model from the issue text.
Description
User impact
New developers following the Agent Deployment steps cannot start either Cloud Agent without inferring an undocumented working-directory change.
Affected documentation and ownership
- Quick Start Guide, observed 2026-10-28 18:49 UTC, HTTP 200. The deployed startup examples match the source below.
- Editable, portal-local Markdown: documentation/develop/quick-start.md, lines 20–89, revision
fa985dfa33caefa45bf1e9009e1f6f5a445344fb. Not generated/imported component documentation. - Intended version: page sets
AGENT_VERSION=2.0.0. Directory resolution itself is version-independent; no version upgrade is requested.
Observed versus expected
The guide first runs:
git clone https://github.com/hyperledger/identus-cloud-agent
It then tells readers to create files at ./identus-cloud-agent/infrastructure/local/.env-issuer and .env-verifier, consistent with remaining in the clone's parent directory.
The next executable examples instead start with ./infrastructure/local/run.sh and pass ./infrastructure/local/.env-issuer or .env-verifier. No step establishes the checkout root as the working directory. Git clone does not change the calling shell's directory.
Expected: both the startup script and environment-file paths resolve when the documented steps are followed literally.
Evidence and reproduction
Static comparison, Python 3.13.15/pathlib, 2026-10-28:
- Start in a fresh parent directory and follow the listed clone/file-creation sequence.
- Resolve the startup command's
./infrastructure/local/run.shfrom that same directory: it is outside the newly createdidentus-cloud-agentcheckout. - The actual script is inside the matching Agent v2.0.0 checkout. Its explicit environment-file argument is passed to Docker Compose.
This is a source/path-resolution defect, not a claim of a tested Docker failure. No tutorial commands, Docker deployment or service requests were executed. A reader who independently changes directory can work around it. Deployment commit is not exposed; source/deployed example text was compared, not assumed from timestamps.
Existing work checked
Searched open/closed issues and PRs, including discussion, in docs, cloud-agent and sdk-ts by Quick Start/path, run.sh, and startup root cause; fully paginated repository inventories were also checked. docs #222/#223 update versions/flow, not this directory transition. cloud-agent #1171 concerns image/version configuration after the script is already running. No existing repair for this omission was found.
Acceptance criteria
- From a fresh clone parent, the guide explicitly establishes working-directory context in which its startup script and environment-file paths resolve.
- Verify the documented issuer and verifier sequences on both supported shell variants without an unmentioned directory change.
- Dominant language
- TypeScript
- Stars
- 15
- Forks
- 8
- Avg merge
- 7d 19h
- Merged PRs (30d)
- 3
Getting set up
- No Dockerfile or Docker Compose file
- No pull request template
- Read the contributing guide
First steps
- Read the whole issue, then the project's contributing guide.
- Comment on the issue to say you are picking it up — it saves two people doing the same work.
- Fork the repository and make your change on a branch.
- Open a pull request that references the issue number.
More from hyperledger-identus/docs
-
documentation
Difficulty 1/5 1-3 hours Newbie friendliness 89/100
hyperledger-identus/docs#296 ·
-
documentation
Difficulty 2/5 1-3 hours Newbie friendliness 82/100
hyperledger-identus/docs#295 ·
-
documentation
Difficulty 2/5 1-3 hours Newbie friendliness 83/100
hyperledger-identus/docs#294 ·
-
Quick Start: TypeScript demo requires Accept, but the guide promises automatic offer acceptanceOpendocumentation
Difficulty 2/5 1-3 hours Newbie friendliness 82/100
hyperledger-identus/docs#293 ·
-
documentation
Difficulty 1/5 Under an hour Newbie friendliness 85/100
hyperledger-identus/docs#291 · 1 comment ·
All issues in hyperledger-identus/docs
Similar issues
-
Difficulty 2/5 1-3 hours Newbie friendliness 78/100
gnosis/gnosis_vpn#661 ·
Maintainers usually reply within 1 day
-
content-freshness: staleOwnedContent doc comments still say 'complete receipt' (follow-up to #7912)Opentriage:bug-verified
Difficulty 1/5 Under an hour Newbie friendliness 92/100
Maintainers usually reply within 1 day
-
fix: reject sourceStorage/packagedStorage bucket that differs from the stack default (fail loud)Open
Difficulty 2/5 1-3 hours Newbie friendliness 82/100
Eyevinn/open-videocore#1300 ·
Maintainers usually reply within 1 day
-
nextjs-tracking
Difficulty 2/5 1-3 hours Newbie friendliness 67/100
cloudflare/vinext#4390 ·
Maintainers usually reply within 1 day
-
kind/bug
Difficulty 2/5 1-3 hours Newbie friendliness 82/100
kubernetes-sigs/headlamp#8175 ·
Maintainers usually reply within 2 days