docs: add Quick start and Local development workflow guides - #39
docs: add Quick start and Local development workflow guides#39patrikbraborec wants to merge 12 commits into
Conversation
Adds a docs/ folder with two guided pages, modelled on the shape of the Supabase local-development guide: - docs/quick-start.md: prerequisites, starting the runtime with the Apify CLI (opt-in 'runtime' channel) or plain Docker, pointing the CLI at it, first push and run, inspecting, stop/reset, and a clearly marked proposal for an 'apify local' command group as the ideal CLI-only experience. - docs/local-development.md: the full dev loop (push/build/run/inspect), iterating without rebuilds via the dev folder, IDE debugging, migration/reboot/abort rehearsal, multiple users, platform fallback, limitations, and an ideal-state list of DX improvements. Also documents the Docker Desktop port-forwarding issue observed on macOS (published ports hang once the runtime joins the apify-local network) with the single-network workaround. README and CLAUDE.md gain pointers to the new docs. No code or behaviour changes.
Short 'Learn how to' intros, a 'Before you start' list, numbered steps in the quick start, imperative sentences, tables for commands and paths, bold-titled notes, and 'Next steps'. Same content and scope; proposals stay clearly marked.
- 'Check that it is running' and 'Connect Apify CLI' lead with one proposed apify local command each (status, connect/disconnect), clearly marked as proposed, with the working alternative right below. - Proposal table gains connect/disconnect in place of env. - Step 3 targets the reader's own Actor; samples move to a note.
- apify local start is documented as run from the Actor directory, with data kept in the Actor's own data folder. - The 'Debug with your IDE' section moves into the quick start as step 6. - docs/local-development.md is removed for now; README and CLAUDE.md pointers updated.
Co-authored-by: Cursor <cursoragent@cursor.com>
Pijukatel
left a comment
Pijukatel
left a comment
There was a problem hiding this comment.
I have already implemented some methods in the CLI in advance and named them differently. I will use naming suggested here and once the CLI is updated I will post review here with whatever minor update is needed
| To send every Apify CLI command to the local runtime instead of the Apify platform, run: | ||
|
|
||
| ``` | ||
| apify local connect |
There was a problem hiding this comment.
This is, in essence, very global. It makes sense for parallel agents, for example, to run separate instances of the local runtime. We should describe how to do that.
I imagine setting APIFY_CLIENT_BASE_URL and APIFY_CONSOLE_URL in a per-worktree .env file or via mise would work just fine...
There was a problem hiding this comment.
My idea that it would work out of the box in Actor project. Anyway, your point is good. Maybe it can be both the .env, and also maybe some parameters like apify local connect --client-base-url=<...> ...
| 3. Run the Actor: | ||
|
|
||
| ``` | ||
| apify call |
There was a problem hiding this comment.
How does apify run fit into this? Can we delete it to prevent confusion?
There was a problem hiding this comment.
Well, I think that we still need apify run, if you want to run Actor without local runtime.
Just for the context, run is the second most used command. If we decide to change it/delete it, we should definitely think twice to do it correctly. :)
There was a problem hiding this comment.
That statistic can be misleading, and if we can easily replace run with something that uses the local runtime instead, it will benefit pretty much everyone.
4 participants
Summary
Adds a
docs/folder with two guided pages, modelled on the shape of the Supabase local development guide. No code or behaviour changes.docs/quick-start.md- prerequisites, starting the runtime (Apify CLI's opt-inapify runtimechannel, or plain Docker), pointing the CLI at it, first push and run, inspecting, stop/reset. Ends with a clearly marked proposal for anapify local start|stop|status|env|reset|logscommand group as the ideal CLI-only experience, and explains how it relates to the shippedapify runtimecommands and the spec on theclaude/actor-runtime-cli-distribution-mo0u94branch.docs/local-development.md- the full dev loop (push/build/run/inspect), measured build times, iterating without rebuilds via the dev folder, IDE debugging, migration/reboot/abort rehearsal, multiple users, platform fallback, going back to the platform, limitations, and an ideal-state list of DX improvements (auto dev-folder registration,apify call --dev, runtime-side network fix, housekeeping).