Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

docs: runs and builds updates #884

Merged
merged 3 commits into from
Mar 18, 2024
Merged
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
39 changes: 19 additions & 20 deletions sources/platform/actors/running/runs_and_builds.md
Original file line number Diff line number Diff line change
Expand Up @@ -11,22 +11,21 @@

## Builds

An Actor is a combination of source code and various settings in a Docker container. To be able to run, it first needs to be built. An Actor build consists of the source code built as a Docker image, making the Actor ready to run on the Apify platform.
An Actor is a combination of source code and various settings in a Docker container. To run, it needs to be built. An Actor build consists of the source code built as a Docker image, making the Actor ready to run on the Apify platform.

Check warning on line 14 in sources/platform/actors/running/runs_and_builds.md

View workflow job for this annotation

GitHub Actions / vale

[vale] sources/platform/actors/running/runs_and_builds.md#L14

[write-good.Passive] 'be built' may be passive voice. Use active voice if you can.
Raw output
{"message": "[write-good.Passive] 'be built' may be passive voice. Use active voice if you can.", "location": {"path": "sources/platform/actors/running/runs_and_builds.md", "range": {"start": {"line": 14, "column": 106}}}, "severity": "WARNING"}

:::info What is Docker image?
A Docker image is a lightweight, standalone, executable package of software that includes everything needed to run an application: code, runtime, system tools, system libraries, and settings.
<https://www.docker.com/resources/what-container/>
A Docker image is a lightweight, standalone, executable package of software that includes everything needed to run an application: code, runtime, system tools, system libraries, and settings. For more information visit Docker's [site](https://www.docker.com/resources/what-container/).
:::

With every new version of an Actor, a new build gets created. Each Actor build has its number (for example, **1.2.34**), and some of the builds are tagged for easier use (for example, **latest** or **beta**). When running an Actor, you can choose what build you want to run by selecting a tag or number in the run options.
With every new version of an Actor, a new build is created. Each Actor build has its number (for example, **1.2.34**), and some builds are tagged for easier use (for example, _latest_ or _beta_). When running an Actor, you can choose what build you want to run by selecting a tag or number in the run options.

Check warning on line 20 in sources/platform/actors/running/runs_and_builds.md

View workflow job for this annotation

GitHub Actions / vale

[vale] sources/platform/actors/running/runs_and_builds.md#L20

[write-good.Passive] 'is created' may be passive voice. Use active voice if you can.
Raw output
{"message": "[write-good.Passive] 'is created' may be passive voice. Use active voice if you can.", "location": {"path": "sources/platform/actors/running/runs_and_builds.md", "range": {"start": {"line": 20, "column": 49}}}, "severity": "WARNING"}

Check warning on line 20 in sources/platform/actors/running/runs_and_builds.md

View workflow job for this annotation

GitHub Actions / vale

[vale] sources/platform/actors/running/runs_and_builds.md#L20

[write-good.Passive] 'are tagged' may be passive voice. Use active voice if you can.
Raw output
{"message": "[write-good.Passive] 'are tagged' may be passive voice. Use active voice if you can.", "location": {"path": "sources/platform/actors/running/runs_and_builds.md", "range": {"start": {"line": 20, "column": 136}}}, "severity": "WARNING"}

![Actor run options](./images/runs_and_builds/actor-run-options.png)

Each build may have different features, input, or output. By fixing the build to an exact version, you can ensure that you won't be affected by a breaking change in a new Actor version. But on the other hand, you lose updates.
Each build may have different features, input, or output. By fixing the build to an exact version, you can ensure that you won't be affected by a breaking change in a new Actor version. However, you will lose updates.

Check warning on line 24 in sources/platform/actors/running/runs_and_builds.md

View workflow job for this annotation

GitHub Actions / vale

[vale] sources/platform/actors/running/runs_and_builds.md#L24

[write-good.Passive] 'be affected' may be passive voice. Use active voice if you can.
Raw output
{"message": "[write-good.Passive] 'be affected' may be passive voice. Use active voice if you can.", "location": {"path": "sources/platform/actors/running/runs_and_builds.md", "range": {"start": {"line": 24, "column": 130}}}, "severity": "WARNING"}

Check warning on line 24 in sources/platform/actors/running/runs_and_builds.md

View workflow job for this annotation

GitHub Actions / vale

[vale] sources/platform/actors/running/runs_and_builds.md#L24

[write-good.TooWordy] 'However' is too wordy.
Raw output
{"message": "[write-good.TooWordy] 'However' is too wordy.", "location": {"path": "sources/platform/actors/running/runs_and_builds.md", "range": {"start": {"line": 24, "column": 187}}}, "severity": "WARNING"}

## Runs

When you start an Actor, an Actor run gets created. An Actor run is a Docker container created from the build's Docker image with dedicated resources (CPU, memory, disk space). For more on this topic, see [usage and resources](./usage_and_resources.md).
When you start an Actor, an Actor run is created. An Actor run is a Docker container created from the build's Docker image with dedicated resources (CPU, memory, disk space). For more on this topic, see [Usage and resources](./usage_and_resources.md).

Check warning on line 28 in sources/platform/actors/running/runs_and_builds.md

View workflow job for this annotation

GitHub Actions / vale

[vale] sources/platform/actors/running/runs_and_builds.md#L28

[write-good.Passive] 'is created' may be passive voice. Use active voice if you can.
Raw output
{"message": "[write-good.Passive] 'is created' may be passive voice. Use active voice if you can.", "location": {"path": "sources/platform/actors/running/runs_and_builds.md", "range": {"start": {"line": 28, "column": 39}}}, "severity": "WARNING"}

Each run has its own (default) [storages](../../storage) assigned, which it may but not necessarily need to use:

Expand All @@ -44,13 +43,13 @@

|Name|Origin|
|:---|:---|
|DEVELOPMENT|manually from Apify Console in Development mode (own Actor)|
|WEB|manually from Apify Console in "normal" mode (someone else's Actor or task)|
|API|from API|
|CLI|from Apify CLI|
|SCHEDULER|using a Schedule|
|WEBHOOK|using a webhook|
|ACTOR|from another Actor run|
|DEVELOPMENT|Manually from Apify Console in Development mode (own Actor)|
|WEB|Manually from Apify Console in "normal" mode (someone else's Actor or task)|
|API|From API|
|CLI|From Apify CLI|
|SCHEDULER|Using a Schedule|
|WEBHOOK|Using a webhook|
|ACTOR|From another Actor run|

## Lifecycle

Expand Down Expand Up @@ -81,23 +80,23 @@
---

| Status | Type | Description |
|------------|--------------|---------------------------------------------|
|:-----------|:-------------|:--------------------------------------------|
| READY | initial | Started but not allocated to any worker yet |
| RUNNING | transitional | Executing on a worker machine |
| SUCCEEDED | terminal | Finished successfully |
| FAILED | terminal | Run failed |
| TIMING-OUT | transitional | Timing out now |
| TIMED-OUT | terminal | Timed out |
| ABORTING | transitional | Being aborted by user |
| ABORTED | terminal | Aborted by user |
| ABORTING | transitional | Being aborted by the user |
| ABORTED | terminal | Aborted by the user |


### Aborting runs

You can abort runs with the statuses **READY**, **RUNNING**, or **TIMING-OUT** in two ways:

- **Immediately** - this is the default option. The Actor process is killed immediately with no grace period.
- **Gracefully** - the Actor run receives a signal about aborting via the `aborting` event and is granted a 30-second window to finish in-progress tasks before getting aborted. This is helpful in cases where you plan to resurrect the run later because it gives the Actor a chance to persist its state. When resurrected, the Actor can restart where it left off.
- _Immediately_ - this is the default option. The Actor process is killed immediately with no grace period.

Check warning on line 98 in sources/platform/actors/running/runs_and_builds.md

View workflow job for this annotation

GitHub Actions / vale

[vale] sources/platform/actors/running/runs_and_builds.md#L98

[write-good.Weasel] 'Immediately' is a weasel word!
Raw output
{"message": "[write-good.Weasel] 'Immediately' is a weasel word!", "location": {"path": "sources/platform/actors/running/runs_and_builds.md", "range": {"start": {"line": 98, "column": 4}}}, "severity": "WARNING"}

Check warning on line 98 in sources/platform/actors/running/runs_and_builds.md

View workflow job for this annotation

GitHub Actions / vale

[vale] sources/platform/actors/running/runs_and_builds.md#L98

[write-good.Passive] 'is killed' may be passive voice. Use active voice if you can.
Raw output
{"message": "[write-good.Passive] 'is killed' may be passive voice. Use active voice if you can.", "location": {"path": "sources/platform/actors/running/runs_and_builds.md", "range": {"start": {"line": 98, "column": 65}}}, "severity": "WARNING"}

Check warning on line 98 in sources/platform/actors/running/runs_and_builds.md

View workflow job for this annotation

GitHub Actions / vale

[vale] sources/platform/actors/running/runs_and_builds.md#L98

[write-good.Weasel] 'immediately' is a weasel word!
Raw output
{"message": "[write-good.Weasel] 'immediately' is a weasel word!", "location": {"path": "sources/platform/actors/running/runs_and_builds.md", "range": {"start": {"line": 98, "column": 75}}}, "severity": "WARNING"}
- _Gracefully_ - the Actor run receives a signal about aborting via the `aborting` event and is granted a 30-second window to finish in-progress tasks before getting aborted. This is helpful in cases where you plan to resurrect the run later because it gives the Actor a chance to persist its state. When resurrected, the Actor can restart where it left off.

Check warning on line 99 in sources/platform/actors/running/runs_and_builds.md

View workflow job for this annotation

GitHub Actions / vale

[vale] sources/platform/actors/running/runs_and_builds.md#L99

[Microsoft.Adverbs] Consider removing 'Gracefully'.
Raw output
{"message": "[Microsoft.Adverbs] Consider removing 'Gracefully'.", "location": {"path": "sources/platform/actors/running/runs_and_builds.md", "range": {"start": {"line": 99, "column": 4}}}, "severity": "WARNING"}

Check warning on line 99 in sources/platform/actors/running/runs_and_builds.md

View workflow job for this annotation

GitHub Actions / vale

[vale] sources/platform/actors/running/runs_and_builds.md#L99

[write-good.Weasel] 'Gracefully' is a weasel word!
Raw output
{"message": "[write-good.Weasel] 'Gracefully' is a weasel word!", "location": {"path": "sources/platform/actors/running/runs_and_builds.md", "range": {"start": {"line": 99, "column": 4}}}, "severity": "WARNING"}

Check warning on line 99 in sources/platform/actors/running/runs_and_builds.md

View workflow job for this annotation

GitHub Actions / vale

[vale] sources/platform/actors/running/runs_and_builds.md#L99

[write-good.Passive] 'is granted' may be passive voice. Use active voice if you can.
Raw output
{"message": "[write-good.Passive] 'is granted' may be passive voice. Use active voice if you can.", "location": {"path": "sources/platform/actors/running/runs_and_builds.md", "range": {"start": {"line": 99, "column": 94}}}, "severity": "WARNING"}

You can abort a run in Apify Console using the **Abort** button or via API using the [Abort run](/api/v2#/reference/actor-runs/abort-run/abort-run) endpoint.

Expand All @@ -123,9 +122,9 @@

### Data retention

All **Actor runs** and default storages (key-value store, dataset, request queue) are deleted after the data retention period, based on your [subscription plan](https://apify.com/pricing).
All **Actor runs** and default storages (Key-value store, Dataset, Request queue) are deleted after the data retention period, based on your [subscription plan](https://apify.com/pricing).

Check warning on line 125 in sources/platform/actors/running/runs_and_builds.md

View workflow job for this annotation

GitHub Actions / vale

[vale] sources/platform/actors/running/runs_and_builds.md#L125

[write-good.Passive] 'are deleted' may be passive voice. Use active voice if you can.
Raw output
{"message": "[write-good.Passive] 'are deleted' may be passive voice. Use active voice if you can.", "location": {"path": "sources/platform/actors/running/runs_and_builds.md", "range": {"start": {"line": 125, "column": 83}}}, "severity": "WARNING"}

**Actor builds** are deleted only when they are **not tagged** and have not been used for over 90 days.
**Actor builds** are deleted only when they are _not tagged_ and have not been used for over 90 days.

Check warning on line 127 in sources/platform/actors/running/runs_and_builds.md

View workflow job for this annotation

GitHub Actions / vale

[vale] sources/platform/actors/running/runs_and_builds.md#L127

[write-good.Passive] 'are deleted' may be passive voice. Use active voice if you can.
Raw output
{"message": "[write-good.Passive] 'are deleted' may be passive voice. Use active voice if you can.", "location": {"path": "sources/platform/actors/running/runs_and_builds.md", "range": {"start": {"line": 127, "column": 18}}}, "severity": "WARNING"}

Check warning on line 127 in sources/platform/actors/running/runs_and_builds.md

View workflow job for this annotation

GitHub Actions / vale

[vale] sources/platform/actors/running/runs_and_builds.md#L127

[write-good.Weasel] 'only' is a weasel word!
Raw output
{"message": "[write-good.Weasel] 'only' is a weasel word!", "location": {"path": "sources/platform/actors/running/runs_and_builds.md", "range": {"start": {"line": 127, "column": 30}}}, "severity": "WARNING"}

Check warning on line 127 in sources/platform/actors/running/runs_and_builds.md

View workflow job for this annotation

GitHub Actions / vale

[vale] sources/platform/actors/running/runs_and_builds.md#L127

[write-good.Passive] 'been used' may be passive voice. Use active voice if you can.
Raw output
{"message": "[write-good.Passive] 'been used' may be passive voice. Use active voice if you can.", "location": {"path": "sources/platform/actors/running/runs_and_builds.md", "range": {"start": {"line": 127, "column": 75}}}, "severity": "WARNING"}

## Sharing

Expand Down