> For the complete documentation index, see [llms.txt](https://bluebricks.co/docs/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://bluebricks.co/docs/orchestration/packages/artifacts-overview/generic/container-config.md).

# Container Configuration

Configure how your Generic artifact's Docker container runs, including the image, entry command, arguments, and environment variables.

## Native configuration fields

All container settings live under the `native` key in `bricks.json`:

<table><thead><tr><th width="107.49609375">Field</th><th width="93.1953125">Type</th><th width="108.953125">Required</th><th width="152.1796875">Default</th><th>Description</th></tr></thead><tbody><tr><td><code>type</code></td><td>string</td><td>Yes</td><td>:</td><td>Must be <code>"generic"</code></td></tr><tr><td><code>path</code></td><td>string</td><td>Yes</td><td>:</td><td>Path to source files relative to package root. Mounted as <code>/workspace</code></td></tr><tr><td><code>image</code></td><td>string</td><td>No</td><td><code>busybox:stable</code></td><td>Docker image to use. Must come from an <a href="#approved-container-registries">approved registry</a></td></tr><tr><td><code>command</code></td><td>array</td><td>No</td><td>Image's CMD</td><td>Entry command array</td></tr><tr><td><code>args</code></td><td>array</td><td>No</td><td>:</td><td>Arguments appended to command</td></tr><tr><td><code>env_vars</code></td><td>object</td><td>No</td><td>:</td><td>Key-value map of environment variables injected into the container</td></tr></tbody></table>

## Configuration examples

{% tabs %}
{% tab title="Python" %}

```json
{
  "native": {
    "type": "generic",
    "path": "./src",
    "image": "python:3.11-slim",
    "command": ["/bin/bash", "-c"],
    "args": [
      "pip install -r /workspace/requirements.txt && python /workspace/scripts/main.py"
    ],
    "env_vars": {
      "PYTHONUNBUFFERED": "1",
      "PYTHONPATH": "/workspace"
    }
  }
}
```

{% endtab %}

{% tab title="Node.js" %}

```json
{
  "native": {
    "type": "generic",
    "path": "./src",
    "image": "node:18-alpine",
    "command": ["node"],
    "args": ["/workspace/app.js"],
    "env_vars": {
      "NODE_ENV": "production"
    }
  }
}
```

{% endtab %}

{% tab title="Bash" %}

```json
{
  "native": {
    "type": "generic",
    "path": "./src",
    "image": "alpine:latest",
    "command": ["/bin/sh"],
    "args": ["/workspace/scripts/deploy.sh"],
    "env_vars": {
      "DEBUG": "false"
    }
  }
}
```

{% endtab %}

{% tab title="Multi-step" %}

```json
{
  "native": {
    "type": "generic",
    "path": "./src",
    "image": "python:3.11-slim",
    "command": ["/bin/bash", "-c"],
    "args": [
      "python /workspace/step1.py && python /workspace/step2.py && python /workspace/step3.py"
    ]
  }
}
```

{% endtab %}
{% endtabs %}

## Approved container registries

Only images from the registries below are accepted at publish time:

<table><thead><tr><th width="304.3125">Registry</th><th>Description</th></tr></thead><tbody><tr><td><code>docker.io</code></td><td>Docker Hub</td></tr><tr><td><code>ghcr.io</code></td><td>GitHub Container Registry</td></tr><tr><td><code>quay.io</code></td><td>Red Hat Quay</td></tr><tr><td><code>registry.gitlab.com</code></td><td>GitLab Container Registry</td></tr><tr><td><code>mcr.microsoft.com</code></td><td>Microsoft Container Registry</td></tr><tr><td><code>gcr.io</code></td><td>Google Container Registry</td></tr><tr><td><code>artifactregistry.googleapis.com</code></td><td>Google Artifact Registry</td></tr><tr><td><code>ecr.aws</code></td><td>AWS ECR</td></tr><tr><td><code>*.us-east-1.amazonaws.com</code></td><td>AWS ECR us-east-1</td></tr><tr><td><code>*.eu-west-1.amazonaws.com</code></td><td>AWS ECR eu-west-1</td></tr></tbody></table>

{% hint style="warning" %}
Images from registries not on this list are rejected at publish time. If you need a registry added, contact Bluebricks support.
{% endhint %}

## Best practices

### Image selection

* **Pin versions**: use `python:3.11-slim` instead of `python:latest` for reproducible builds
* **Use minimal images**: Alpine-based images pull faster and have a smaller attack surface
* **Pin digests for production**: `python@sha256:...` guarantees byte-for-byte reproducibility
* **Choose official images**: prefer images from trusted publishers

### Command configuration

* **Be explicit**: always specify `command` and `args` rather than relying on image defaults
* **Use absolute paths**: reference `/workspace/` for all mounted files
* **Handle errors in scripts**: use `set -e` in Bash scripts so failures propagate

### Environment variables

* **Use `env_vars` for static config**: values known at publish time (log levels, feature flags)
* **Use props for dynamic config**: values that change per collection or deployment
* **Never put secrets in `env_vars`**: use Bluebricks secrets instead; they're injected separately at runtime