Merge pull request #1 from benchling/initial-example

Initial commit with an example for chem-sync-local-flask

Author: bowenwr

.gitignore

@@ -0,0 +1,11 @@
+.idea
+.vscode
+**/.venv/
+**/*.egg-info
+**/__pycache__
+**/.env
+.DS_Store
+**/.client_secret
+**/.pytest_cache
+.mypy_cache
+.ruff_cache

README.md

@@ -0,0 +1,22 @@
+# Benchling App Python Examples
+
+The `examples/` directory contains Benchling App samples written by Benchling.
+
+## chem-sync-local-flask
+
+Demonstrates creating a custom UI in Benchling allowing users to search for 
+molecules from [PubChem](https://pubchem.ncbi.nlm.nih.gov/) and sync them into Benchling.
+
+Uses [localtunnel](https://localtunnel.me/) and [Docker](https://www.docker.com/) to receive webhooks 
+in a local development environment running [Flask](https://flask.palletsprojects.com/) with the 
+[Benchling SDK](https://docs.benchling.com/docs/getting-started-with-the-sdk).
+
+![image info](./examples/chem-sync-local-flask/docs/demo-short.gif)
+
+**Code Includes:**
+* Benchling App Authentication via [Client Credentials](https://docs.benchling.com/docs/getting-started-benchling-apps#getting-credentials)
+* Custom UI via [App Canvas](https://docs.benchling.com/docs/introduction-to-app-canvas)
+* User Feedback via [App Status](https://docs.benchling.com/docs/introduction-to-app-status)
+* Data Mapping via [App Config](https://docs.benchling.com/docs/app-configuration)
+* Receiving and verifying [Webhooks](https://docs.benchling.com/docs/getting-started-with-webhooks)
+* Creating [molecule custom entities](https://benchling.com/api/reference#/Molecules/createMolecule)

examples/chem-sync-local-flask/.devcontainer/Dockerfile

@@ -0,0 +1,17 @@
+FROM python:3.11
+
+# Add non-root user for security
+ARG USERNAME=nonroot
+RUN groupadd --gid 1000 $USERNAME && useradd --uid 1000 --gid 1000 -m $USERNAME
+## Make sure to reflect new user in PATH
+ENV PATH="/home/${USERNAME}/.local/bin:${PATH}"
+USER $USERNAME
+
+# Install pre-requirements
+RUN pip install pip~=23.3.2 setuptools~=69.0.3
+
+COPY requirements.txt ./
+RUN pip install -r requirements.txt
+
+COPY dev_requirements.txt ./
+RUN pip install -r dev_requirements.txt

examples/chem-sync-local-flask/.devcontainer/devcontainer.json

@@ -0,0 +1,27 @@
+{
+  "build": {
+    "dockerfile": "Dockerfile",
+    "context": ".."
+  },
+  "remoteUser": "nonroot",
+  "customizations": {
+    "vscode": {
+      "extensions": [
+        "ms-python.python",
+        "ms-python.mypy-type-checker",
+        "charliermarsh.ruff"
+      ],
+      "settings": {
+        "python.testing.pytestArgs": [
+          "."
+        ],
+        "python.testing.unittestEnabled": false,
+        "python.testing.pytestEnabled": true,
+        "python.editor.defaultFormatter": "charliermarsh.ruff",
+        "python.linting.mypy": true,
+        "python.linting.enabled": true,
+        "explorer.excludeGitIgnore": true
+      }
+    }
+  }
+}

examples/chem-sync-local-flask/.gitignore

@@ -0,0 +1,11 @@
+.idea
+.vscode
+**/.venv/
+**/*.egg-info
+**/__pycache__
+**/.env
+.DS_Store
+**/.client_secret
+**/.pytest_cache
+.mypy_cache
+.ruff_cache

examples/chem-sync-local-flask/Dockerfile

@@ -0,0 +1,10 @@
+FROM python:3.11
+
+# Install pre-requirements
+RUN pip install pip~=23.3.2 setuptools~=69.0.3
+
+COPY requirements.txt ./
+RUN pip install -r requirements.txt
+COPY ./local_app /src/local_app
+WORKDIR /src/local_app
+CMD ["flask", "run", "--host", "0.0.0.0"]

examples/chem-sync-local-flask/Dockerfile.localtunnel

@@ -0,0 +1,5 @@
+FROM node:21-alpine
+RUN npm install -g localtunnel@2.0.2
+
+# Note: This might not work with some networks. For instance, random airplane WiFi
+CMD lt --port 5000 --local-host benchling-app --print-requests

examples/chem-sync-local-flask/README.md

@@ -0,0 +1,208 @@
+# Benchling App Example: Chemical Sync for Local Development
+
+An example Benchling App written in Python which allows users to search for chemicals 
+via [PubChem](https://pubchem.ncbi.nlm.nih.gov/) and create them in Benchling.
+
+![image info](./docs/demo-full.gif)
+_The App features branching flows and will also validate user inputs._
+
+## Technical Prerequisites
+
+This app is optimized as a minimal local development experience using [Docker](https://www.docker.com/) for reproducibility.
+
+> ⚠️ **Development Only**: This example is not meant to be copied into production as-is. There are additional deployment, scale, and security concerns that should be addressed before deploying an app based on this example to production.
+
+It relies on a few other tools that will be installed for you within Docker containers:
+* [Localtunnel](https://localtunnel.me/) - expose a public webhook URL and forward the results locally. ⚠️ *Not for production or real data!*
+* [Flask](https://flask.palletsprojects.com/) - A simple Python web application framework
+
+## Getting Started
+
+Create an empty placeholder file for Docker secrets. *nix example:
+
+```bash
+touch .client_secret
+```
+
+Start Docker:
+
+```bash
+docker compose up --build -d
+```
+
+Tip: You can omit the `-d` option if you want to run in the foreground. Otherwise, use `docker compose logs -f` to tail logs.
+
+You can verify that Flask is up and running:
+
+```bash
+curl localhost:8000/health
+```
+
+If Flask is running, you should see `OK` printed.
+
+Be sure to note the URL created for you by `localtunnel`. The log line should look something like this:
+
+```
+app-workshop-local-tunnel-1   | your url is: https://brave-wombats-poke.loca.lt
+```
+
+On *nix systems, you can easily obtain _just_ the URL via:
+
+```
+docker compose logs local-tunnel | grep -o https://.* | tail -n 1
+```
+
+Example Output:
+
+```
+https://brave-wombats-poke.loca.lt
+```
+
+> 💡 Don't forget to append `/1/webhooks`, making the full URL given to Benchling `https://brave-wombats-poke.loca.lt/1/webhooks`
+
+## Setting Up Your App in Benchling
+
+### Benchling Prerequisites
+1. Access to a Benchling tenant, like `https://my-tenant.benchling.com`
+2. Ensure you've been granted access to the [Benchling Developer Platform Capability](https://help.benchling.com/hc/en-us/articles/9714802977805-Access-the-Benchling-Developer-Platform).
+3. This example also requires a [Lab Automation](https://www.benchling.com/resources/benchling-lab-automation) license.
+4. [Molecule entities](https://help.benchling.com/hc/en-us/articles/9684254682893-Molecule-entity-overview) will need to be enabled on your tenant.
+
+### Upload the App Manifest
+
+Click the user icon in the bottom left corner to bring up the main menu. Select "Feature Settings" > "Developer Console"
+
+Next, click the "Create app" button and choose "From manifest."
+
+When prompted to upload a file, select `manifest.yaml` and click "Create."
+
+![image info](./docs/create-app.gif)
+
+### Update the Webhook URL
+
+Every time we restart the `local-tunnel` Docker container, it will provision
+a new public webhook URL.
+
+Update the Benchling App's Webhook URL in the UI with the new server and
+append the path our Flask route expects (see `local_app/app.py`).
+
+For example, if our `localtunnel` generated URL is `https://hot-ideas-doubt.loca.lt`,
+the webhook URL in Benchling should be:
+
+```
+https://hot-ideas-doubt.loca.lt/1/webhooks
+```
+
+![image info](./docs/update-webhook-url.gif)
+
+### Generating a Client Secret
+
+Generate a client secret in Benchling and be sure to copy the secret.
+
+![image info](./docs/generate-secret.gif)
+
+One easy way to set these environment variables for Docker is to add a `.env` file.
+
+```bash
+touch .env
+```
+
+Open it in an editor of your choice and set the values with the plaintext client ID 
+for your App. For example:
+
+```
+CLIENT_ID=42a0cd39-0543-4dd2-af02-a866c97f0c4d
+```
+
+Since the client secret is sensitive, it's handled a bit differently. It's
+registered as a `secret` in our `docker-compose.yaml` file, which will be looking
+for a file `./client_secret`.
+
+We can create this file and paste in the secret plaintext value if we have the secret in our clipboard.
+On *nix:
+
+```bash
+touch .client_secret
+pbpaste > .client_secret
+```
+
+> ⚠️ **Security Note:** Be sure to avoid committing `.client_secret` to a source code repository.
+
+You'll then need to restart _just_ the `benchling-app` Docker service to pick up the changes:
+
+```
+docker-compose up -d
+```
+
+If you restart both containers, be sure to update your App in Benchling with the new webhook URL from localtunnel.
+
+> ⚠️ **Security Note:** In production, store the secret with a secure solution such as a secrets store (AWS Secrets Manager, as an example) or, if storing programmatically, encrypted using app-layer encryption. Avoid placing it in plaintext anywhere in code or configuration.
+
+### Create App Registry Dependencies
+
+If you examine the `configuration` section of `manifest.yaml`, you'll see our App
+expects a few configuration items:
+1. A folder
+2. A molecule entity schema with two decimal fields
+
+The `features` section of `manifest.yaml` also states that our App will render
+its UI on an `ASSAY_RUN`. So we'll also need:
+1. An Lab Automation run schema
+
+#### Folder
+
+Create a new folder where the molecules created by the App will be placed.
+An existing folder can also be used, if the App has permissions to it.
+
+![image info](./docs/create-folder.gif)
+
+#### Molecule Entity Schema
+
+Create the entity schema in the tenant's registry. If you do not have access to
+the registry, you can ask your tenant administrator to do this for you.
+
+![image info](./docs/create-molecule-schema.gif)
+
+The created molecule schema should look something like this:
+
+![image info](./docs/schema-example.png)
+
+_Note: The names can be different, and the schema is allowed to have additional fields.
+As long as it's for a `Molecule` entity, and has at least two `Decimal` fields._
+
+#### Lab Automation Run Schema
+
+Create a new lab automation run schema in the registry.
+
+![image info](./docs/create-run-schema.gif)
+
+### Updating the App's Configuration
+
+App Configuration gives us a stable code contract for referencing data mapped in a Benchling tenant.
+The values of the data in Benchling can then be changed without updating App code.
+
+Let's update our configuration to:
+1. Specify a folder for syncing sequences
+2. Link a molecule schema and fields for the synced chemicals
+3. Select an assay run schema to associate with our Benchling App
+
+![image info](./docs/update-app-config.gif)
+
+### Permission the App
+
+By default, Benchling Apps do not have permission to any data in Benchling.
+Let's grant some access by adding the Benchling App to an organization.
+
+![image info](./docs/permission-app.gif)
+
+## Running the App - Syncing a Chemical
+
+1. Create a new notebook entry
+2. Insert a run of the schema linked in App Config
+3. Create the Run
+4. Enter a valid chemical name to search for, such as `acetaminophen`
+5. Click "Search Chemicals"
+6. After reviewing the preview, click "Create Molecule"
+7. Click the linked entity to view it in Benchling
+
+![image info](./docs/demo.gif)

examples/chem-sync-local-flask/dev_requirements.txt

@@ -0,0 +1,4 @@
+# Only for maintainers
+ruff~=0.1.11
+pytest~=7.4.4
+mypy~=1.8.0

examples/chem-sync-local-flask/docker-compose.yaml

@@ -0,0 +1,38 @@
+version: "3.8"
+
+services:
+  benchling-app:
+    build: .
+    ports:
+      - "8000:5000"
+    volumes:
+      - type: bind
+        source: .
+        target: /src
+    environment:
+      # Don't set debug in production!
+      - FLASK_DEBUG=1
+      # Enable debug logging for Python Benchling App. This is not native, specific to this example implementation
+      - BENCHLING_APP_LOG_LEVEL=DEBUG
+      # Client ID is not sensitive and is the same across all tenants, so could be hard-coded
+      # You might choose to have two different Apps for dev vs prod, which would have different client IDs
+      - CLIENT_ID
+      # Client secret for the Benchling App, stored somewhere securely in production.
+      # Injected here for convenience. Each Client ID will have its own Client secret
+      - CLIENT_SECRET_FILE=/run/secrets/app_client_secret
+    secrets:
+      - app_client_secret
+
+  # FOR LOCAL DEVELOPMENT ONLY!
+  # Free tool for providing a public URL to forward webhooks to our Benchling App running locally
+  # Do not do this in production or use with any sensitive data.
+  # Benchling has not vetted this tool for use in production or in sensitive systems.
+  # Conduct your own due diligence before choosing a tool for production use.
+  local-tunnel:
+    build:
+      context: .
+      dockerfile: Dockerfile.localtunnel
+
+secrets:
+  app_client_secret:
+    file: .client_secret