From fc9d3b4c313c7a70b4894d32128793c6343d49dc Mon Sep 17 00:00:00 2001 From: Luis Remis Date: Wed, 1 Jul 2026 11:15:15 -0700 Subject: [PATCH 1/2] Add AGENTS.md --- AGENTS.md | 46 ++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 46 insertions(+) create mode 100644 AGENTS.md diff --git a/AGENTS.md b/AGENTS.md new file mode 100644 index 00000000..c6a69f99 --- /dev/null +++ b/AGENTS.md @@ -0,0 +1,46 @@ +# OpenCode Agent Instructions + +This repository contains ApertureDB workflows packaged as Docker images. It uses a monorepo-style structure with multiple applications located in the `apps/` directory, sharing common build scripts and base images. + +## Architecture & Boundaries +- `apps/`: Contains individual workflow projects (e.g., `embeddings-extraction`, `rag`, `jupyterlab`). Each acts as an independent Docker build but relies on root scripts. +- `base/docker/`: Contains the base Ubuntu+Python Docker image that individual workflows build upon. +- `docker-compose.yml` (at root): Provides shared services for testing, notably the `lenz` ApertureDB container and the `ca` cert generator. + +## Testing & Execution +**Do not run `pytest` or python execution scripts directly on the host.** Workflows depend on complex interactions with the database and object storage. Execution and testing are entirely orchestrated via Docker Compose. + +To test a specific app: +```bash +cd apps/ +./test.sh +``` + +What `test.sh` does (orchestrated via root `.commonrc`): +1. Builds the `base` image and the app image via `compose.sh`. +2. Starts `lenz` (ApertureDB) locally. +3. Frequently runs a `seed` container to populate synthetic data (see `apps//test/docker-compose.yml`). +4. Executes the main workflow container. +5. Runs a `tests` container (which executes `pytest` internally) and reports success/failure based on the exit code. + +Test logs are captured and written to `apps//test.log`. Review this file if a test suite fails. + +*Note: If an app lacks a `test.sh`, the CI pipeline falls back to executing `../build.sh` to ensure the Docker image successfully builds.* + +## Building Images +If you only need to build the Docker image for an app without running tests: +```bash +apps/build.sh +# or from the app directory: +cd apps/ && ../build.sh +``` + +To build the shared base image: +```bash +cd base/docker && bash build.sh +``` + +## Quirks & Conventions +- **Docker Compose Dependencies:** Test execution relies on strict `depends_on` sequencing (`lenz` -> `seed` -> `workflow-app` -> `tests`). If you modify an app's testing compose file, ensure lifecycle conditions like `service_completed_successfully` are maintained so containers do not execute prematurely. +- **Environment Variables:** Workflows expect specific ApertureDB connection variables: `DB_HOST`, `DB_PORT`, `DB_USER`, `DB_PASS`, and `CA_CERT`. During local tests, `DB_HOST` resolves to the `lenz` service. +- **Code Standards:** There are no repo-wide linting, formatting, or pre-commit hooks enforced. Conform strictly to the style of the file you are modifying. \ No newline at end of file From 974d6761d4ecb6cdc31b62effd939eb37452f14a Mon Sep 17 00:00:00 2001 From: luisremis Date: Wed, 1 Jul 2026 11:41:49 -0700 Subject: [PATCH 2/2] Apply suggestions from code review Co-authored-by: Copilot Autofix powered by AI <175728472+Copilot@users.noreply.github.com> --- AGENTS.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/AGENTS.md b/AGENTS.md index c6a69f99..0816c043 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -5,7 +5,7 @@ This repository contains ApertureDB workflows packaged as Docker images. It uses ## Architecture & Boundaries - `apps/`: Contains individual workflow projects (e.g., `embeddings-extraction`, `rag`, `jupyterlab`). Each acts as an independent Docker build but relies on root scripts. - `base/docker/`: Contains the base Ubuntu+Python Docker image that individual workflows build upon. -- `docker-compose.yml` (at root): Provides shared services for testing, notably the `lenz` ApertureDB container and the `ca` cert generator. +- `docker-compose.yml` (at root): Provides shared services for testing, notably the `aperturedb` database, the `lenz` gateway in front of it, and the `ca` cert generator. ## Testing & Execution **Do not run `pytest` or python execution scripts directly on the host.** Workflows depend on complex interactions with the database and object storage. Execution and testing are entirely orchestrated via Docker Compose. @@ -18,7 +18,7 @@ cd apps/ What `test.sh` does (orchestrated via root `.commonrc`): 1. Builds the `base` image and the app image via `compose.sh`. -2. Starts `lenz` (ApertureDB) locally. +2. Starts `aperturedb` and `lenz` (ApertureDB gateway) locally. 3. Frequently runs a `seed` container to populate synthetic data (see `apps//test/docker-compose.yml`). 4. Executes the main workflow container. 5. Runs a `tests` container (which executes `pytest` internally) and reports success/failure based on the exit code. @@ -42,5 +42,5 @@ cd base/docker && bash build.sh ## Quirks & Conventions - **Docker Compose Dependencies:** Test execution relies on strict `depends_on` sequencing (`lenz` -> `seed` -> `workflow-app` -> `tests`). If you modify an app's testing compose file, ensure lifecycle conditions like `service_completed_successfully` are maintained so containers do not execute prematurely. -- **Environment Variables:** Workflows expect specific ApertureDB connection variables: `DB_HOST`, `DB_PORT`, `DB_USER`, `DB_PASS`, and `CA_CERT`. During local tests, `DB_HOST` resolves to the `lenz` service. +- **Environment Variables:** Workflows expect ApertureDB connection/auth variables such as `DB_HOST`, `DB_PORT`, `DB_USER`, `DB_PASS`, `CA_CERT`, and optionally `APERTUREDB_KEY`. During local tests, `DB_HOST` resolves to the `lenz` service. - **Code Standards:** There are no repo-wide linting, formatting, or pre-commit hooks enforced. Conform strictly to the style of the file you are modifying. \ No newline at end of file