docs: rewrite source types document

sources/platform/actors/development/deployment/index.md

@@ -5,35 +5,67 @@ description: Learn how to deploy your Actor to the Apify platform and build them
 slug: /actors/development/deployment
 ---
 
-**Learn how to deploy your Actor to the Apify platform and build them.**
+**Learn how to deploy your Actors to the Apify platform and build them.**
 
 ---
 
-The deployment of your Actor is the process of uploading your Actor [source code](../actor_definition/index.md) and [building](../builds_and_runs/builds.md) it on the Apify platform. After that, you can easily [run](../builds_and_runs/runs.md) and scale your Actor in the cloud.
+Deploying an Actor involves uploading your [source code](/platform/actors/development/actor-definition) and [building](/platform/actors/development/builds-and-runs/builds) it on the Apify platform. Once deployed, you can run and scale your Actor in the cloud.
 
-## Apify CLI
+## Deploy using Apify CLI
 
-The easiest and fastest way to get your Actor deployed and built is to use [Apify CLI](/cli). If you followed one of the [tutorials](/academy), you should already have it installed. If you do not have Apify CLI installed, then follow the instructions at [Apify CLI documentation](/cli/docs/installation) to install it. Then you can simply log in to your Apify account by running:
+The fastest way to deploy and build your Actor is by uising the [Apify CLI](/cli). If you've completed one of the tutorials from the [academy](/academy), you should have already have it installed. If not, follow the [Apify CLI installation instructions](/cli/docs/installation).
+
+To deploy your Actor using Apify CLI:
+
+1. Log in to your Apify account:
+
+    ```bash
+    apify login
+    ```
+
+1. Navigate to the directory of your Actor on your local machine.
+
+1. Deploy your Actor by running:
+
+    ```bash
+    apify push
+    ```
+
+When you deploy using the CLI, your source code is uploaded as "multiple source files" and is visible and editable in the Web IDE.
+
+![Web IDE](./images/actor-source.png)
+
+:::note Source files size limit
+
+The CLI deploys code as multiple source files up to 3 MB. Beyond that, it deploys as a Zip file.
+
+:::
+
+### Pull an existing Actor
+
+You can also pull an existing Actor from the Apify platform to your local machine using `apify pull` command
 
 ```bash
-apify login
+apify pull [ACTORID]
 ```
 
-and then deploy your Actor by running:
+This command fetches the Actor's files to your current directory. If the Actor is defined as a Git repository, it will be cloned, for Actors defined in the Web IDE, the command will fetch the files diresctly.
+
+You can specify a particular version of the Actor to pull by using the `--version` flag:
 
 ```bash
-apify push
+apify pull [ACTORID] --version=1.2
 ```
 
-When you deploy an Actor using the CLI, the code gets deployed as "multiple source files" Actor source type and so the code is visible and editable via web IDE:
-![Web IDE](./images/actor-source.png)
-
-> This works only until a certain size; after that, Apify CLI deploys the code as a Zip file.
+If you don't provide the `ACTORID`, the command will update the Actor in the current directory based on its name in the `.actor/actor.json` file.
 
-## Other ways (Zip, Git, Gist)
+## Alternative deployment methods
 
-If you want to deploy an Actor in a different way, you need to first manually create the Actor in [Apify Console](https://my.apify.com/actors). Then switch its source type:
+To deploy using other methods, first create the Actor manually through Apify CLI or Apify Console, then change its source type:
 
 ![Actor source types](./images/actor-source-types.png)
 
-This enables you to link a Git repository, Gist, or Zip file to your Actor. You will find more information on all source types in the following chapter.
+You can link your anctor to a Git repository, Gist, or a Zip file.
+
+For more information on alternative source types, check out next chapter.
+

sources/platform/actors/development/deployment/source_types.md

@@ -5,69 +5,92 @@ slug: /actors/development/deployment/source-types
 sidebar_position: 1
 ---
 
-# Source types {#source-types}
-
 **Learn about Apify Actor source types and how to deploy an Actor from GitHub using CLI or Gist.**
 
 ---
 
-The **Source type** setting determines the location of the source code for the Actor. It can have one of the following values: [Web IDE](#web-ide), [Git repository](#git-repository), [Zip file](#zip-file) or [GitHub Gist](#github-gist).
+This section explains the various sources types available for Apify Actors and how to deploy an Actor from Github using CLI or Gist. Apify Actors supporst four source types:
+
+- [Web IDE](#web-ide)
+- [Git repository](#git-repository)
+- [Zip file](#zip-file)
+- [GitHub Gist](#github-gist)
 
-## Web IDE {#web-ide}
+## Web IDE
 
-This option is used by default when your Actor's source code is hosted on the Apify platform. You can use our Web IDE to preview and update your Actor's source code and browse its files and directories. This is especially helpful when you need to make fast updates to your source code or README or when you want to directly test the [**INPUT_SCHEMA.json**](../actor_definition/input_schema/index.md) on the Apify platform.
+This is the default option when your Actor's source code is hosted on the Apify platform. It offers quick previews and updates to your source code, easy file and directory browsing, and direct testing of the [`INPUT_SCHEMA.json`](/platform/actors/development/actor-definition/input-schema) on the Apify platform.
 
-The only required file is **Dockerfile**, and all other files depend on your Dockerfile settings. By default, Apify's custom NodeJS Dockerfile is used, which requires a **main.js** file containing your source code and a **package.json** file containing package configurations for [NPM](https://www.npmjs.com/).
+A `Dockerfile` is mandatory for all Actors. When using the default NodeJS Dockerfile, you'll typically need `main.js` for your source code and `package.json` for [NPM](https://www.npmjs.com/) package configurations.
 
-See [Dockerfile](../actor_definition/docker.md#custom-dockerfile) and [base Docker images](../actor_definition/docker.md#base-docker-images) for more information about creating your own Dockerfile and using Apify's prepared base images.
+For more information on creating custom Dockersfiles or using Apify's base images, refer to the [Dockerfile](/platform/actors/development/actor-definition/dockerfile#custom-dockerfile) and [base Docker images](/platform/actors/development/actor-definition/dockerfile#base-docker-images) documentation.
 
-## [](#git-repository)Git repository
+## Git repository
 
 <iframe width="560" height="315" src="https://www.youtube-nocookie.com/embed/NEzT_p_RE1Q" title="YouTube video player" frameborder="0" allow="accelerometer; autoplay; clipboard-write; encrypted-media; gyroscope; picture-in-picture; web-share" allowfullscreen></iframe>
 
-If the Actor's source code is hosted externally in a Git repository, it can consist of multiple files and directories, use its own **Dockerfile** to control the build process (see [Custom Dockerfile](../actor_definition/docker.md#custom-dockerfile) for details) and have a user description in store fetched from the <strong>README.md</strong> file. The location of the repository is specified by the **Git URL** setting, which can be an **https**, **git** or **ssh** URL.
+Hosting your Actor's source code in a Git repository allows for multiple files and directories, a custom `Dockerfile` for build process control, and a user description fetched from `README.md`. Specify the repository location using the **Git URL** setting with `https`, `git`, or `ssh` protocols.
+
+To deploy an Actor from GitHub, set the **Source Type** to **Git repository** and enter the GitHub repository URL in the **Git URL** field. You can optionally specify a branch or tag by adding a URL fragmend (e.g., `#develop`).
+
+To use a specific directory, add it after the branch/tag, separated by a colon (e.g., `#develop:some/dir`)
+
+:::note GitHub integration
+
+You can easily set up an integration where the Actor is automatically rebuilt on every commit to the Git repository. For more details, see [GitHub integration](/platform/integrations/github).
+
+:::
+
+### Private repositories
+
+When using a private Git repository for your Actor's source code, you need to configure a deployment key. This key grants Apify secure, read-only access to your repository.
+
+:::note What are deployment keys
+
+Deployment keys are unique SSH keys that allow Apify to clone and build your Actor from a private repository.
+
+:::
 
-[//]: # (TODO: It's pretty outdated, we should probably update the Actor too)
-To help you get started quickly, you can use the [apify/quick-start](https://apify.com/apify/quick-start) Actor which contains all the boilerplate necessary when creating a new Actor hosted on Git. The source code is available on [GitHub](https://github.com/apify/actor-quick-start).
+#### How to configure deployment keys
 
-To specify a Git branch or tag to check out, add a URL fragment to the URL. For example, to check out the **develop** branch, specify a URL such as `https://github.com/jancurn/some-actor.git#develop`.
+To configure the deployment key for your Actor's source code you need to:
 
-Optionally, the second part of the fragment in the Git URL (separated by a colon) specifies the directory from which the Actor will be built (and where the `.actor`) folder is located. For example, `https://github.com/jancurn/some-actor.git#develop:some/dir` will check out the **develop** branch and set **some/dir** as the root directory of the Actor.
+1. In your Actor's settings, find the **Git URL** input field
+2. Click the **deployment key** link below the input field
+3. Follow the instruction to add the key to your Git hosting service.
 
-Note that you can easily set up an integration where the Actor is automatically rebuilt on every commit to the Git repository. For more details, see [GitHub integration](../../../integrations/programming/github.md).
+![Deployment keys instruction window](./images/deployment-keys.png)
 
-### [](#private-repositories)Private repositories
+By using deployment keys, you enable secure, automated builds of your Actor from private repositories.
 
-If your source code is hosted in a private Git repository, then you need to configure the deployment key. The deployment key is different for each Actor and may be used only once for the Git hosting of your choice (GitHub, Bitbucket, GitLab, etc.).
+:::info Key usage limitations
 
-To obtain the key click at the **deployment key** link under the **Git URL** text input and follow the instructions there.
+Remember that each key can only be used once per Git hosting service (GitHub, Bitbucket, GitLab)
 
-### [](#actor-monorepos)Actor monorepos
+:::
 
-By default, the context directory for the Docker build is the directory pointed to by the **Git URL** (or the repository root if no directory is specified). If you want to use a different directory for the Docker context, you can use the `dockerContextDir` property in the [Actor definition](../actor_definition/actor_json.md). This is useful for sharing code between multiple Actors in the same repository.
+### Actor monorepos
 
-If you want to have multiple Actors in a single repository using shared code also located in the repository, you can set `dockerContextDir` to the path to the folder which contains the Actor's source and the shared code, and then, in the Dockerfile, copy both the Actor's source and the shared code into the Docker image.
+To manage multiple Actors in a single repository, use the `dockerContextDix` property in the [Actor definition](/platform/actors/development/actor-definition/actor-json) to set the Docker context directory (if not provided then the repository root is used). In the Dockerfile, copy both the Actor's source and any shared code into the Docker image.
 
 To enable sharing Dockerfiles between multiple Actors, the Actor build process passes the `ACTOR_PATH_IN_DOCKER_CONTEXT` build arg to the Docker build.
 It contains the relative path from `dockerContextDir` to the directory selected as the root of the Actor in the Apify Console (the "directory" part of the Actor's git URL).
 
-An example Actor monorepo is shown in the [`apify/actor-monorepo-example`](https://github.com/apify/actor-monorepo-example) repository. To build Actors from this monorepo, you would set the source URL (including branch name and folder) as `https://github.com/apify/actor-monorepo-example#main:actors/javascript-actor` and `https://github.com/apify/actor-monorepo-example#main:actors/typescript-actor` respectively.
+For an example, see the [`apify/actor-monorepo-example`](https://github.com/apify/actor-monorepo-example) repository. To build Actors from this monorepo, you would set the source URL (including branch name and folder) as `https://github.com/apify/actor-monorepo-example#main:actors/javascript-actor` and `https://github.com/apify/actor-monorepo-example#main:actors/typescript-actor` respectively.
 
-## [](#zip-file)Zip file
+## Zip file
 
-The source code for the Actor can also be located in a Zip archive hosted on an external URL. This option enables integration with arbitrary source code or continuous integration systems. Similarly, as with the [Git repository](#git-repository), the source code can consist of multiple files and directories and can contain a custom **Dockerfile**. The Actor description is taken from the <strong>README.md</strong>. If you don't use a [custom Dockerfile](../actor_definition/docker.md#custom-dockerfile), the root file of your application must be named `main.js`.
+Actors can also use source code from a Zip archive hosted on an external URL. This option supports multiple files and directories, allows for custom `Dockerfile`, and uses `README.md` for the Actor description. If not using a [custom Dockerfile](../actor_definition/docker.md#custom-dockerfile), ensure your main applicat file is named `main.js`.
 
-## [](#github-gist)GitHub Gist
+:::note Automatic use of ZIP file
 
-Sometimes having a full Git repository or a hosted Zip file might be overly complicated for your small project, but you still want to have the source code in multiple files. In this case, you can simply put your source code into a [GitHub Gist](https://gist.github.com/). For example:
+This source type is used automatically when you are using Apify-CLI and the source size exceeds `3MB`.
 
-[//]: # (TODO: It's pretty outdated, we should probably update the Actor too)
-https://gist.github.com/jancurn/2dbe83fea77c439b1119fb3f118513e7
+:::
 
-Then set the **Source Type** to **GitHub Gist** and paste the Gist URL as follows:
+## GitHub Gist
 
-![GitHub Gist settings](./images/source-types-gist-settings.png)
+For smaller projects, GitHub Gist offers a simpler alternative to full Git repositories or hosted Zip files. To use a GitHub Gist, create your Gist at [https://gist.github.com/](https://gist.github.com/), set the **Source type** to **GitHub Gist**, and paste the Gist URL in the provided field.
 
-Note that the example Actor is available in the Apify Store as [apify/example-github-gist](https://apify.com/apify/example-github-gist).
+Like other source types, Gists can include multiple files, directories, and a custom Dockersfile. The Actor description is taken from `README.md`.
 
-Similarly, as with the [Git repository](#git-repository), the source code can consist of multiple files and directories and can contain a custom **Dockerfile**. The Actor description is taken from the <strong>README.md</strong>. If you don't use a [custom Dockerfile](../actor_definition/docker.md#custom-dockerfile), the root file of your application must be named `main.js`.
+By understanding these source types, you can choose the most appropriate option for hosting and deploying your Apify Actors. Each type offers unique advantages, allowing you to select the best fit for your project's size, complexity, and collaboration needs.