diff --git a/.github/PULL_REQUEST_TEMPLATE/new_container.md b/.github/PULL_REQUEST_TEMPLATE/new_container.md index 27057310d..c64d66785 100644 --- a/.github/PULL_REQUEST_TEMPLATE/new_container.md +++ b/.github/PULL_REQUEST_TEMPLATE/new_container.md @@ -14,13 +14,18 @@ It helps reduce unnecessary work for you and the maintainers! - [ ] Your PR title follows the [Conventional Commits](https://www.conventionalcommits.org/en/v1.0.0/) syntax as we make use of this for detecting Semantic Versioning changes. + - Additions to the community modules do not contribute to SemVer scheme: + all community features will be tagged [community-feat](https://github.com/testcontainers/testcontainers-python/issues?q=label%3Acommunity-feat+), + but we do not want to release minor or major versions due to features or breaking changes outside of core. + So please use `fix(postgres):` or `fix(my_new_vector_db):` if you want to add or modify community modules. + This may change in the future if we have a separate package released with community modules. - [ ] Your PR allows maintainers to edit your branch, this will speed up resolving minor issues! - [ ] The new container is implemented under `modules/*` - Your module follows [PEP 420](https://peps.python.org/pep-0420/) with implicit namespace packages (if unsure, look at other existing community modules) - Your package namespacing follows `testcontainers..*` and you DO NOT have an `__init__.py` above your module's level. - - Your module has it's own tests under `modules/*/tests` + - Your module has its own tests under `modules/*/tests` - Your module has a `README.rst` and hooks in the `.. auto-class` and `.. title` of your container - Implement the new feature (typically in `__init__.py`) and corresponding tests. - [ ] Your module is added in `pyproject.toml` @@ -28,8 +33,7 @@ It helps reduce unnecessary work for you and the maintainers! - it is declared under `tool.poetry.extras` with the same name as your module name, we still prefer adding _NO EXTRA DEPENDENCIES_, meaning `mymodule = []` is the preferred addition (see the notes at the bottom) -- [ ] The `INDEX.rst` at the project root includes your module under the `.. toctree` directive -- [ ] Your branch is up to date (or we'll use GH's "update branch" function through the UI) +- [ ] Your branch is up-to-date (or your branch will be rebased with `git rebase`) # Preferred implementation diff --git a/index.rst b/index.rst index 8c02832fe..70708a247 100644 --- a/index.rst +++ b/index.rst @@ -13,6 +13,7 @@ testcontainers-python testcontainers-python facilitates the use of Docker containers for functional and integration testing. The collection of packages currently supports the following features. .. toctree:: + :maxdepth: 1 core/README modules/index @@ -59,12 +60,15 @@ Installation ------------ The suite of testcontainers packages is available on `PyPI `_, -and individual packages can be installed using :code:`pip`. +the package can be installed using :code:`pip`. -Version `4.0.0` onwards we do not support the `testcontainers-*` packages as it is unsutainable to maintain ownership. +Version `4.0.0` onwards we do not support the `testcontainers-*` packages as it is unsustainable to maintain ownership. Instead packages can be installed by specifying `extras `__, e.g., :code:`pip install testcontainers[postgres]`. +Please note, that community modules are supported on a best-effort basis and breaking changes DO NOT create major versions in the package. +Therefore, only the package core is strictly following SemVer. If your workflow is broken by a minor update, please look at the changelogs for guidance. + Custom Containers ----------------- @@ -80,40 +84,77 @@ For common use cases, you can also use the generic containers provided by the `t Docker in Docker (DinD) ----------------------- -When trying to launch a testcontainer from within a Docker container, e.g., in continuous integration testing, two things have to be provided: +When trying to launch Testcontainers from within a Docker container, e.g., in continuous integration testing, two things have to be provided: 1. The container has to provide a docker client installation. Either use an image that has docker pre-installed (e.g. the `official docker images `_) or install the client from within the `Dockerfile` specification. 2. The container has to have access to the docker daemon which can be achieved by mounting `/var/run/docker.sock` or setting the `DOCKER_HOST` environment variable as part of your `docker run` command. + +Private Docker registry +----------------------- + +Using a private docker registry requires the `DOCKER_AUTH_CONFIG` environment variable to be set. +`official documentation `_ + +The value of this variable should be a JSON string containing the authentication information for the registry. + +Example: + +.. code-block:: bash + + DOCKER_AUTH_CONFIG='{"auths": {"https://myregistry.com": {"auth": "dXNlcm5hbWU6cGFzc3dvcmQ="}}}' + +In order to generate the JSON string, you can use the following command: + +.. code-block:: bash + + echo -n '{"auths": {"": {"auth": "'$(echo -n ":" | base64 -w 0)'"}}}' + +Fetching passwords from cloud providers: + +.. code-block:: bash + + ECR_PASSWORD = $(aws ecr get-login-password --region eu-west-1) + GCP_PASSWORD = $(gcloud auth print-access-token) + AZURE_PASSWORD = $(az acr login --name --expose-token --output tsv) + + Configuration ------------- -+-------------------------------------------+-------------------------------+------------------------------------------+ -| Env Variable | Example | Description | -+===========================================+===============================+==========================================+ -| ``TESTCONTAINERS_DOCKER_SOCKET_OVERRIDE`` | ``/var/run/docker.sock`` | Path to Docker's socket used by ryuk | -+-------------------------------------------+-------------------------------+------------------------------------------+ -| ``TESTCONTAINERS_RYUK_PRIVILEGED`` | ``false`` | Run ryuk as a privileged container | -+-------------------------------------------+-------------------------------+------------------------------------------+ -| ``TESTCONTAINERS_RYUK_DISABLED`` | ``false`` | Disable ryuk | -+-------------------------------------------+-------------------------------+------------------------------------------+ -| ``RYUK_CONTAINER_IMAGE`` | ``testcontainers/ryuk:0.7.0`` | Custom image for ryuk | -+-------------------------------------------+-------------------------------+------------------------------------------+ ++-------------------------------------------+---------------------------------------------------+------------------------------------------+ +| Env Variable | Example | Description | ++===========================================+===================================================+==========================================+ +| ``TESTCONTAINERS_DOCKER_SOCKET_OVERRIDE`` | ``/var/run/docker.sock`` | Path to Docker's socket used by ryuk | ++-------------------------------------------+---------------------------------------------------+------------------------------------------+ +| ``TESTCONTAINERS_RYUK_PRIVILEGED`` | ``false`` | Run ryuk as a privileged container | ++-------------------------------------------+---------------------------------------------------+------------------------------------------+ +| ``TESTCONTAINERS_RYUK_DISABLED`` | ``false`` | Disable ryuk | ++-------------------------------------------+---------------------------------------------------+------------------------------------------+ +| ``RYUK_CONTAINER_IMAGE`` | ``testcontainers/ryuk:0.7.0`` | Custom image for ryuk | ++-------------------------------------------+---------------------------------------------------+------------------------------------------+ +| ``DOCKER_AUTH_CONFIG`` | ``{"auths": {"": {"auth": ""}}}`` | Custom registry auth config | ++-------------------------------------------+---------------------------------------------------+------------------------------------------+ Development and Contributing ---------------------------- -We recommend you use a `virtual environment `_ for development (:code:`python>=3.7` is required). After setting up your virtual environment, you can install all dependencies and test the installation by running the following snippet. + +We recommend you use a `Poetry `_ for development. +After having installed `poetry`, you can run the following snippet to set up your local dev environment. .. code-block:: bash - poetry install --all-extras - make /tests + make install Package Structure ^^^^^^^^^^^^^^^^^ -Testcontainers is a collection of `implicit namespace packages `__ to decouple the development of different extensions, e.g., :code:`testcontainers-mysql` and :code:`testcontainers-postgres` for MySQL and PostgreSQL database containers, respectively. The folder structure is as follows. +Testcontainers is a collection of `implicit namespace packages `__ +to decouple the development of different extensions, +e.g., :code:`testcontainers[mysql]` and :code:`testcontainers[postgres]` for MySQL and PostgreSQL database containers, respectively. + +The folder structure is as follows: .. code-block:: bash @@ -133,10 +174,11 @@ Testcontainers is a collection of `implicit namespace packages __`. +You want to contribute a new feature or container? Great! +- We recommend you first `open an issue `_ +- Then follow the suggestions from the team +- We also have a Pull Request `template `_ for new containers!