Overcast is alpha — behaviour and APIs may change between releases. Pin your version and read the changelog before upgrading.

overcast

ECR — Elastic Container Registry

Quick start, the Docker registry behind the control plane, how images are reconciled and persisted, and why repositoryUri names localhost over plain HTTP.

AWS’s ECR control-plane API in front of a real Docker registry, so a push lands bytes that ECS and Lambda can actually run.

Status: ⚠️ Partial

Quick start

export AWS_ENDPOINT_URL=http://localhost:4566

URI=$(aws ecr create-repository --repository-name my-app \
  --query 'repository.repositoryUri' --output text)   # localhost:4510/000000000000/my-app

aws ecr get-login-password | docker login --username AWS --password-stdin "${URI%%/*}"

docker tag my-app:latest "$URI:latest"
docker push "$URI:latest"

aws ecr describe-images --repository-name my-app

Any credentials work; with none configured, run eval "$(overcast env)" first — see Using AWS SDKs and CLI.

What works

AreaBehaviour
RepositoriesFull CRUD, policies, lifecycle policy and tag operations.
RegistryA shared registry:2 container, started lazily, on port OVERCAST_ECR_REGISTRY_PORT (default 4510).
AuthenticationGetAuthorizationToken returns base64("AWS:<password>"), valid 12 hours; the same password is provisioned into the registry via htpasswd.
Image inventoryReconciled against the registry on every repository read, in both directions — a manifest the registry serves is recorded, and a record it 404s is dropped.
PersistenceImages on the fixed port survive a restart in the named volume overcast-ecr-registry-data-<port>.
Running what you pushedECS task definitions and PackageType=Image Lambda functions resolve {account}.dkr.ecr.{region}.amazonaws.com/{repo}:{tag} to this registry.

Differences from AWS

AreaOn AWSOvercast
Repository URI host{account}.dkr.ecr.{region}.amazonaws.comlocalhost:<registryPort> — the address startup proved the Docker daemon can reach
TransportHTTPSPlain HTTP
Image scanningReal findingsNo scan engine at all: DescribeImageScanFindings always reports scanner-unavailable, PutImageScanningConfiguration stores a setting nothing acts on, and StartImageScan/Get/PutRegistryScanningConfiguration are not implemented
Image deletionDurableBatchDeleteImage removes the record only — an image the registry still serves reappears on the next reconciling read
Replication, public registriesSupportedNot implemented
Image storageManaged by AWSA Docker volume, reclaimed by Docker rather than by OVERCAST_DATA_DIR

Why the URI is re-minted on every read, why it says localhost rather than OVERCAST_HOSTNAME, and what happens when the fixed port is taken: Limitations.

Gotchas

Important

Without Docker there is no registry, and repositoryUri falls back to the API base URL. A docker push there answers 405 Method Not Allowed, because it is not a registry. CreateRepository marks that response with x-overcast-emulation-limitation, which becomes the resource’s ResourceStatusReason inside a CloudFormation deploy.

Removing the registry’s storage volume discards every image pushed to it, with nothing to rebuild them from — see Troubleshooting.

Operations

22 of 25 listed operations are implemented. Per-operation status, notes and AWS API links: ECR operations.