OpenCloning Backend API

This API is part of a bigger application, before going further, please go to the main project readme, where you can find an introduction.

This python API is built with FastAPI and is for in silico cloning.

Summary

Read main project readme first.

This API provides a series of entry points. The API documentation can be accessed here. You can use the documentation page to try some request directly on the browser. Otherwise, the API is open for you to make requests from a python script or command line at: https://api.opencloning.org/.

Scripting with pydna

You can write python scripts to automate cloning using the python library pydna, which is now integrated with the OpenCloning data model. See the documentation for how to get started.

Migrating between model versions and fixing model bugs

• The data model changes, so the json files you created may not be compatible with the newest version of the library, which uses the latest data mode. You can easily fix this using python -m opencloning_linkml.migrations.migrate file.json see full documentation.
• Before version 0.3, there was a bug for assembly fields that included locations spanning the origin. See the details and how to fix it in the documentation of this file.

Getting started

If you want to quickly set up a local instance of the frontend and backend of the application, check getting started in 5 minutes in the main repository.

Running locally

You can install this as a python package:

# Create a virtual environment
python -m venv .venv
# Activate the virtual environment
source .venv/bin/activate
# Install the package from pypi
pip install opencloning
# Run the API (uvicorn should be installed in the virtual environment)
uvicorn opencloning.main:app

Installing from GitHub (monorepo)

This repository is a uv workspace; the installable package lives in packages/opencloning/. When installing directly from GitHub, include the subdirectory fragment:

# uv
uv add "opencloning @ git+https://github.com/manulera/OpenCloning_backend.git@master#subdirectory=packages/opencloning"

# pip
pip install "git+https://github.com/manulera/OpenCloning_backend.git@master#subdirectory=packages/opencloning"

Running locally if you want to contribute

This repository is a uv workspace: the installable package lives under packages/opencloning/, and the repo root holds workspace metadata and shared dev dependencies. Install uv, then from the repository root:

# Install the workspace (editable opencloning + dev/test dependency groups) into .venv
uv sync

# Install the pre-commit hooks
uv run pre-commit install

# Run tools via uv, or activate .venv and use them directly
source .venv/bin/activate   # optional

The virtual environment is created at the repository root (.venv). For VS Code settings see the folder .vscode.

Now you should be able to run the api by running:

# The --reload argument will reload the API if you make changes to the code
uvicorn opencloning.main:app --reload --reload-exclude='.venv'

Then you should be able to open the API docs at http://127.0.0.1:8000/docs to know that your API is working.

Running locally with docker 🐳

If you want to serve the full site (backend and frontend) with docker, check getting started in 5 minutes in the main repository.

If you want to serve only the backend from a docker container, an image is available at manulera/opencloningbackend. The image is built from docker/opencloning.Dockerfile (repository root as build context) and exposes the port 3000. To run it:

docker build -f docker/opencloning.Dockerfile -t manulera/opencloningbackend .
docker run -d --name backendcontainer -p 8000:8000 manulera/opencloningbackend

To run with a read-only root filesystem while still allowing temporary files (required for tools like mafft), mount /tmp as tmpfs (RAM-backed writable storage). This will not work with RECORD_STUBS=1 (see Generating API stubs).

docker run -d --name backendcontainer -p 8000:8000 \
  --read-only \
  --tmpfs /tmp:rw,noexec,nosuid,size=256M \
  manulera/opencloningbackend

If you don't want to download the repository and build the image, you can fetch the latest image from dockerhub.

docker pull manulera/opencloningbackend
docker run -d --name backendcontainer -p 8000:8000 manulera/opencloningbackend

The api will be running at http://localhost:8000, so you should be able to access the docs at http://localhost:8000/docs.

Connecting to the frontend

If you want to receive requests from the frontend, or from another web application you may have to include the url of the frontend application in the CORS exceptions. By default, if you run the dev server with uvicorn opencloning.main:app --reload --reload-exclude='.venv', the backend will accept requests coming from http://localhost:3000, which is the default address of the frontend dev server (ran with yarn start).

If you want to change the allowed origins, you can do so via env variables (comma-separated). e.g.:

ALLOWED_ORIGINS=http://localhost:3000,http://localhost:3001 uvicorn opencloning.main:app --reload --reload-exclude='.venv'

Similarly, the frontend should be configured to send requests to the backend address, see here.

Serving the frontend from the backend

You may prefer to handle everything from a single server. You can do so by:

• Build the frontend with yarn build.
• Copy the folder build from the frontend to the root directory of the backend, and rename it to frontend.
• Set the environment variable SERVE_FRONTEND=1 when running the backend. By default this will remove all allowed origins, but you can still set them with ALLOWED_ORIGINS.
• Set the value of backendUrl in frontend/config.js to /.
• Now, when you go to the root of the backend (e.g. http://localhost:8000), you should receive the frontend instead of the greeting page of the API.

You can see how this is done in this docker image and docker-compose file.

Contributing 🛠️

Check contribution guidelines in the main repository for general guidelines.

For more specific tasks:

• Creating a new type of source: follow the new source issue template. You can create an issue like that here.

Running the tests locally

From the repository root (after uv sync):

uv run pytest packages/opencloning/tests -v -ks

Running opencloning-db locally

opencloning-db is a companion API/database service for OpenCloning data workflows. It now lives in packages/opencloning-db/src and uses the local workspace opencloning package. This is currently an experimental feature, so behavior and interfaces may change. For a package-specific quickstart (what it is and how to run it), see packages/opencloning-db/README.md.

From the repository root:

# Install/update workspace dependencies
uv sync

# Run opencloning-db tests
uv run pytest packages/opencloning-db/tests -v

# Recreate the opencloning-db local database seed
./restart_db.sh

If you need to run the init script manually:

uv run --directory packages/opencloning-db/src python -m opencloning_db.init_db

Dependency guardrail (deptry)

This repository uses a uv workspace. In a workspace, dependencies are resolved in one shared environment, so imports can appear to work even when a package does not declare them in its own pyproject.toml.

To catch that, pre-commit runs deptry separately for opencloning and opencloning-db, each using that package’s pyproject.toml as the source of truth for declared dependencies.

Run them manually from the repository root:

uv run deptry --config packages/opencloning/pyproject.toml packages/opencloning/src
uv run deptry --config packages/opencloning-db/pyproject.toml packages/opencloning-db/src

Current rollout note: known undeclared imports such as pydna are temporarily ignored and should be removed from the ignore list once dependencies are declared.

Addgene authenticated access

Addgene now requires authenticated access to retrieve sequence files.

To be able to access AddGene sequences, create an account on AddGene and set these environment variables to enable Addgene imports:

export ADDGENE_USERNAME="your_addgene_username"
export ADDGENE_PASSWORD="your_addgene_password"

For one-off local runs you can also prefix commands:

ADDGENE_USERNAME="your_addgene_username" ADDGENE_PASSWORD="your_addgene_password" uv run pytest packages/opencloning/tests -v -ks

If these variables are not set, Addgene import endpoints return an informative error explaining that credentials are required.

Use of Addgene credentials and data must comply with Addgene Terms of Use.

For CI, configure repository secrets named ADDGENE_USERNAME and ADDGENE_PASSWORD so Addgene-dependent tests can run.

Notes

Pin a particular library version from GitHub

Do not do the default:

uv add git+https://github.com/pydna-group/pydna --branch main
uv add git+https://github.com/pydna-group/pydna --rev 4fd760d075f77cceeb27969e017e04b42f6d0aa3

Instead, edit pyproject directly:

pydna @ git+https://github.com/pydna-group/pydna@fa00f2a1240bd2caae7a89c808a464f297209ecf

The reason for this is that otherwise you cannot install the package from pip from the repository, as the github version is not pinned. For the same reasons, you don't want to publish this to pypi, and this will make the action fail.

If resolution seems stale, clear uv’s cache:

uv cache clean

Generating API stubs

For the frontend, it may be useful to produce stubs (I use them for writing the tests). See how this is implemented by looking at the RecordStubRoute class in api_config_utils.py. To run the dev server and record stubs:

RECORD_STUBS=1 uvicorn opencloning.main:app --reload --reload-exclude='.venv'

This will record the stubs (requests and responses) in the stubs folder.

Catalogs

Catalogs are used to map ids to urls for several plasmid collections. They are stored under packages/opencloning/src/opencloning/catalogs/.

To update the catalogs, run the following command from the repository root:

uv run python scripts/update_catalogs.py