docs: add troubleshooting guide and expand setup instructions - #1990
docs: add troubleshooting guide and expand setup instructions#1990efekrbas wants to merge 19 commits into
Conversation
Assisted-by: Gemini:gemini-3.1-pro
![chatgpt-codex-connector[bot]](https://avatars.githubusercontent.com/in/1144995?s=60&v=4){kind=small}
There was a problem hiding this comment.
💡 Codex Review
Here are some automated review suggestions for this pull request.
Reviewed commit: 214f2708ae
ℹ️ About Codex in GitHub
Codex has been enabled to automatically review pull requests in this repo. Reviews are triggered when you
- Open a pull request for review
- Mark a draft as ready
- Comment "@codex review".
If Codex has suggestions, it will comment; otherwise it will react with 👍.
When you sign up for Codex through ChatGPT, Codex can also answer questions or update the PR, like "@codex address that feedback".
Assisted-by: Gemini:gemini-3.1-pro
|
@codex review |
There was a problem hiding this comment.
💡 Codex Review
Here are some automated review suggestions for this pull request.
Reviewed commit: 2901d3b907
ℹ️ About Codex in GitHub
Codex has been enabled to automatically review pull requests in this repo. Reviews are triggered when you
- Open a pull request for review
- Mark a draft as ready
- Comment "@codex review".
If Codex has suggestions, it will comment; otherwise it will react with 👍.
When you sign up for Codex through ChatGPT, Codex can also answer questions or update the PR, like "@codex address that feedback".
Assisted-by: Gemini:gemini-3.1-pro
|
@codex review |
|
Codex Review: Didn't find any major issues. Nice work! Reviewed commit: ℹ️ About Codex in GitHubCodex has been enabled to automatically review pull requests in this repo. Reviews are triggered when you
If Codex has suggestions, it will comment; otherwise it will react with 👍. When you sign up for Codex through ChatGPT, Codex can also answer questions or update the PR, like "@codex address that feedback". |
There was a problem hiding this comment.
💡 Codex Review
Here are some automated review suggestions for this pull request.
Reviewed commit: 26ce4945c7
ℹ️ About Codex in GitHub
Codex has been enabled to automatically review pull requests in this repo. Reviews are triggered when you
- Open a pull request for review
- Mark a draft as ready
- Comment "@codex review".
If Codex has suggestions, it will comment; otherwise it will react with 👍.
When you sign up for Codex through ChatGPT, Codex can also answer questions or update the PR, like "@codex address that feedback".
Assisted-by: Antigravity:Gemini-3.1-Pro
|
@codex review |
I, Efe Kýrbaþ <efekrbass@gmail.com>, hereby add my Signed-off-by to this commit: 214f270 I, Efe Kýrbaþ <efekrbass@gmail.com>, hereby add my Signed-off-by to this commit: 2901d3b I, Efe Kýrbaþ <efekrbass@gmail.com>, hereby add my Signed-off-by to this commit: 47c72d8 I, Efe Kýrbaþ <efekrbass@gmail.com>, hereby add my Signed-off-by to this commit: bd84c39 Signed-off-by: Efe Kýrbaþ <efekrbass@gmail.com>
I, Efe Kırbaş <efekrbass@gmail.com>, hereby add my Signed-off-by to this commit: 214f270 I, Efe Kırbaş <efekrbass@gmail.com>, hereby add my Signed-off-by to this commit: 2901d3b I, Efe Kırbaş <efekrbass@gmail.com>, hereby add my Signed-off-by to this commit: 47c72d8 I, Efe Kırbaş <efekrbass@gmail.com>, hereby add my Signed-off-by to this commit: bd84c39 I, Efe Kırbaş <efekrbass@gmail.com>, hereby add my Signed-off-by to this commit: 9abf549 Signed-off-by: Efe Kırbaş <efekrbass@gmail.com>
There was a problem hiding this comment.
💡 Codex Review
Here are some automated review suggestions for this pull request.
Reviewed commit: bd84c39738
ℹ️ About Codex in GitHub
Codex has been enabled to automatically review pull requests in this repo. Reviews are triggered when you
- Open a pull request for review
- Mark a draft as ready
- Comment "@codex review".
If Codex has suggestions, it will comment; otherwise it will react with 👍.
When you sign up for Codex through ChatGPT, Codex can also answer questions or update the PR, like "@codex address that feedback".
Assisted-by: Antigravity:Gemini-3.1-Pro Signed-off-by: Efe Kırbaş <efekrbass@gmail.com>
|
@codex review |
There was a problem hiding this comment.
💡 Codex Review
Here are some automated review suggestions for this pull request.
Reviewed commit: 786b3bee89
ℹ️ About Codex in GitHub
Codex has been enabled to automatically review pull requests in this repo. Reviews are triggered when you
- Open a pull request for review
- Mark a draft as ready
- Comment "@codex review".
If Codex has suggestions, it will comment; otherwise it will react with 👍.
When you sign up for Codex through ChatGPT, Codex can also answer questions or update the PR, like "@codex address that feedback".
| ## Midnight-Specific Setup | ||
| ### 2. Earthly (Containerized Builds) | ||
|
|
||
| Earthly is required for building Docker images, regenerating metadata, and rebuilding genesis state. |
There was a problem hiding this comment.
On a clean macOS/Linux machine following this setup page, installing only the Earthly binary is not enough for the repo targets this paragraph sends developers to use: the Earthfile builds images and runs containerized targets, so earthly +... fails unless Docker or another supported container backend is installed and running. The WSL note mentions Docker Desktop, but the macOS/Linux paths never add the same prerequisite, so add a Docker/podman install step before verifying Earthly.
Useful? React with 👍 / 👎.
There was a problem hiding this comment.
💡 Codex Review
Here are some automated review suggestions for this pull request.
Reviewed commit: aeaf9398cd
ℹ️ About Codex in GitHub
Codex has been enabled to automatically review pull requests in this repo. Reviews are triggered when you
- Open a pull request for review
- Mark a draft as ready
- Comment "@codex review".
If Codex has suggestions, it will comment; otherwise it will react with 👍.
When you sign up for Codex through ChatGPT, Codex can also answer questions or update the PR, like "@codex address that feedback".
|
@codex review |
There was a problem hiding this comment.
💡 Codex Review
Here are some automated review suggestions for this pull request.
Reviewed commit: 13ef2cf9fd
ℹ️ About Codex in GitHub
Codex has been enabled to automatically review pull requests in this repo. Reviews are triggered when you
- Open a pull request for review
- Mark a draft as ready
- Comment "@codex review".
If Codex has suggestions, it will comment; otherwise it will react with 👍.
When you sign up for Codex through ChatGPT, Codex can also answer questions or update the PR, like "@codex address that feedback".
|
@codex review |
There was a problem hiding this comment.
💡 Codex Review
Here are some automated review suggestions for this pull request.
Reviewed commit: 2bfd91495d
ℹ️ About Codex in GitHub
Codex has been enabled to automatically review pull requests in this repo. Reviews are triggered when you
- Open a pull request for review
- Mark a draft as ready
- Comment "@codex review".
If Codex has suggestions, it will comment; otherwise it will react with 👍.
When you sign up for Codex through ChatGPT, Codex can also answer questions or update the PR, like "@codex address that feedback".
|
@codex review |
There was a problem hiding this comment.
💡 Codex Review
Here are some automated review suggestions for this pull request.
Reviewed commit: 9ba9b08a4a
ℹ️ About Codex in GitHub
Codex has been enabled to automatically review pull requests in this repo. Reviews are triggered when you
- Open a pull request for review
- Mark a draft as ready
- Comment "@codex review".
If Codex has suggestions, it will comment; otherwise it will react with 👍.
When you sign up for Codex through ChatGPT, Codex can also answer questions or update the PR, like "@codex address that feedback".
|
@codex review |
There was a problem hiding this comment.
💡 Codex Review
Here are some automated review suggestions for this pull request.
Reviewed commit: dd18f6e2d9
ℹ️ About Codex in GitHub
Codex has been enabled to automatically review pull requests in this repo. Reviews are triggered when you
- Open a pull request for review
- Mark a draft as ready
- Comment "@codex review".
If Codex has suggestions, it will comment; otherwise it will react with 👍.
When you sign up for Codex through ChatGPT, Codex can also answer questions or update the PR, like "@codex address that feedback".
A bare `cargo test` fails on fresh setups because midnight-node-toolkit depends on generated toolkit-js npm artifacts. The Earthfile +test target explicitly excludes it. Replace with `cargo check` as the smoke test and document proper test commands. Assisted-by: Claude:claude-opus-4-20250514 Signed-off-by: Efe Kırbaş <efekrbass@gmail.com>
The earthly +test target requires --secret DOCKERHUB_USER= --secret DOCKERHUB_TOKEN= flags even for local runs. The direct cargo command now uses cargo nextest with the full -E filter from the Earthfile to skip fixture-dependent pallet tests (test_get_contract_state, test_send_mn_transaction, test_validation_works). Assisted-by: Claude:claude-opus-4-20250514 Signed-off-by: Efe Kırbaş <efekrbass@gmail.com>
…ation cargo-nextest is only installed inside the Earthly CI image, not available on a fresh local setup. Switch to plain `cargo test` with --skip flags for the fixture-dependent tests. Assisted-by: Claude:claude-opus-4-20250514 Signed-off-by: Efe Kırbaş <efekrbass@gmail.com>
The hardcoded earthly-linux-amd64 URL fails on ARM64 Linux hosts. Use uname -m to detect the architecture and download the correct binary (amd64 or arm64). Assisted-by: Claude:claude-opus-4-20250514 Signed-off-by: Efe Kırbaş <efekrbass@gmail.com>
dd18f6e to
5601477
Compare
Earthly's WITH DOCKER feature (used in targets like +test) requires rootful Podman. Clarify this requirement in the setup instructions and add the command to start the rootful podman socket on Linux. Assisted-by: Claude:claude-opus-4-20250514 Signed-off-by: Efe Kırbaş <efekrbass@gmail.com>
|
@codex review |
|
Codex Review: Didn't find any major issues. Another round soon, please! Reviewed commit: ℹ️ About Codex in GitHubCodex has been enabled to automatically review pull requests in this repo. Reviews are triggered when you
If Codex has suggestions, it will comment; otherwise it will react with 👍. When you sign up for Codex through ChatGPT, Codex can also answer questions or update the PR, like "@codex address that feedback". |
There was a problem hiding this comment.
💡 Codex Review
Here are some automated review suggestions for this pull request.
Reviewed commit: 4b43b88a1c
ℹ️ About Codex in GitHub
Codex has been enabled to automatically review pull requests in this repo. Reviews are triggered when you
- Open a pull request for review
- Mark a draft as ready
- Comment "@codex review".
If Codex has suggestions, it will comment; otherwise it will react with 👍.
When you sign up for Codex through ChatGPT, Codex can also answer questions or update the PR, like "@codex address that feedback".
| > and the fixture-dependent tests: | ||
| > | ||
| > ```bash | ||
| > cargo test --workspace --locked \ |
There was a problem hiding this comment.
When developers choose the direct Cargo path here on a normal workstation, this runs the workspace tests in the debug profile, but the repo's Earthfile documents that debug/opt-level=1 test binaries can OOM the linker (>24GB) and the +test target instead sets opt-level 2 and runs cargo nextest ... --release (Earthfile:1110-1134). This fallback can therefore still fail for memory reasons unrelated to setup; mirror the release/RUSTFLAGS settings or avoid recommending a direct whole-workspace Cargo run.
Useful? React with 👍 / 👎.
1 participant
Overview
This PR improves the developer onboarding experience and fixes broken documentation links. Specifically, it:
docs/rust-setup.mdinto a comprehensivePrerequisites & Setupguide, adding missing setup steps for Earthly, Just, and Nix which are critical for the node build.docs/troubleshooting.mdguide that aggregates common build and setup errors (WASMmemmovecompilation error, ledger upgrade issues, Earthly build failures, SSL connection errors).testing-upgrades.mdindocs/development-workflow.mdby pointing to the correctfork-testing.mdguide for hardfork upgrades.README.mdto reflect the new Troubleshooting guide and the renamed Setup section.🗹 TODO before merging
📌 Submission Checklist
git commit -s) for the DCO🧪 Testing Evidence
N/A - Documentation updates only.
🔱 Fork Strategy