Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
4 changes: 2 additions & 2 deletions docs/actor/build.md
Original file line number Diff line number Diff line change
Expand Up @@ -6,9 +6,9 @@ title: Build

Before the actor can be run, it first needs to be built. The build effectively creates a snapshot of a specific version of the actor's settings such as the [Source code]({{@link actor/source_code.md}}) and [Environment variables]({{@link actor/run.md}}#run-env-vars), and creates a Docker image that contains everything the actor needs for its run, including necessary NPM packages, web browsers, etc.

Each build is assigned a unique build number of the form `MAJOR.MINOR.BUILD` (e.g. `1.2.345`), where `MAJOR.MINOR` corresponds to the actor version number (see [Versions](#versions)) and `BUILD` is an automatically-incremented number starting at `1`.
Each build is assigned a unique build number of the form `MAJOR.MINOR.BUILD` (e.g. `1.2.345`), where `MAJOR.MINOR` corresponds to the actor version number (see [Versioning]({{@link actor/source_code.md#versioning}})) and `BUILD` is an automatically-incremented number starting at `1`.

By default, the build has a timeout of 300 seconds and consumes 1024 MB of memory from the user's memory limit. See the [Resource limits](#resource-limits) section for more details.
By default, the build has a timeout of 300 seconds and consumes 1024 MB of memory from the user's memory limit. See the [Resource limits]({{@link actor/run.md#resource-limits}}) section for more details.

### [](#build-tags)Tags

Expand Down
8 changes: 4 additions & 4 deletions docs/actor/examples.md
Original file line number Diff line number Diff line change
Expand Up @@ -4,7 +4,7 @@ title: Examples

## [](#examples)Examples

This section provides examples of actors using various features of the Apify platform. All these examples and many more are also available in the [store](/store?type=acts&search=user%3Aapify%20example).
This section provides examples of actors using various features of the Apify platform. All these examples and many more are also available in the [store](https://apify.com/store?type=acts&search=user%3Aapify%20example).

### [](#examples-puppeteer)Puppeteer

Expand Down Expand Up @@ -52,11 +52,11 @@ This example demonstrates how to use headless Chrome with Puppeteer to open a we
console.log(`- https://api.apify.com/v2/key-value-stores/${storeId}/records/page.pdf`);
});

The code above uses the [`launchPuppeteer()`](https://sdk.apify.com/docs/api/apify#module_Apify.launchPuppeteer) function provided by the [`apify`](https://sdk.apify.com/) NPM package. The function launches Puppeteer with several settings that enable it to run in an actor. Note that the actor needs to have **Base image** set to [Node.js 10 + Puppeteer on Debian](#base-images) in order to run Puppeteer.
The code above uses the [`launchPuppeteer()`](https://sdk.apify.com/docs/api/apify#module_Apify.launchPuppeteer) function provided by the [`apify`](https://sdk.apify.com/) NPM package. The function launches Puppeteer with several settings that enable it to run in an actor. Note that the actor needs to have **Base image** set to [Node.js 10 + Puppeteer on Debian]({{@link actor/build.md#base-images}}) in order to run Puppeteer.

### [](#examples-dockerfile)Custom Dockerfile

This example demonstrates how to create an actor written in PHP using a custom Dockerfile. For more information, see the [Custom Dockerfile](#custom-dockerfile) section. The Dockerfile is based on the [`php:7.0-cli` _open_in_new_](https://hub.docker.com/_/php/) Docker image that contains everything needed to run PHP in a terminal.
This example demonstrates how to create an actor written in PHP using a custom Dockerfile. For more information, see the [Custom Dockerfile]({{@link actor/source_code.md#custom-dockerfile}}) section. The Dockerfile is based on the [`php:7.0-cli` _open_in_new_](https://hub.docker.com/_/php/) Docker image that contains everything needed to run PHP in a terminal.

`Dockerfile` contains only two commands. The first copies source code into the container and the second executes `main.php`.

Expand All @@ -83,7 +83,7 @@ The actor can be found in the Apify store as [apify/example-php](https://apify.c

### [](#examples-state-persistence)State persistence

This actor demonstrates how to persist a state, so that on restart the actor can continue where it left off. For more information, see the [State persistence](#state-persistence) section. The actor simply counts from one up. In each run it prints one number. Its state (counter position) is stored in a named [key-value store](/docs/storage#key-value-store) called `example-counter`. You will find it in the [Storage](https://my.apify.com/key-value-stores) section of the app after you run the actor.
This actor demonstrates how to persist a state, so that on restart the actor can continue where it left off. For more information, see the [State persistence]({{@link actor/run.md#state-persistence}}) section. The actor simply counts from one up. In each run it prints one number. Its state (counter position) is stored in a named [key-value store]({{@link storage/key_value_store.md}}) called `example-counter`. You will find it in the [Storage](https://my.apify.com/key-value-stores) section of the app after you run the actor.

The actor can be found in the Apify store as [apify/example-counter](https://apify.com/apify/example-counter).

Expand Down
2 changes: 1 addition & 1 deletion docs/actor/limits.md
Original file line number Diff line number Diff line change
Expand Up @@ -4,7 +4,7 @@ title: Limits

## [](#limits)Limits

This section describes various resource limits of the Apify platform. Do you need to increase any of them? Please [contact us](/contact).
This section describes various resource limits of the Apify platform. Do you need to increase any of them? Please [contact us](https://apify.com/contact).

|Description|Value|
|--- |--- |
Expand Down
4 changes: 2 additions & 2 deletions docs/actor/publishing.md
Original file line number Diff line number Diff line change
Expand Up @@ -4,10 +4,10 @@ title: Publishing

## [](#publishing)Publishing

Actors can be private or public. Private actors can only be accessed and started by their owner, while public actor are shown in the [store](/store) and can be run by anyone. Each public actor has a globally unique identifier that consists of the owner's username and the actor name, e.g. [apify/hello-world](https://apify.com/apify/hello-world).
Actors can be private or public. Private actors can only be accessed and started by their owner, while public actor are shown in the [store](https://apify.com/store) and can be run by anyone. Each public actor has a globally unique identifier that consists of the owner's username and the actor name, e.g. [apify/hello-world](https://apify.com/apify/hello-world).

To publish your actor, go to **Settings → Permissions** on the actor detail page and click the **Publish** button. You'll need to have a username set. This can be done on the [Profile](https://my.apify.com/account#/profile) page.

The short actor description shown in the store is taken from **Settings → Description**. Additionally, if the actor's source code is hosted in a [Git repository](#source-git-repo), [Zip file](#source-tarball) or [GitHub Gist](#source-github-gist), you can add a long description in [Markdown _open_in_new_](https://github.com/adam-p/markdown-here/wiki/Markdown-Cheatsheet) language to the `README.md` or `README` files in the root of the source code directory. To see an example of how this looks, go to [apify/web-scraper](https://apify.com/apify/web-scraper).
The short actor description shown in the store is taken from **Settings → Description**. Additionally, if the actor's source code is hosted in a [Git repository]({{@link actor/source_code.md#source-git-repo}}), [Zip file]({{@link actor/source_code.md#source-tarball}}) or [GitHub Gist]({{@link actor/source_code.md#source-github-gist}}), you can add a long description in [Markdown _open_in_new_](https://github.com/adam-p/markdown-here/wiki/Markdown-Cheatsheet) language to the `README.md` or `README` files in the root of the source code directory. To see an example of how this looks, go to [apify/web-scraper](https://apify.com/apify/web-scraper).

**IMPORTANT:** Note that if your actor is public and used by other people, its usage is not charged towards your account. The user running the actor is always the one who pays for the computational resources consumed by an actor's execution.
4 changes: 2 additions & 2 deletions docs/actor/quick_start.md
Original file line number Diff line number Diff line change
Expand Up @@ -19,7 +19,7 @@ Click **Quick run** to build and run your actor. After the run is finished you s

Congratulations, you have successfully created and run your first actor!

Let's try something little more complicated. We will change the actor to accept input and generate output (see [Input and output](#input-output) for more details):
Let's try something little more complicated. We will change the actor to accept input and generate output (see [Input and output]({{@link actor/run.md#input-output}}) for more details):

const Apify = require('apify');

Expand Down Expand Up @@ -54,4 +54,4 @@ For more complicated actors, you'll probably prefer to host the source code on G
4. Paste the Git repo link to **Git URL**, save changes and build your actor.
5. That's it, now you can develop your actor locally on your computer and run it in the Apify cloud!

For more information, go to the [Git repository](#source-git-repo) section.
For more information, go to the [Git repository]({{@link actor/source_code.md#source-git-repo}}) section.
26 changes: 13 additions & 13 deletions docs/actor/run.md
Original file line number Diff line number Diff line change
Expand Up @@ -21,11 +21,11 @@ The following table describes the run settings:

The owner of the actor can specify default values for all the above settings in the **Default run configuration** section in the app. If the actor caller does not specify a particular setting, the default value is used.

The actor can also be invoked using the Apify API by sending a HTTP POST request to the [Run actor](/docs/api/v2/#/reference/actors/run-collection/run-actor) API endpoint, such as:
The actor can also be invoked using the Apify API by sending a HTTP POST request to the [Run actor](https://apify.com/docs/api/v2/#/reference/actors/run-collection/run-actor) API endpoint, such as:

https://api.apify.com/v2/acts/apify~hello-world/runs?token=<YOUR_API_TOKEN>

The actor's input and its content type can be passed as a payload of the POST request and additional options can be specified using URL query parameters. For more details, see the [Run actor](/docs/api/v2/#/reference/actors/run-collection/run-actor) section in the API reference.
The actor's input and its content type can be passed as a payload of the POST request and additional options can be specified using URL query parameters. For more details, see the [Run actor](https://apify.com/docs/api/v2/#/reference/actors/run-collection/run-actor) section in the API reference.

Actors can also be invoked programmatically from other actors using the [`call()`](https://sdk.apify.com/docs/api/apify#module_Apify.call) function provided by the [`apify`](https://sdk.apify.com/) NPM package. For example:

Expand All @@ -34,19 +34,19 @@ Actors can also be invoked programmatically from other actors using the [`call()

The newly started actor runs under the same user account as the initial actor and therefore all resources consumed are charged to the same user account. This allows more complex actors to be built using simpler actors built and owned by other users.

Internally, the `call()` function takes the user's API token from the `APIFY_TOKEN` environment variable, then it invokes the [Run actor](/docs/api/v2/#/reference/actors/run-collection/run-actor) API endpoint, waits for the actor to finish and reads its output using the [Get record](/docs/api/v2/#/reference/key-value-stores/record/get-record) API endpoint.
Internally, the `call()` function takes the user's API token from the `APIFY_TOKEN` environment variable, then it invokes the [Run actor](https://apify.com/docs/api/v2/#/reference/actors/run-collection/run-actor) API endpoint, waits for the actor to finish and reads its output using the [Get record](https://apify.com/docs/api/v2/#/reference/key-value-stores/record/get-record) API endpoint.

### [](#input-output)Input and output

As demonstrated in the hello world example above, actors can accept input and generate output. Both input and output are stored in a key-value store that is created when the actor is started, under the `INPUT` and `OUTPUT` keys, respectively. Note that the actor can store other values under arbitrary keys, for example crawling results or screenshots of web pages.

The key-value store associated with the actor run can be conveniently accessed using the [`getValue()`](https://sdk.apify.com/docs/api/apify#module_Apify.getValue) and [`setValue()`](https://sdk.apify.com/docs/api/apify#module_Apify.setValue) functions provided by the `apify` NPM package. Internally, these functions read the ID of the key-value store from the `APIFY_DEFAULT_KEY_VALUE_STORE_ID` environment variable and then access the store using the Apify API. For more details about the key-value stores, go to the [Storage](#storage) section.
The key-value store associated with the actor run can be conveniently accessed using the [`getValue()`](https://sdk.apify.com/docs/api/apify#module_Apify.getValue) and [`setValue()`](https://sdk.apify.com/docs/api/apify#module_Apify.setValue) functions provided by the `apify` NPM package. Internally, these functions read the ID of the key-value store from the `APIFY_DEFAULT_KEY_VALUE_STORE_ID` environment variable and then access the store using the Apify API. For more details about the key-value stores, go to the [Storage]({{@link storage/index.md}}) section.

The input can be passed to the actor either manually in the Console or using a POST payload when running the actor using API. See [Run](#run) section for details.
The input can be passed to the actor either manually in the Console or using a POST payload when running the actor using API. See [Run]({{@link actor/run.md}}) section for details.

### [](#run-env-vars)Environment variables

Aside from [custom environment variables](#source-env-vars), the actor's process has several environment variables set to provide it with context:
Aside from [custom environment variables]({{@link actor/source_code.md#source-env-vars}}), the actor's process has several environment variables set to provide it with context:

|||
|--- |--- |
Expand All @@ -66,8 +66,8 @@ Aside from [custom environment variables](#source-env-vars), the actor's process
|`APIFY_TIMEOUT_AT`|Date when the actor will time out.|
|`APIFY_TOKEN`|The API token of the user who started the actor.|
|`APIFY_USER_ID`|ID of the user who started the actor. Note that it might be different than the owner of the actor.|
|`APIFY_CONTAINER_PORT`|TCP port on which the actor can start a HTTP server to receive messages from the outside world. See [Container web server](#container-web-server) section for more details.|
|`APIFY_CONTAINER_URL`|A unique public URL under which the actor run web server is accessible from the outside world. See [Container web server](#container-web-server) section for more details.|
|`APIFY_CONTAINER_PORT`|TCP port on which the actor can start a HTTP server to receive messages from the outside world. See [Container web server]({{@link actor/run.md#container-web-server}}) section for more details.|
|`APIFY_CONTAINER_URL`|A unique public URL under which the actor run web server is accessible from the outside world. See [Container web server]({{@link actor/run.md#container-web-server}}) section for more details.|


Dates are always in the UTC timezone and are represented in simplified extended ISO format ([ISO 8601 _open_in_new_](https://en.wikipedia.org/wiki/ISO_8601)), e.g. `2017-10-13T14:23:37.281Z`
Expand All @@ -78,7 +78,7 @@ To access environment variables in Node.js, use the `process.env` object, for ex

### [](#resource-limits)Resource limits

Actors run inside a Docker container whose resources are limited. When invoking the actor, the caller has to specify the amount of memory allocated for the actor. Additionally, each user has a certain total limit of memory for running actors. The sum of memory allocated for all running actors and builds needs to fit into this limit, otherwise the user cannot start a new actor. For more details, see [Limits](#limits).
Actors run inside a Docker container whose resources are limited. When invoking the actor, the caller has to specify the amount of memory allocated for the actor. Additionally, each user has a certain total limit of memory for running actors. The sum of memory allocated for all running actors and builds needs to fit into this limit, otherwise the user cannot start a new actor. For more details, see [Limits]({{@link actor/limits.md}}).

The share of CPU is computed automatically from the memory as follows: for each 4096 MB of memory, the actor gets 1 full CPU core. For other amounts of memory the number of CPU cores is computed fractionally. For example, an actor with 1024 MB of memory will have a 1/4 share of a CPU core.

Expand Down Expand Up @@ -114,17 +114,17 @@ The whole process of resurrection looks as follows:
* Updated duration will include the time when actor was not running. This does not affect compute units consumption.
* Timeout will be counted from the point when this actor run was resurrected.

Resurrection can be peformed in Apify app using the **resurrect** button or via API using the [resurrect run](/docs/api/v2#/reference/actors/resurrect-run) API endpoint.
Resurrection can be peformed in Apify app using the **resurrect** button or via API using the [resurrect run](https://apify.com/docs/api/v2#/reference/actors/resurrect-run) API endpoint.

### [](#container-web-server)Container web server

Each actor run is assigned a unique hard-to-guess URL (e.g. `http://kmdo7wpzlshygi.runs.apify.net`), which enables HTTP access to an optional web server running inside the actor run's Docker container. The URL is available in the following places:

* In the web application, on the actor run details page as the **Container URL** field.
* In the API as the `containerUrl` property of the [Run object](./api/v2#/reference/actor/run-object/get-run).
* In the API as the `containerUrl` property of the [Run object](https://apify.com/api/v2#/reference/actor/run-object/get-run).
* In the actor run's container as the `APIFY_CONTAINER_URL` environment variable.

The web server running inside the container must listen at the port defined by the `APIFY_CONTAINER_PORT` environment variable (typically 4321). If you want to use another port, simply define the `APIFY_CONTAINER_PORT` environment variable with the desired port number in your actor version configuration - see [Custom environment variable](#source-env-vars) for details.
The web server running inside the container must listen at the port defined by the `APIFY_CONTAINER_PORT` environment variable (typically 4321). If you want to use another port, simply define the `APIFY_CONTAINER_PORT` environment variable with the desired port number in your actor version configuration - see [Custom environment variable]({{@link actor/source_code.md#source-env-vars}}) for details.

The following example demonstrates how to start a simple web server in your actor:

Expand All @@ -147,4 +147,4 @@ The following example demonstrates how to start a simple web server in your acto

### [](#data-retention)Data retention

Actor run gets deleted along with its default storages (key-value store, dataset, request queue) after a data retention period which is based on [subscription plan](/pricing) of a user.
Actor run gets deleted along with its default storages (key-value store, dataset, request queue) after a data retention period which is based on [subscription plan](https://apify.com/pricing) of a user.
Loading