Best practices

This page summarizes recommended best practices when developing and operating workloads with STACKIT Notebooks. Following these guidelines will help ensure maintainability, reproducibility, collaboration, and secure operation.

---

Development workflow

Even when working interactively, a structured workflow is essential.

• Use Git for all code and notebooks
  • Store notebooks (.ipynb) and related Python modules in a Git repository.
  • Use feature branches and pull requests for collaboration and review.
  • Avoid keeping critical logic only inside running notebook servers.

---

Versioning notebooks properly

Notebooks are JSON files and can become difficult to review if not handled properly.

• Commit notebooks without execution outputs

  • Clear outputs before committing (e.g. via pre-commit hooks).
  • This reduces merge conflicts and repository size.

• Keep business logic outside notebooks

  • Move reusable logic into .py modules.
  • Import those modules into the notebook.
  • This makes testing and code review significantly easier.

• Use tools like nbdime

  • Improves notebook diffs and merge handling.

---

Installing additional packages

Notebooks often require additional Python dependencies.

• Avoid permanent pip install commands inside notebooks

  • Installing packages ad-hoc leads to non-reproducible environments.
  • Restarting kernels may remove dynamically installed packages.

• Installing packages during runtime is acceptable for experiments only

  • Example: !pip install package-name
  • Suitable for quick prototyping in DEV.
  • Not suitable for production or shared environments.

• *Best practice: Use custom profiles

  • If you have special requirements regarding the runtime you want to use in STACKIT Notebooks, ask the Support to provide an additional profile which fits your needs.

This guarantees reproducibility and avoids environment drift.