# 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