Merge branch 'main' into mssql

.github/workflows/test.yml

@@ -84,12 +84,14 @@ jobs:
           - elasticsearch
           - hivemq
           - kafka
+          - localstack
           - mongodb
           - mssqlserver
           - mysql
           - nats
           - neo4j
           - postgresql
+          - redis
           - selenium
     uses: ./.github/workflows/test-template.yml
     with:

CONTRIBUTING.md

@@ -0,0 +1,30 @@
+# Contributing
+
+[Create an issue](https://github.com/testcontainers/testcontainers-node/issues) if you find any bugs.
+
+[Create a pull request](https://github.com/testcontainers/testcontainers-node/pulls) if you wish to fix an issue or provide an enhancement. Please be sure to:
+* Discuss with the authors via an issue or discussion prior to doing anything big.
+* Follow the style, structure and naming conventions of the rest of the project.
+* Make commits atomic and easy to merge.
+* Run the Git hooks when making commits to ensure the code is linted and correctly formatted.
+* Verify all tests are passing with `npm test`.
+
+## Documentation
+
+The documentation is a static site built with [MkDocs](https://www.mkdocs.org/) and the [Material for MkDocs](https://squidfunk.github.io/mkdocs-material/) theme. In addition, we use a [custom plugin](https://github.com/rnorth/mkdocs-codeinclude-plugin) for inclusion of code snippets. We publish our documentation using Netlify.
+
+### Previewing rendered content
+
+#### Using Docker
+
+The root of the project contains a `docker-compose.yml` file. Simply run `docker-compose up` and then access the docs at [http://localhost:8000](http://localhost:8000).
+
+#### Using Python
+
+* Ensure that you have Python 3.8.0 or higher.
+* Set up a virtualenv and run `pip install -r requirements.txt` in the `testcontainers-node` root directory.
+* Once Python dependencies have been installed, run `mkdocs serve` to start a local auto-updating MkDocs server.
+
+#### PR Preview deployments
+
+Documentation for pull requests will automatically be published by Netlify as 'deploy previews'. These deployment previews can be accessed via the `deploy/netlify` check that appears for each pull request.

docs/features/advanced.md

@@ -0,0 +1,42 @@
+# Advanced
+
+## Container Runtime Client
+
+Testcontainers configures an underlying container runtime to perform its tasks. This runtime works automatically with several providers like Docker, Podman, Colima, Rancher Desktop and Testcontainers Desktop. There are too many usage examples to list here, but here are some common examples:
+
+### Fetch container runtime information
+
+```js
+import { getContainerRuntimeClient } from "testcontainers";
+
+const containerRuntimeClient = await getContainerRuntimeClient();
+
+console.log(containerRuntimeClient.info);
+```
+
+### Pulling an image
+
+```js
+import { ImageName } from "testcontainers";
+
+await containerRuntimeClient.image.pull(ImageName.fromString("alpine:3.12"))
+```
+
+### Starting a container
+
+```js
+const container = await containerRuntimeClient.container.create({ ... });
+await containerRuntimeClient.container.start(container);
+```
+
+### Starting a Docker Compose environment
+
+```js
+const environment = await containerRuntimeClient.compose.up({ ... })
+```
+
+### Starting a network
+
+```js
+const network = await containerRuntimeClient.network.create({ ... })
+```

docs/features/containers.md

@@ -495,6 +495,9 @@ const container = await new GenericContainer("alpine")
 
 ## Running commands
 
+To run a command inside an already started container use the `exec` method. The command will be run in the container's 
+working directory, returning the command output and exit code:
+
 ```javascript
 const container = await new GenericContainer("alpine")
   .withCommand(["sleep", "infinity"])
@@ -503,6 +506,30 @@ const container = await new GenericContainer("alpine")
 const { output, exitCode } = await container.exec(["echo", "hello", "world"]);
 ```
 
+The following options can be provided to modify the command execution:
+
+1. **`user`:** The user, and optionally, group to run the exec process inside the container. Format is one of: `user`, `user:group`, `uid`, or `uid:gid`.
+
+2. **`workingDir`:** The working directory for the exec process inside the container.
+
+3. **`env`:** A map of environment variables to set inside the container.
+
+
+```javascript
+const container = await new GenericContainer("alpine")
+  .withCommand(["sleep", "infinity"])
+  .start();
+
+const { output, exitCode } = await container.exec(["echo", "hello", "world"], {
+	workingDir: "/app/src/",
+	user: "1000:1000",
+	env: {
+		"VAR1": "enabled",
+		"VAR2": "/app/debug.log",
+	}
+});
+````
+
 ## Streaming logs
 
 Logs can be consumed either from a started container:
@@ -527,3 +554,14 @@ const container = await new GenericContainer("alpine")
   })
   .start();
 ```
+
+You can specify a point in time as a UNIX timestamp from which you want the logs to start: 
+
+```javascript
+const msInSec = 1000;
+const tenSecondsAgoMs = new Date().getTime() - 10 * msInSec;
+const since = tenSecondsAgoMs / msInSec;
+
+(await container.logs({ since }))
+  .on("data", line => console.log(line))
+```

docs/modules/localstack.md

@@ -0,0 +1,15 @@
+# Localstack Module
+
+[Localstack](https://www.localstack.cloud/): Develop and test your AWS applications locally to reduce development time and increase product velocity
+
+## Install
+
+```bash
+npm install @testcontainers/localstack --save-dev
+```
+
+## Examples
+
+<!--codeinclude-->
+[Create a S3 bucket:](../../packages/modules/localstack/src/localstack-container.test.ts) inside_block:createS3Bucket
+<!--/codeinclude-->

docs/modules/redis.md

@@ -0,0 +1,31 @@
+# Redis Module
+
+[Redis](https://redis.io/) The open source, in-memory data store used by millions of developers as a database, cache, streaming engine, and message broker.
+
+## Install
+
+```bash
+npm install @testcontainers/redis --save-dev
+```
+
+## Examples
+
+<!--codeinclude-->
+[Start container:](../../packages/modules/redis/src/redis-container.test.ts) inside_block:startContainer
+<!--/codeinclude-->
+
+<!--codeinclude-->
+[Connect redis client to container:](../../packages/modules/redis/src/redis-container.test.ts) inside_block:simpleConnect
+<!--/codeinclude-->
+
+<!--codeinclude-->
+[Start container with password authentication:](../../packages/modules/redis/src/redis-container.test.ts) inside_block:startWithCredentials
+<!--/codeinclude-->
+
+<!--codeinclude-->
+[Define volume for persistent/predefined data:](../../packages/modules/redis/src/redis-container.test.ts) inside_block:persistentData
+<!--/codeinclude-->
+
+<!--codeinclude-->
+[Execute a command inside the container:](../../packages/modules/redis/src/redis-container.test.ts) inside_block:executeCommand
+<!--/codeinclude-->

mkdocs.yml

@@ -40,6 +40,7 @@ nav:
       - Networking: features/networking.md
       - Compose: features/compose.md
       - Wait strategies: features/wait-strategies.md
+      - Advanced: features/advanced.md
   - Modules:
       - ArangoDB: modules/arangodb.md
       - Elasticsearch: modules/elasticsearch.md
@@ -52,4 +53,5 @@ nav:
       - Neo4J: modules/neo4j.md
       - PostgreSQL: modules/postgresql.md
       - Selenium: modules/selenium.md
+      - Redis: modules/redis.md
   - Configuration: configuration.md