Keep copies of public packages

Connect the write and read paths#

Set mirrorTarget to the repository receiving public copies. Set privateUpstream to the private endpoint clients read through Écluse.

Configure that read endpoint to include the mirror repository. Écluse does not create this relationship in your registry.

Example: npm with CodeArtifact

mounts:
  npm:
    privateUpstream:
      codeArtifact:
        url: https://DOMAIN-ACCOUNT.d.codeartifact.REGION.amazonaws.com/npm/internal/
    mirrorTarget:
      codeArtifact:
        url: https://DOMAIN-ACCOUNT.d.codeartifact.REGION.amazonaws.com/npm/mirror/

Replace the domain, account, and region values with your repository endpoints. Keep the mirror, private read repository, and publication repository distinct if you plan to use cleanup.

Choose where the worker runs#

proxy includes a mirror worker. For separate services, run proxy --no-worker and mirror against the same durable SQS queue.

Durable queue

queue:
  url: https://sqs.REGION.amazonaws.com/ACCOUNT/ecluse-mirror

The in-memory queue suits a single-process trial. It cannot connect separate processes and loses queued work on restart.

Give the proxy permission to enqueue. Give the worker permission to consume, renew visibility, acknowledge jobs, and publish to the mirror.

A CodeArtifact worker mints its token from workload identity. Generic registries use the mirror's configured write credential.

For PyPI, add completion state#

PyPI needs an explicit native upload endpoint and durable state in addition to its registry read URL:

Example: PyPI mirror additions

mirrorState:
  url: s3://your-mirror-state-bucket/pypi
mounts:
  pypi:
    privateUpstream:
      codeArtifact:
        url: https://DOMAIN-ACCOUNT.d.codeartifact.REGION.amazonaws.com/pypi/internal/
    mirrorTarget:
      codeArtifact:
        url: https://DOMAIN-ACCOUNT.d.codeartifact.REGION.amazonaws.com/pypi/mirror/
        uploadUrl: https://DOMAIN-ACCOUNT.d.codeartifact.REGION.amazonaws.com/pypi/mirror/

The proxy needs state reads and prefix listing. The worker also needs conditional writes. Both use the same bucket, prefix, and target identity.

Do not expire state records or referenced metadata companions. The state proves which files form a complete version. Package archives remain in the registry.

Verify a complete copy#

An admitted artifact download triggers background mirroring. The worker checks current policy before copying. For PyPI, it copies every supported distribution in the admitted version.

Confirm completion before relying on the mirror during an outage. Then verify a private read with fresh client state.

Read the completion and recovery rules for partial uploads, retries, and public outages.