Docker Images

Pull container images from GHCR through a clean vanity registry URL. Docker sees easy-install.sh as a standard OCI registry and handles authentication transparently.

Quick Start

Pull your first image

Replace namespace and project with your GitHub username/org and repo name.

docker pull easy-install.sh/acme/api

Deep Dive

How it works

When you run docker pull easy-install.sh/acme/api, here's what happens under the hood:

  1. Registry handshake

    Docker sends GET /v2/ to verify that easy-install.sh speaks the OCI Distribution spec. The proxy responds with 200 OK and the required headers.

    GET https://easy-install.sh/v2/

  2. Manifest request

    Docker requests the image manifest. The proxy fetches it from GHCR using an anonymous token and streams the response back.

    GET https://easy-install.sh/v2/acme/api/manifests/latest

  3. Analytics recorded

    The proxy fires off an analytics event (fire-and-forget) with the pull metadata. This never blocks the Docker pull. The pull continues regardless of whether analytics succeeds.

  4. Blob streaming

    Docker fetches the image layers (blobs). Each blob request is proxied through to GHCR and streamed directly to the Docker client. The proxy never buffers entire layers in memory.

    GET https://easy-install.sh/v2/acme/api/blobs/sha256:abc123...

  5. Image ready

    Once all layers are pulled, the image is available locally just like any other Docker image. Run it, tag it, push it elsewhere. It's a standard OCI image.

Routing

Namespace mapping

The URL path maps directly to a GHCR image path. No configuration required. The namespace and project in your URL correspond exactly to your GitHub identity and repository.

easy-install.sh URLGHCR Path
acme/apighcr.io/acme/api
jane/cli-toolghcr.io/jane/cli-tool
my-org/backendghcr.io/my-org/backend

Tags

Tag resolution

Tags work exactly like any Docker registry. If omitted, Docker defaults to :latest.

Latest (default)

docker pull easy-install.sh/acme/api

Equivalent to easy-install.sh/acme/api:latest

Explicit tag

docker pull easy-install.sh/acme/api:v2.1.0

Digest reference

docker pull easy-install.sh/acme/api@sha256:a1b2c3d4...

Pinning by digest guarantees you get the exact same image every time.

Security

Authentication

GHCR requires a token even for public images. The proxy handles this automatically using the standard Docker token exchange flow:

  1. Initial request (unauthenticated) — The proxy calls GHCR without credentials. GHCR responds with 401 Unauthorized and a Www-Authenticate header pointing to its token endpoint.

  2. Token exchange — The proxy requests an anonymous token from GHCR's token service, scoped to the specific repository being pulled.

  3. Authenticated retry — The proxy retries the original request with the token in the Authorization: Bearer header. GHCR serves the content.

Note

You never need to docker login to easy-install.sh. The proxy handles all token exchange behind the scenes for public images.

Analytics

What gets tracked

Each Docker pull records the following anonymous metadata. No personal information is collected.

FieldDescription
NamespaceGitHub user or org
ProjectRepository name
Tag / DigestWhich version was pulled
TimestampWhen the pull occurred (UTC)
CountryDerived from IP via geo lookup
User-AgentDocker client version string

Note

IP addresses are used only for geo lookup and are never stored. Analytics are fully anonymous.

Examples

Common usage

Pull and run

docker pull easy-install.sh/acme/api:latest
docker run -p 8080:8080 easy-install.sh/acme/api:latest

Use in a Dockerfile

Dockerfile
FROM easy-install.sh/acme/api:v2.1.0
COPY ./config /app/config
CMD ["/app/server"]

Docker Compose

docker-compose.yml
services:
  api:
    image: easy-install.sh/acme/api:v2
    ports:
      - '8080:8080'

Pin to a specific digest

docker pull easy-install.sh/acme/api@sha256:a1b2c3d4e5f6...

Limitations

Current limitations

GHCR only

Docker forwarding currently only supports GitHub Container Registry (ghcr.io). Docker Hub, ECR, and other registries are not supported.