# Docker

---

## Overview

Push, pull, and deploy Docker images through Fly Registry. Your images are stored securely, linked to releases, and tracked all the way to your runtime environments.

JFrog Fly supports OCI (Open Container Initiative) native images, ensuring compatibility across container tools like Docker, Docker Buildx, and Podman.

---

## Supported Clients

JFrog Fly supports container images built with:

- **Docker CLI** (`docker build`, `docker push`, `docker pull`) - The standard Docker command-line interface for building and managing container images

- **Docker Buildx** (`docker buildx build --push`) - Docker's extended build capabilities with BuildKit, supporting multi-platform images (e.g., amd64 and arm64), improved caching, and advanced build features

- **Podman** (`podman build`, `podman push`, `podman pull`) - Daemonless container engine, fully compatible with Docker images

All tools push and pull images using the same registry format, so images built with any tool are fully compatible.

---

## Upload / Push Image

### With Fly App

Activate Docker in your Fly App to automatically authenticate, then push your image:

```bash
docker push <your-fly-subdomain>.jfrog.io/docker/my-image:latest
```

### Manual Configuration

**1. Generate an access token** in Fly Token Management

**2. Login to Docker:**

```bash
docker login <your-fly-subdomain>.jfrog.io -u <your-fly-username> -p <your-fly-token>
```

**3. Push your image:**

```bash
docker push <your-fly-subdomain>.jfrog.io/docker/my-image:latest
```

---

## Download / Pull Image

### With Fly App

Activate Docker in your Fly App to automatically authenticate, then pull your image:

```bash
docker pull <your-fly-subdomain>.jfrog.io/docker/my-image:latest
```

### Manual Configuration

**1. Generate an access token** in Fly Token Management

**2. Login to Docker:**

```bash
docker login <your-fly-subdomain>.jfrog.io -u <your-fly-username> -p <your-fly-token>
```

**3. Pull your image:**

```bash
docker pull <your-fly-subdomain>.jfrog.io/docker/my-image:latest
```

### From Public Registry

Activate Docker in your Fly App (or login manually as shown above), then pull from public registries.

When you pull an image that isn't in your Fly Registry, JFrog Fly automatically fetches it from DockerHub and caches it for future use.

```bash
docker pull <your-fly-subdomain>.jfrog.io/docker/nginx:latest
```

---

## Push/Pull Images with CI

To push and pull Docker images with CI, update your GitHub Actions workflow to include the Fly action.

Simply ask your coding agent: **"Configure my workflows with Fly"** and Fly MCP will configure your GitHub Actions workflow yml file, as follows:

**1. Add permissions** (top level, after `on:`):
```yaml
permissions:
  contents: read
  id-token: write
```

**2. Add Fly Action** (after package manager setup steps like `actions/setup-node`, before artifact operations like `npm install`, `docker push`):
```yaml
- uses: jfrog/fly-action@v1              # Setup Fly package managers
```

**3. Use the `FLY_REGISTRY_SUBDOMAIN` environment variable** (exported by the Fly action, e.g., `acmecorp.jfrog.io`) in your image path: `${{ env.FLY_REGISTRY_SUBDOMAIN }}/docker/my-app:tag`

### GitHub Action Example

```yaml
name: Build and Push Docker Image

on:
  push:
    branches: [main]

permissions:
  contents: read
  id-token: write

jobs:
  build:
    runs-on: ubuntu-latest

    steps:
      - uses: actions/checkout@v4

      - uses: jfrog/fly-action@v1              # Setup Fly package managers

      - run: docker build -t ${{ env.FLY_REGISTRY_SUBDOMAIN }}/docker/my-app:${{ github.sha }} .
        # Base images pulled from Fly registry

      - run: docker push ${{ env.FLY_REGISTRY_SUBDOMAIN }}/docker/my-app:${{ github.sha }}
        # Push to Fly registry
```

---

## Deployment to Runtime

To deploy your Docker image to your runtime environment, you need a Fly image secret. If you don't have one:

- **Option A:** Ask your coding agent to deploy the image, and Fly MCP will add the token in a secure way
- **Option B:** Generate a new token in Fly Token Management and add it to your Kubernetes cluster or other container orchestration platform

### Pull Docker Secret to K8s

Here's an example of how to create an image pull secret with your Fly credentials:

```bash
kubectl create secret docker-registry <secret-name> \
  --docker-server=<your-fly-subdomain>.jfrog.io/docker \
  --docker-username=<your-fly-username> \
  --docker-password=<your-fly-token> \
  --namespace=<namespace>
```

> [!NOTE]
> Replace `<secret-name>` with any name you choose (e.g., `fly-registry-secret`). Use `<your-fly-username>` and `<your-fly-token>` from Fly Token Management.

Use the Fly Registry image path in your deployment: `<your-fly-subdomain>.jfrog.io/docker/<image-name>:<tag>`

**Example:** `acmecorp.jfrog.io/docker/payment-service:v2.3.1`

---

*Back to [Package Managers →](../)*