docs: (#3601)

* new docs for act

* Update docs/developers/local_github_actions_with_act.md

Co-authored-by: gemini-code-assist[bot] <176961590+gemini-code-assist[bot]@users.noreply.github.com>

* Update docs/developers/local_github_actions_with_act.md

Co-authored-by: gemini-code-assist[bot] <176961590+gemini-code-assist[bot]@users.noreply.github.com>

* Update docs/developers/local_github_actions_with_act.md

Co-authored-by: gemini-code-assist[bot] <176961590+gemini-code-assist[bot]@users.noreply.github.com>

* Update docs/developers/testing.md

Co-authored-by: gemini-code-assist[bot] <176961590+gemini-code-assist[bot]@users.noreply.github.com>

* Update docs/developers/local_github_actions_with_act.md

Co-authored-by: gemini-code-assist[bot] <176961590+gemini-code-assist[bot]@users.noreply.github.com>

---------

Co-authored-by: gemini-code-assist[bot] <176961590+gemini-code-assist[bot]@users.noreply.github.com>

Author: jaegeral

docs/developers/local_github_actions_with_act.md

@@ -0,0 +1,84 @@
+# How to Run GitHub Actions Locally with act
+
+Running your GitHub Actions workflows locally before pushing your changes can save significant time and CI/CD resources. This guide explains how to use `act`, a tool that lets you run your workflows in a local Docker environment that mimics the GitHub Actions runners.
+
+## Prerequisites
+
+1.  **Docker:** You must have Docker installed, and the Docker daemon must be running.
+2.  **`act`:** The `act` command-line tool.
+
+## Installation
+
+You can install `act` using its official installation script. Open a terminal and run the following command. You will be prompted for your password as it installs the binary into `/usr/local/bin/`.
+
+```bash
+curl -s https://raw.githubusercontent.com/nektos/act/master/install.sh | sudo bash
+
+For other installation methods, please refer to the [official `act` documentation](https://github.com/nektos/act#installation).
+
+## Running the Workflows
+
+The most common use case is to simulate a `pull_request` event, which is what triggers the e2e tests.
+
+### Listing and Running a Specific Job
+
+1.  To see all jobs that would run for a pull request, navigate to the root of the Timesketch repository and run:
+    ```bash
+    act pull_request --list
+    ```
+    `act` will list all the jobs from the `.github/workflows/e2e_tests.yml` file.
+
+2.  To run a **specific job** from the list, use the `-j` flag. This is the recommended approach as it consumes fewer resources.
+
+    **Example:** To run the e2e test suite with stable Plaso and OpenSearch v2:
+    ```bash
+    act pull_request -j PyPi-plaso-stable-opensearch-v2 --container-options "-m 4g --privileged"
+    ```
+
+### Running All Jobs
+
+To run all jobs for a given event (e.g., `pull_request`), simply run `act` without the `-j` flag.
+
+**Warning:** This will run all 8 e2e test jobs in parallel, which is very resource-intensive (CPU, RAM, and disk space).
+
+```bash
+act pull_request --container-options "-m 4g --privileged"
+```
+
+## Important Considerations
+
+### Resource Allocation
+*   `--container-options "-m 4g --privileged"`: It is highly recommended to allocate at least 4GB of memory to the container to prevent memory-related failures (which can manifest as `exit code 137`). The `--privileged` flag grants extended permissions that can help avoid certain container runtime errors.
+
+### Docker-in-Docker
+
+The Timesketch e2e test workflow uses `docker compose` to set up its test environment. This means `act` will be running a Docker container, which in turn needs to run `docker compose`. This "Docker-in-Docker" scenario requires the `act` container to have access to your system's Docker daemon.
+`act` typically handles this automatically by mounting the Docker socket (`/var/run/docker.sock`). If you encounter errors related to `docker` not being found, ensure your Docker setup is standard and the socket is accessible.
+
+### File Permissions
+If you encounter `permission denied` errors, particularly related to `metadata.json`, you may need to adjust the file's ownership on your host machine. You can do this by running:
+```bash
+sudo chown $(whoami) metadata.json
+```
+
+### Secrets
+
+`act` does not have access to your repository's GitHub secrets. If a workflow depends on secrets, you can provide them locally by creating a `.secrets` file in the root of the repository and running `act` with the `--secret-file .secrets` flag. The e2e tests do not require any secrets.
+
+### Controlling Log Verbosity
+By default, `act` can produce very verbose output, logging every detail of the workflow execution. You can control this verbosity using the following flags:
+*   **`--quiet`** (or **`-q`**): Disables the logging of output from individual steps, making the overall output less verbose. This is useful when you only care about the job's success or failure.
+
+    **Example:** To run a specific job with quiet output:
+    ```bash
+    act pull_request -j PyPi-plaso-stable-opensearch-v2 --quiet
+    ```
+
+*   **`--verbose`** (or **`-v`**): Provides more detailed output for debugging purposes. Use this when you need to inspect the inner workings of an action or step.
+
+    **Example:** To run a specific job with verbose output:
+    ```bash
+    act pull_request -j PyPi-plaso-stable-opensearch-v2 --verbose
+    ```
+
+**Note:** The exact path to the `act` executable may vary depending on your installation method. If the command is not in your shell's `PATH`, you may need to provide the full path to the executable.

docs/developers/testing.md

@@ -157,3 +157,7 @@ To generate a CSV file named `dummy_events.csv` with 50 events between January 1
 ```bash
 python3 utils/generate_sample_data.py --output dummy_events.csv --count 50 --start-date 2023-01-01T09:00:00 --end-date 2023-01-01T17:00:00
 ```
+
+### Running End-to-End Tests Locally
+For detailed instructions on how to run end-to-end tests locally using `act`,
+please refer to the [How to Run GitHub Actions Locally with act](local_github_actions_with_act.md) guide.