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

docs: improve environment variables section #1124

Merged
merged 10 commits into from
Aug 9, 2024
Merged

docs: improve environment variables section #1124

Changes from 3 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
123 changes: 85 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,83 @@ 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 from Actor platform. |
TC-MO marked this conversation as resolved.
Show resolved Hide resolved
| `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. |
TC-MO marked this conversation as resolved.
Show resolved Hide resolved
| `ACTOR_INPUT_KEY` | Key of the record in the default key-value store that holds the Actor input. Typically **INPUT**, but may vary. |
TC-MO marked this conversation as resolved.
Show resolved Hide resolved
| `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` | Set to **1** if the Actor is running on Apify servers. |
TC-MO marked this conversation as resolved.
Show resolved Hide resolved
| `ACTOR_MEMORY_MBYTES` | Size of memory allocated for the Actor run, in megabytes. Used to optimize memory usage. |
TC-MO marked this conversation as resolved.
Show resolved Hide resolved
| `APIFY_PROXY_PASSWORD` | The Apify Proxy password of the user who started the Actor. |
TC-MO marked this conversation as resolved.
Show resolved Hide resolved
| `APIFY_PROXY_PORT` | |
TC-MO marked this conversation as resolved.
Show resolved Hide resolved
| `APIFY_PROXY_STATUS_URL` | |
TC-MO marked this conversation as resolved.
Show resolved Hide resolved
| `ACTOR_STANDBY_PORT` | TCP port for the Actor to start an HTTP server to receive messages from Actor Standby. |
TC-MO marked this conversation as resolved.
Show resolved Hide resolved
| `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 to receive external messages. |
TC-MO marked this conversation as resolved.
Show resolved Hide resolved
| `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 API, typically set to api.apify.com |
TC-MO marked this conversation as resolved.
Show resolved Hide resolved
| `APIFY_DEDICATED_CPUS` | Number of CPU cores reserved for the actor, based on allocated memory. |
| `APIFY_DISABLE_OUTDATED_WARNING` | |
TC-MO marked this conversation as resolved.
Show resolved Hide resolved
| `APIFY_FACT` | |
TC-MO marked this conversation as resolved.
Show resolved Hide resolved
| `APIFY_WORKFLOW_KEY` | Identifier used for grouping related runs and API calls together. |
| `APIFY_META_ORIGIN` | |
TC-MO marked this conversation as resolved.
Show resolved Hide resolved
| `APIFY_SDK_LATEST_VERSION` | |
TC-MO marked this conversation as resolved.
Show resolved Hide resolved


<!-- 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` class
TC-MO marked this conversation as resolved.
Show resolved Hide resolved

<Tabs groupId="main">
<TabItem value="JavaScript" label="JavaScript">
Expand Down Expand Up @@ -107,14 +131,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.
Loading