# Deploying from a Private Registry

Treza Enclaves support deploying images from private container registries that require authentication. Credentials are encrypted and stored securely in AWS Secrets Manager — they are never logged, exposed in the UI, or stored in plaintext.

***

### How It Works

```
Private Container Registry
(Docker Hub private, ECR, GHCR private, etc.)
          │
          ▼
    Treza Platform
    (credentials encrypted → AWS Secrets Manager)
          │
          ▼
    Treza Enclave provisioning
    (credentials fetched at deploy time, image pulled)
          │
          ▼
    Treza Enclave
    (image running in isolated enclave)
```

#### Step-by-step

1. **Name your enclave** — Give it a name and optional description.
2. **Select Private Registry** as the deployment source.
3. **Enter your registry credentials** — Provide the registry URL, username, and password/token.
4. **Enter your image URI** — The full image reference including the registry hostname.
5. **Configure your enclave** — Set the provider region and any other settings.
6. **Deploy** — Treza encrypts your credentials, stores them in AWS Secrets Manager, and uses them at deploy time to pull the image. Credentials are not persisted beyond the deployment lifecycle.

***

### Supported Registries

Any private OCI-compliant registry that accepts username/password or token-based authentication is supported, including:

| Registry                          | Registry URL                               | Auth Notes                                                               |
| --------------------------------- | ------------------------------------------ | ------------------------------------------------------------------------ |
| Docker Hub (private repos)        | `registry-1.docker.io`                     | Docker Hub username + access token                                       |
| GitHub Container Registry         | `ghcr.io`                                  | GitHub username + personal access token (PAT) with `read:packages` scope |
| Amazon ECR (private)              | `<account>.dkr.ecr.<region>.amazonaws.com` | AWS access key + secret, or use IAM role (recommended)                   |
| Google Artifact Registry          | `<region>-docker.pkg.dev`                  | Service account JSON or access token                                     |
| Azure Container Registry          | `<registry>.azurecr.io`                    | ACR username + password, or service principal                            |
| Self-hosted (Harbor, Nexus, etc.) | Custom hostname                            | Username + password                                                      |

***

### Credentials & Security

#### How credentials are stored

* Credentials are encrypted at rest using AWS KMS and stored in **AWS Secrets Manager** under a secret scoped to your enclave.
* The secret is referenced by ARN in the enclave record — the plaintext credentials are never written to the database.
* At deploy time, the Treza infrastructure fetches the secret from Secrets Manager to authenticate the image pull, then the credential reference is released.

#### Credential lifecycle

| Phase               | What happens                                               |
| ------------------- | ---------------------------------------------------------- |
| Enclave creation    | Credentials encrypted and stored in Secrets Manager        |
| Deployment          | Credentials fetched from Secrets Manager to pull the image |
| Post-deployment     | Secret remains in Secrets Manager for re-deployment use    |
| Enclave termination | Secret is deleted from Secrets Manager                     |

#### Recommended: use access tokens, not passwords

Where possible, use short-lived access tokens or tokens with minimal scope rather than account passwords:

* **Docker Hub** — Create a [personal access token](https://hub.docker.com/settings/security) with `Read-only` access
* **GitHub** — Create a [fine-grained PAT](https://github.com/settings/tokens) with `read:packages` scope only
* **ECR** — Prefer IAM roles over access keys; contact <support@treza.xyz> to configure IAM-based ECR access

***

### Image URI Format

For private registries, always use the fully qualified image reference:

```
<registry-hostname>/<namespace>/<image>:<tag>
```

**Examples:**

| Registry                | Example URI                                               |
| ----------------------- | --------------------------------------------------------- |
| Docker Hub private repo | `registry-1.docker.io/my-org/private-app:v2.1`            |
| GHCR                    | `ghcr.io/my-org/private-service:main`                     |
| Amazon ECR              | `123456789.dkr.ecr.us-east-1.amazonaws.com/my-app:latest` |
| Azure ACR               | `myregistry.azurecr.io/my-image:stable`                   |

***

### Enclave Statuses

| Status           | Description                                                                      |
| ---------------- | -------------------------------------------------------------------------------- |
| `PENDING_DEPLOY` | Deployment queued; credentials have been stored                                  |
| `DEPLOYING`      | Infrastructure provisioning and image pull in progress                           |
| `DEPLOYED`       | Enclave is live and running                                                      |
| `FAILED`         | Deployment failed — check the **Infrastructure** log tab for auth or pull errors |

***

### Using the CLI

```bash
treza enclave create \
  --name my-enclave \
  --provider aws-nitro \
  --source-type private-registry \
  --image myregistry.azurecr.io/my-image:stable \
  --registry-url myregistry.azurecr.io \
  --registry-username myuser \
  --registry-password mypassword
```

For interactive prompts, omit the flags:

```bash
treza enclave create
```

> **Security note:** Avoid passing `--registry-password` directly in your shell history. Use the interactive prompt instead, or pipe the value from a secrets manager:
>
> ```bash
> treza enclave create --registry-password "$(vault kv get -field=password secret/my-registry)"
> ```

***

### Troubleshooting

#### Deployment failed: authentication required / unauthorized

* Verify the registry URL, username, and password/token are correct.
* Confirm the token has sufficient permissions to pull the image (not just list repositories).
* For Docker Hub, ensure the access token was created with at least `Read` access.
* For GHCR, ensure the PAT has the `read:packages` scope and the package is accessible to the account.

#### Deployment failed: image not found (after successful auth)

The credentials are valid but the image reference is incorrect. Double-check:

* The registry hostname matches the credentials (e.g., `ghcr.io` not `docker.io`)
* The namespace/org name matches exactly (case-sensitive)
* The tag exists in the registry

#### Credentials expired after deployment

Access tokens can expire. To update credentials for an existing enclave, terminate the current enclave and create a new one with refreshed credentials. Credential rotation support for live enclaves is on the roadmap.

***

### Related

* Deploying from a Container Registry
* Deploying from a GitHub Repository
* Enclave Lifecycle
* Enclave Logs


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.trezalabs.com/enclaves/deploying-from-a-private-registry.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.