An example Benchling App written in Python to test canvas session and user interactions.
The App features branching flows and will also validate user inputs.
Appendices:
This app is optimized as a minimal local development experience using Docker 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:
- Cloudflare-tunnel - expose a public webhook URL and forward the results locally.
⚠️ Not for production or real data! - Flask - A simple Python web application framework
Create an empty placeholder file for Docker secrets. *nix example:
touch .client_secretWindows example:
echo.> .client_secretStart Docker:
docker compose up --build -dTip: You can omit the -d option if you want to run in the foreground. Otherwise, use docker compose logs -f to tail logs.
ℹ️ Windows Note 1: "Use ContainerD for pulling and storing images" may need to be enabled in
Docker > Settings > Features in development > Beta Features
ℹ️ Windows Note 2: If running into an error like "ERROR: request returned Bad Gateway for API route and version", this solution may fix the problem.
You can verify that Flask is up and running:
curl localhost:8000/healthIf Flask is running, you should see OK printed.
Be sure to note the URL created for you by cloudflare-tunnel. The log line should look something like this:
cloudflare-tunnel-1 | 2025-03-11T18:45:24Z INF +--------------------------------------------------------------------------------------------+
cloudflare-tunnel-1 | 2025-03-11T18:45:24Z INF | Your quick Tunnel has been created! Visit it at (it may take some time to be reachable): |
cloudflare-tunnel-1 | 2025-03-11T18:45:24Z INF | https://pioneer-rights-hardly-disorder.trycloudflare.com |
cloudflare-tunnel-1 | 2025-03-11T18:45:24Z INF +--------------------------------------------------------------------------------------------+
On *nix systems, you can easily obtain just the URL via:
docker compose logs cloudflare-tunnel | grep -o 'https://[^ ]*trycloudflare.com[^ ]*' | tail -n 1
Example Output:
https://pioneer-rights-hardly-disorder.trycloudflare.com
💡 Don't forget to append
/1/webhooks, making the full URL given to Benchlinghttps://pioneer-rights-hardly-disorder.trycloudflare.com/1/webhooks
- Access to a Benchling tenant, like
https://my-tenant.benchling.com - Ensure you've been granted access to the Benchling Developer Platform Capability.
- [Optional] If you'd like to render the App's UI in a Run, you'll need a Benchling Connect license.
- Global Apps will need to be enabled on your tenant.
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."
Every time we restart the cloudflare-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 cloudflare-tunnel generated URL is https://pioneer-rights-hardly-disorder.trycloudflare.com,
the webhook URL in Benchling should be:
https://https://pioneer-rights-hardly-disorder.trycloudflare.com/1/webhooks
Generate a client secret in Benchling and be sure to copy the secret.
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:
touch .client_secret
pbpaste > .client_secret
⚠️ Security Note: Be sure to avoid committing.client_secretto a source code repository.
You'll then need to restart just the benchling-app Docker service to pick up the changes:
docker-compose up -dIf you restart both containers, be sure to update your App in Benchling with the new webhook URL from cloudflare-tunnel.
Our App needs a Client ID to pair with the Client Secret for authentication to Benchling. In this case, we've created our
App to accept CLIENT_ID as an environment variable.
One easy way to set an environment variables for Docker is to add a .env file.
touch .envWindows example:
echo.> .envOpen it in an editor of your choice and set the values with the plaintext client ID for your App. For example:
CLIENT_ID=Ts7jtwPohM
The App definition ID is available from the Developer Console by selecting the App to view.
ℹ️ Note: If you do NOT see this ID, please ensure Global Apps are enabled for your tenant.
Add it to your .env file with a variable name APP_DEFINITION_ID. The contents of your .env file should now look something like:
CLIENT_ID=Ts7jtwPohM
APP_DEFINITION_ID=appdef_Trow4zbR3o
Restart the benchling-app Docker container to pick up the environment changes.
docker-compose up -d
⚠️ 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.
We declare two features in the manifest.yaml so that our App can render
its UI as a CANVAS (e.g. within the Notebook) or on an ASSAY_RUN. If you'd like to use a Run, we'll also need:
- An Lab Automation run schema
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.
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.
- Insert a Run of the schema linked in App Config
- Create the Run
- Continue with steps 3-6 above
