.. _containers_and_ci:

Containers & continuous integration
===================================

For containerization and continuous integration, Docker and GitHub Actions are used.

+------------------------+--------------------------------+---------------------------------------+
| Container image        | ordec-base                     | ordec                                 |
+========================+================================+=======================================+
| Purpose                | testing, development, building | **for users**                         |
+------------------------+--------------------------------+---------------------------------------+
| ORDeC installation     | ❌ no                          | ✅ included                           |
+------------------------+--------------------------------+---------------------------------------+
| Recommended tools (1)  | ✅ included                    | ✅ included                           |
+------------------------+--------------------------------+---------------------------------------+
| Recommended PDKs (2)   | ✅ included                    | ✅ included                           |
+------------------------+--------------------------------+---------------------------------------+
| Runtime dependencies   | ✅ included                    | ✅ included                           |
+------------------------+--------------------------------+---------------------------------------+
| Test dependencies (3)  | ✅ included                    | ❌ no                                 |
+------------------------+--------------------------------+---------------------------------------+
| Build dependencies (4) | ✅ included                    | ❌ no                                 |
+------------------------+--------------------------------+---------------------------------------+
| Image size             | ~ 2 GB                         | ~ 1 GB                                |
+------------------------+--------------------------------+---------------------------------------+
| Base image             | Debian                         | Debian + ordec-base                   |
+------------------------+--------------------------------+---------------------------------------+
| Release cycle          | manual, commit hash as version | synchronized to ORDeC / PyPI versions |
+------------------------+--------------------------------+---------------------------------------+
| Build script           | /base.Dockerfile               | /Dockerfile                           |
+------------------------+--------------------------------+---------------------------------------+

(1) The included recommended tools are: Ngspice, OpenVAF
(2) The included recommended PDKs are: SKY130, IHP-Open-PDK
(3) Test dependencies are: Selenium with Chromium
(4) Build dependencies are: Npm

ordec-base Docker image
-----------------------

The custom base image `ordec-base <https://github.com/tub-msc/ordec/pkgs/container/ordec-base>`_ is used for building and testing ORDeC. It contains most build and runtime dependencies. It also includes an environment with a custom Ngspice build, PDKs and OpenVAF.

This base image prevents having to recompile the fixed environment too often. It is a bit optimized for size (e.g., build dependencies of ngspice are not in final image).

This image is automatically built through *.github/workflows/base.yaml* using *base.Dockerfile*. It can of course also be built manually using *base.Dockerfile*.

ordec Docker image
------------------

The `ordec <https://github.com/tub-msc/ordec/pkgs/container/ordec>`_ image is built on top of ordec-base. It contains an installation of ORDeC that can be run by users through a single docker command, as described in the Readme.

This image is automatically built through *.github/workflows/build.yaml* using *Dockerfile*. It can also be built manually using this *Dockerfile*.

Before pushing the image, *build.yaml* tests it. This is important because the automated pytest runs (see below) use the ordec-base image, not the ordec image: a runtime tool that is present in ordec-base but missing from the ordec image (e.g. KLayout not copied over from the base image) is invisible to *tests.yaml*. The test suite is run inside the freshly built image (excluding web tests, which need chromium-driver and npm — deliberately not part of the user image).

In the future, ordec Docker images should be released in sync with the PyPI package ordec, both using git version tags (vX.Y.Z).

Automated pytest runs
---------------------

Pytest is run automatically through *.github/workflows/tests.yaml*. Here, ordec-base is used as container in which the tests are run.

There are some slight mismatches between this GitHub action and the ordec-base image (maybe this can be addressed in the future):

- While ordec-base uses the *app* user, GitHub actions seem to only work properly as the *root* user inside of a container.
- The user venv */home/app/venv*, where parts of the dependencies are installed, is reused by root.
- The directory */home/app/ordec*, where ORDeC is "supposed to go" in the logic of ordec-base, is ignored here.