Chembience

Chembience is a Docker-based chemoinformatics platform with prewired RDKit and RDKit-enabled PostgreSQL components. It provides ready-to-use Django, FastAPI, JupyterLab, RDKit, and PostgreSQL services for building chemical informatics applications. This repository superceeds the chembience implementation at https://github.com/chembience/chembience (v<=0.4.0) and starts at version 0.5.0. It is a full KI-based re-implementation of the original chembience project from the scratch.

What Chembience Provides

Chembience bundles a complete containerized environment for cheminformatics development. All images are built with micromamba to ensure minimal image size and fast build times.

• RDKit for molecular representation, descriptors, fingerprints, similarity search, and chemical data processing.
• PostgreSQL with the RDKit cartridge for storing, indexing, and querying chemical structures.
• Django for building web applications and administrative interfaces.
• FastAPI for building async APIs and lightweight services.
• JupyterLab for exploratory cheminformatics workflows.
• Helper scripts for bootstrapping, running, and removing generated applications.

All services are wired together with Docker Compose and share a common application directory mounted into the containers.

Quick Start

For instance, get a JupyterLab environment with RDKit + PostgreSQL running in a few commands:

# 1. Clone the repository
git clone https://github.com/chembience/core.git chembience
cd chembience

# 2. Build a Jupyter app (creates ~/myapp by default)
./build jupyter myapp

# 3. Switch to the generated app directory and start it
cd ~/myapp
docker compose up -d

# 4. Print the Jupyter access URL (with token)
./jupyter-init

Then open the printed URL in your browser (it includes the access token). Swap jupyter for django, fastapi, or rdkit in step 2 to bootstrap a different stack.

Prerequisites

• Docker: Version 20.10.0 or higher
• Docker Compose: Version 2.0.0 or higher
• Bash: Linux, Windows with WSL2/Ubuntu (docker in Ubuntu), macOS is in works (it works kind of, but not smoothly yet)

Major Software Components

Versions are controlled through .env / .env.example and Docker build arguments.

• Python: 3.14 (configurable via CONDA_PY)
• RDKit: 2026.03.2 (configurable via RDKIT_VERSION)
• PostgreSQL: 18 (RDKit-cartridge-enabled)
• Django: 5.x-compatible
• FastAPI: 0.115+-compatible
• SQLAlchemy: 2.x-compatible
• JupyterLab: 4.x-compatible
• django-rdkit and razi

Releases

Release	Date	Notes
0.5.1	2026‑06‑03	Smaller Docker images, switch to mamba as build system, many minor improvements and bug fixes
0.5.0	2026‑05‑27	Initial release of the re-implemented core architecture

Release older than 0.5.0 are no longer supported but are still available in the archive.

Installation & Setup

1. Clone the repository.

   ./git clone https://github.com/chembience/core.git chembience

2. Navigate to the project directory.

3.  cd chembience

4. Build and set up an application:

   ./build <type> <target>

   • <type>: django, fastapi, jupyter or rdkit
   • <target>: Name of your application (e.g., myapp)

Example:

./build django myapp

By default, the application is created in ~/myapp. You can specify a custom directory with the -d option:

./build rdkit|django|fastapi|jupyter myapp -d /path/to/parent_dir

This will create the app in /path/to/parent_dir/myapp.

Secrets

DJANGO_SECRET_KEY is auto-generated on first ./build and persisted in the per-project .env inside APP_HOME (e.g. ~/myapp/.env). The same key is reused on every container restart, so sessions, signed cookies, and password reset tokens remain valid. Treat that .env as a secret.

• To inject your own key (e.g. from Vault or a CI secret store), set DJANGO_SECRET_KEY in the project's .env before running ./build; it will be forwarded to the container and persisted into the project .env.
• Rotating the key (replacing it in the project .env and restarting) will log out all existing users and invalidate any outstanding signed tokens.
• The key is never baked into the Docker image; generation happens at container start, inside the bind-mounted volume.

PostgreSQL Password

POSTGRES_PASSWORD must be set in the project's .env before running ./build. The .env.example file contains a placeholder (CHANGE_ME_BEFORE_RUNNING) as a reminder.

To change the password later, use the <appname>-configure script located inside your application directory. Each app type ships its own configure script:

App type	Script
django	django-configure
fastapi	fastapi-configure
jupyter	jupyter-configure
rdkit	rdkit-configure

The configure script follows a safe two-phase workflow:

1. First run — creates a .env.new file (a copy of the current .env) and asks you to edit it:

   ./django-configure

2. Edit — open .env.new and update POSTGRES_PASSWORD to the new value.
3. Second run — detects the password change, rotates it live inside the running Postgres container, then adopts the new .env:

   ./django-configure

The script automatically handles the Postgres ALTER USER statement with the old credentials before switching to the new ones, so no manual SQL is needed.

Django Superuser Password

DJANGO_SUPERUSER_PASSWORD (together with DJANGO_SUPERUSER_USERNAME and DJANGO_SUPERUSER_EMAIL) is read from the project's .env and used by the Django init flow to create the initial admin user. Treat it as a secret: set it in .env before running ./build, never commit it, and rotate it via python manage.py changepassword inside the django container if needed.

JupyterLab Token

JupyterLab is launched with its token authentication enabled by default (we do not disable it in docker-compose.yml). Use the per-app init helper to print the access URL — including the token when available:

./jupyter-init

If a token was auto-generated by Jupyter, jupyter-init will query the running server and print a URL like http://localhost:8888/?token=<...>.

• To run without a token in development, use the provided overlay:

  docker compose -f docker-compose.yml -f docker-compose.dev.yml up -d

  The docker-compose.dev.yml file sets --ServerApp.token='' for the jupyter service.

• To pin a stable token, set JUPYTER_TOKEN in your project's .env and add a small compose override to pass it to the server, for example docker-compose.override.yml:

  services:
    jupyter:
      command: ["jupyter", "lab", "--ip=0.0.0.0", "--port=8888", "--no-browser", "--allow-root", "--ServerApp.token=${JUPYTER_TOKEN}"]

Treat JUPYTER_TOKEN as a secret (same as POSTGRES_PASSWORD and DJANGO_SECRET_KEY): never commit it, and rotate it by changing .env and restarting the jupyter service.

Protecting the Project .env

The per-project .env (inside APP_HOME) ends up holding POSTGRES_PASSWORD, DJANGO_SECRET_KEY, DJANGO_SUPERUSER_PASSWORD, and optionally JUPYTER_TOKEN. Treat the whole file as a secret: keep it out of version control, restrict its file permissions, and back it up separately from the source tree.

Services Overview

Chembience ships several services, all wired together via docker-compose.yml:

Service	Directory	Purpose
django	django/	Main Django web app.
fastapi	fastapi/	Async REST API.
jupyter	jupyter/	JupyterLab environment with RDKit + Postgres pre-wired.
rdkit	rdkit/	RDKit interactive one-shot Python shell.
postgres	postgres/	PostgreSQL 18 with the RDKit cartridge.

For all services, the connection to the database is wired via environment variables, that can be imported via the shared chembience python module. The package also let you import a readily configured SqlAlchemy engine.

from chembience import db
dir(db)
['Base', 'POSTGRES_HOST', 'POSTGRES_NAME', 'POSTGRES_PASSWORD', 'POSTGRES_PORT', 'POSTGRES_USER', 'SQLALCHEMY_DATABASE_URL', 'SessionLocal', '__builtins__', '__cached__', '__doc__', '__file__', '__loader__', '__name__', '__package__', '__spec__', 'create_engine', 'declarative_base', 'engine', 'get_db', 'init_db', 'os', 'sessionmaker']

Repository Layout

• docker-compose.yml: Authoritative definition of all services and how they interact.
• .env.example: Template for environment configuration.
• build: Script to bootstrap a new project.
• remove: Script to tear down a project and optionally remove images.
• psql: Helper script to open a psql shell.
• test-build-all: Script to verify all application types.
• django/, fastapi/, jupyter/, rdkit/, postgres/: Service-specific Dockerfiles and initialization scripts.

Helper Scripts

Thin Bash wrappers around docker compose and the per-service entrypoints.

• ./build <type> <target> [-d <parent_dir>] — bootstrap a new project.
• ./remove <target> [-d <parent_dir>] [-i|--images] [--silent|-s] — tear it down.
• ./psql — open a psql shell on the Postgres container.
• ./test-build-all — Test script to build and init all app types.

Per-app helper scripts located in their app directories:

App	Scripts
django	django/django-init, django/django-manage-py, django/psql
fastapi	fastapi/app/fastapi-init, fastapi/app/db_backup, fastapi/app/db_cleanup, fastapi/app/db_restore
jupyter	jupyter/app/jupyter-init
rdkit	rdkit/app/rdkit-init, rdkit/app/run, rdkit/app/shell

Development

For more detailed information, see:

• CLAUDE.md: Development guide and common commands.
• AGENTS.md: Information for AI agents and high-level overview.
• LICENSE: BSD 3-Clause License.

License

This project is licensed under the BSD 3-Clause License - see the LICENSE file for details.

Bugs, Comments and anything else

For any bug reports, comments or suggestion please use the tools here at Github or contact me by email.

Markus Sitzmann, 2026-06-03