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.

Sign up for GitHub

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

Jump to bottom

docs: improve environment variables section #1124

Merged
merged 10 commits into from
Aug 9, 2024
Merged

docs: improve environment variables section #1124

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
10 commits
Select commit Hold shift + click to select a range
3dc8338
docs: improve environment variables section
TC-MO Jul 28, 2024
32fc0a9
remove gerund from headings
TC-MO Jul 28, 2024
e4d6c8b
add missing variables
TC-MO Aug 7, 2024
eb66244
update env var table with descriptions
TC-MO Aug 8, 2024
ae839f8
Merge branch 'master' into development-env-var
TC-MO Aug 8, 2024
bb084c8
fix broken link
TC-MO Aug 8, 2024
04dda91
add missing variable
TC-MO Aug 8, 2024
e433e41
review fixes
TC-MO Aug 9, 2024
bc4ce55
further review fixes
TC-MO Aug 9, 2024
048c600
fix typos
TC-MO Aug 9, 2024
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
124 changes: 86 additions & 38 deletions sources/platform/actors/development/programming_interface/environment_variables.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -5,7 +5,7 @@ slug: /actors/development/programming-interface/environment-variables
sidebar_position: 3
---

# Environment variables {#environment-variables}
# Environment variables in Apify

**Learn how to provide your Actor with context that determines its behavior through a plethora of pre-defined environment variables offered by the Apify SDK.**

Expand All @@ -16,59 +16,84 @@ import TabItem from '@theme/TabItem';

## System environment variables

The Actor's process has several environment variables set to provide it with context:

| Environment Variable | Description |
|------------------------------------|--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| `ACTOR_ID` | ID of the Actor. |
| `ACTOR_RUN_ID` | ID of the Actor run. |
| `ACTOR_BUILD_ID` | ID of the Actor build used in the run. |
| `ACTOR_BUILD_NUMBER` | Build number of the Actor build used in the run. |
| `ACTOR_TASK_ID` | ID of the Actor task. It's empty if Actor is run outside of any task, e.g. directly using the API. |
| `ACTOR_EVENTS_WEBSOCKET_URL` | Websocket URL where Actor may listen for events from Actor platform. See [documentation](/sdk/js/api/apify/class/PlatformEventManager) for more information. |
| `ACTOR_DEFAULT_DATASET_ID` | ID of the dataset where you can push the data. |
| `ACTOR_DEFAULT_KEY_VALUE_STORE_ID` | ID of the key-value store where the Actor's input and output data are stored. |
| `ACTOR_DEFAULT_REQUEST_QUEUE_ID` | ID of the request queue that stores and handles requests that you enqueue. |
| `ACTOR_INPUT_KEY` | The key of the record in the default key-value store that holds the Actor input. Typically it's **INPUT**, but it might be something else. |
| `ACTOR_MAX_PAID_DATASET_ITEMS` | If the Actor is paid per result, this will contain the limit set by the user on how many results they want to return. Do not return them more results because they will be only charged for the limit they set, and you might start accumulating loss. |
| `APIFY_HEADLESS` | If set to **1**, the web browsers inside the Actor should run in headless mode because there is no windowing system available. |
| `APIFY_IS_AT_HOME` | Is set to **1** if the Actor is running on Apify servers. |
| `ACTOR_MEMORY_MBYTES` | Indicates the size of memory allocated for the Actor run, in megabytes. It can be used by Actors to optimize their memory usage. |
| `APIFY_PROXY_PASSWORD` | The [Apify Proxy](../../../proxy/index.md) password of the user who started the Actor. |
| `ACTOR_STANDBY_PORT` | TCP port on which the Actor can start an HTTP server to receive messages from [Actor Standby](./actor_standby.md). |
| `ACTOR_STARTED_AT` | Date when the Actor was started. |
| `ACTOR_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. |
| `ACTOR_WEB_SERVER_PORT` | TCP port on which the Actor can start an HTTP server to receive messages from the outside world. |
| `ACTOR_WEB_SERVER_URL` | A unique public URL under which the Actor run web server is accessible from the outside world. |
Apify sets several system environment variables for each Actor run. These variables provide essential context and information about the Actor's execution environment.

Here's a table of key system environment variables:

| Environment Variable | Description |
|----------------------|-------------|
| `ACTOR_ID` | ID of the Actor. |
| `ACTOR_RUN_ID` | ID of the Actor run. |
| `ACTOR_BUILD_ID` | ID of the Actor build used in the run. |
| `ACTOR_BUILD_NUMBER` | Build number of the Actor build used in the run. |
| `ACTOR_TASK_ID` | ID of the Actor task. Empty if Actor is run outside of any task, e.g. directly using the API. |
| `ACTOR_EVENTS_WEBSOCKET_URL` | Websocket URL where Actor may listen for [events](/platform/actors/development/programming-interface/system-events) from Actor platform. |
| `ACTOR_DEFAULT_DATASET_ID` | Unique identifier for the default dataset associated with the current Actor run. |
| `ACTOR_DEFAULT_KEY_VALUE_STORE_ID` | Unique identifier for the default key-value store associated with the current Actor run. |
| `ACTOR_DEFAULT_REQUEST_QUEUE_ID` | Unique identifier for the default request queue associated with the current Actor run. |
| `ACTOR_INPUT_KEY` | Key of the record in the default key-value store that holds the [Actor input](/platform/actors/running/input-and-output#input). |
| `ACTOR_MAX_PAID_DATASET_ITEMS` | For paid-per-result Actors, the user-set limit on returned results. Do not exceed this limit. |
| `APIFY_HEADLESS` | If **1**, web browsers inside the Actor should run in headless mode (no windowing system available). |
| `APIFY_IS_AT_HOME` | Contains **1** if the Actor is running on Apify servers. |
| `ACTOR_MEMORY_MBYTES` | Size of memory allocated for the Actor run, in megabytes. Can be used to optimize memory usage or finetuning of low-level external libraries. |
| `APIFY_PROXY_PASSWORD` | Password for accessing Apify Proxy services. This password enables the Actor to utilize proxy servers on behalf of the user who initiated the Actor run. |
| `APIFY_PROXY_PORT` | TCP port number to be used for connecting to the Apify Proxy. |
| `APIFY_PROXY_STATUS_URL` | URL for retrieving proxy status information. Appending `?format=json` to this URL returns the data in JSON format for programmatic processing. |
| `ACTOR_STANDBY_PORT` | TCP port for the Actor to start an HTTP server to receive messages in the [Actor Standby](/platform/actors/development/programming-interface/standby) mode. |
| `ACTOR_STARTED_AT` | Date when the Actor was started. |
| `ACTOR_TIMEOUT_AT` | Date when the Actor will time out. |
| `APIFY_TOKEN` | API token of the user who started the Actor. |
| `APIFY_USER_ID` | ID of the user who started the Actor. May differ from the Actor owner. |
| `ACTOR_WEB_SERVER_PORT` | TCP port for the Actor to start an HTTP server on. This server can be used to receive external messages or expose monitoring and control interfaces. |
| `ACTOR_WEB_SERVER_URL` | Unique public URL for accessing the Actor run web server from the outside world. |
| `APIFY_API_PUBLIC_BASE_URL` | Public URL of the Apify API. May be used to interact with the platform programmatically. Typically set to `api.apify.com`. |
| `APIFY_DEDICATED_CPUS` | Number of CPU cores reserved for the actor, based on allocated memory. |
| `APIFY_DISABLE_OUTDATED_WARNING` | Controls the display of outdated version warnings. Set to `1` to suppress notifications about updates. |
| `APIFY_WORKFLOW_KEY` | Identifier used for grouping related runs and API calls together. |
| `APIFY_META_ORIGIN` | Specifies how an Actor run was started. Possible values are [here](/platform/actors/running/runs-and-builds#origin) |
| `APIFY_SDK_LATEST_VERSION` | Specifies the most recent release version of the Apify SDK for Javascript. Used for checking for updates. |
| `APIFY_INPUT_SECRETS_KEY_FILE` | Path to the secret key used to decryt [Secret inputs](/platform/actors/development/actor-definition/input-schema/secret-input). |
| `APIFY_INPUT_SECRETS_KEY_PASSPHRASE` | Passphrase for the input secret key specified in `APIFY_INPUT_SECRETS_KEY_FILE`. |


<!-- vale Microsoft.RangeFormat = NO -->
Dates are always in the UTC timezone and are represented in simplified extended ISO format ([ISO 8601](https://en.wikipedia.org/wiki/ISO_8601)), e.g. **2022-07-13T14:23:37.281Z**.

:::note Date format

All date-related variables use the UTC timezone and are in [ISO 8601](https://en.wikipedia.org/wiki/ISO_8601) format (e.g., _2022-07-13T14:23:37.281Z_).

:::
<!-- vale Microsoft.RangeFormat = YES -->

## Access environment variables

You can access environment variables in your code as follows:

<Tabs groupId="main">
<TabItem value="JavaScript" label="JavaScript">

In Node.js, use the `process.env` object:

```js
// To access environment variables in Node.js, use the process.env object
console.log(process.env.APIFY_USER_ID);
```

</TabItem>
<TabItem value="Python" label="Python">

In Python, use the `os.environ` dictionary:

```python
# To access environment variables in Python, use the os.environ dictionary:
import os
print(os.environ['APIFY_USER_ID'])
```

</TabItem>
</Tabs>

For convenience, rather than using environment vars directly, we provide a `Configuration` class
that allows reading and updating the Actor configuration.
## Use the `Configuration` class

For more convenient access to Actor configuration, use the [`Configuration`](/sdk/js/reference/class/Configuration) class

<Tabs groupId="main">
<TabItem value="JavaScript" label="JavaScript">
Expand Down Expand Up @@ -107,14 +132,37 @@ async def main():
</TabItem>
</Tabs>

## [](#custom-environment-variables)Custom environment variables
## Custom environment variables

Actor owners can define custom environment variables to pass additional configuration to their Actors. To set custom variables:

The Actor owner can specify custom environment variables that are set to the Actor's process during the run. Sensitive environment variables such as passwords or API tokens can be protected by setting the **Secret** option. With this option enabled, the value of the environment variable is encrypted, and it will not be visible in the app or APIs. In addition, the value is redacted from Actor logs to avoid the accidental leakage of sensitive data.
1. Go to your Actor's **Source** page in the Apify Console

1. Navigate to the **Environment variables** section.

1. Add your custom variables.

For sensitive data like API keys or passwords, enable the **Secret** option. This encrypt the value and redacts it from logs to prevent accidental exposure.

:::info Build-time variables

Custom environment variables are set during the Actor's build process and cannot be changed for existing builds. For more information, check out the [Builds](../builds_and_runs/builds.md) page.

:::

## Build-time environment variables

You can also use environment variables during the Actor's build process. In this case, they function as Docker build arguments. To use them in your Dockerfile, include `ARG` instruction:

```docker
ARG MY_BUILD_VARIABLE
RUN echo $MY_BUILD_VARIABLE
```

![Custom environment variables](./images/environment-vatiables-source.png)
:::caution Insecure build variables

Note that the custom environment variables are fixed during the build of the Actor and cannot be changed later. See the [Builds](../builds_and_runs/builds.md) section for details.
Build-time environment variables are not suitable for secrets, as they are not encrypted.

The Actor runtime sets additional environment variables for the Actor process during the run. See [Environment variables](./environment_variables.md) for details.
:::

The environment variables can also be used for the build process. In this case, the variables are treated as [Docker build arguments](https://docs.docker.com/engine/reference/builder/#arg). This means that they should not be used for secrets and, in order to access them in Dockerfile, you have to use the `ARG variable_name` instruction.
By leveraging environment variables effectively, you can create more flexible and configurable Actors that adapt to different execution contexts and user requirements.
1 change: 1 addition & 0 deletions vale.ini
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -20,3 +20,4 @@ Microsoft.Quotes = NO
Microsoft.ThereIs = NO
Microsoft.Auto = NO
Microsoft.URLFormat = NO
Microsoft.GeneralURL = NO