BDFR_Web/DOCKER_PUBLISH.md

# Publishing BDFR Web Interface to Docker Hub

This guide covers how to build and push the Docker image to Docker Hub.

## Prerequisites

1. **Docker Hub Account**: Create one at https://hub.docker.com if you don't have one
2. **Docker installed**: Ensure Docker is running on your machine

## Step 1: Login to Docker Hub

Open your terminal and login:

```bash
docker login
```

Enter your Docker Hub username and password when prompted.

## Step 2: Build the Image with Proper Tagging

Build the image with your Docker Hub username and desired repository name:

```bash
# Replace 'yourusername' with your actual Docker Hub username
# Replace 'bdfr-web' with your desired repository name (or keep it)

docker build -t yourusername/bdfr-web:latest .

# You can also add version tags
docker build -t yourusername/bdfr-web:latest -t yourusername/bdfr-web:1.0.0 .
```

**Example:**
```bash
docker build -t danielsmith/bdfr-web:latest -t danielsmith/bdfr-web:1.0.0 .
```

## Step 3: Test the Image Locally (Optional but Recommended)

Before pushing, verify the image works:

```bash
docker run -d -p 8000:8000 \
  -v $(pwd)/downloads:/downloads \
  -v $(pwd)/data:/app/data \
  --name bdfr-test \
  yourusername/bdfr-web:latest
```

Visit `http://localhost:8000` to verify it works, then clean up:

```bash
docker stop bdfr-test
docker rm bdfr-test
```

## Step 4: Push to Docker Hub

Push the image to Docker Hub:

```bash
# Push latest tag
docker push yourusername/bdfr-web:latest

# If you created a version tag, push that too
docker push yourusername/bdfr-web:1.0.0
```

## Step 5: Verify the Push

1. Go to https://hub.docker.com
2. Navigate to your repositories
3. You should see `bdfr-web` listed
4. Click on it to see tags and details

## Using the Published Image

Others can now pull and use your image:

```bash
docker pull yourusername/bdfr-web:latest
docker run -d -p 8000:8000 -v ./downloads:/downloads yourusername/bdfr-web:latest
```

Or using docker-compose, update [`docker-compose.yml`](docker-compose.yml):

```yaml
services:
  bdfr-web:
    image: yourusername/bdfr-web:latest  # Replace 'build:' section with this
    # ... rest of configuration
```

## Automated Build with Docker Hub

You can set up automated builds that trigger when you push to GitHub:

1. Go to https://hub.docker.com
2. Navigate to your repository
3. Click "Builds" tab
4. Click "Configure Automated Builds"
5. Connect your GitHub account
6. Select your repository
7. Configure build rules (e.g., build on push to main branch)

## Multi-Platform Builds (Optional)

To build for multiple architectures (amd64, arm64, etc.):

### Setup buildx (one-time setup)

```bash
# Create a new builder
docker buildx create --name multiplatform --use

# Bootstrap the builder
docker buildx inspect --bootstrap
```

### Build and push multi-platform image

```bash
docker buildx build \
  --platform linux/amd64,linux/arm64 \
  -t yourusername/bdfr-web:latest \
  -t yourusername/bdfr-web:1.0.0 \
  --push \
  .
```

This creates images that work on both x86_64 (Intel/AMD) and ARM64 (Apple Silicon, Raspberry Pi, etc.).

## Updating Your Published Image

When you make changes:

1. **Update version**: Increment version in tags (e.g., 1.0.0 → 1.0.1)
2. **Rebuild**: 
   ```bash
   docker build -t yourusername/bdfr-web:latest -t yourusername/bdfr-web:1.0.1 .
   ```
3. **Push**:
   ```bash
   docker push yourusername/bdfr-web:latest
   docker push yourusername/bdfr-web:1.0.1
   ```

## Best Practices

### Tagging Strategy

- `latest`: Always points to the most recent stable build
- `1.0.0`, `1.0.1`: Specific version tags for reproducibility
- `1.0`, `1`: Major/minor version tags
- `dev`: Development/unstable builds

Example tagging:
```bash
docker build -t yourusername/bdfr-web:latest \
             -t yourusername/bdfr-web:1.0.1 \
             -t yourusername/bdfr-web:1.0 \
             -t yourusername/bdfr-web:1 .
```

### Repository Description

Add a good description to your Docker Hub repository:

1. Go to your repository on Docker Hub
2. Click "Description" tab
3. Add a README with:
   - What the image does
   - How to use it
   - Environment variables
   - Volume mounts
   - Example docker-compose.yml

### Size Optimization

Current image uses multi-stage builds and is already optimized. To check size:

```bash
docker images yourusername/bdfr-web
```

## Complete Script

Here's a complete script to build and push (save as `publish-docker.sh`):

```bash
#!/bin/bash
set -e

# Configuration
DOCKER_USERNAME="yourusername"
IMAGE_NAME="bdfr-web"
VERSION="1.0.0"

# Build
echo "Building Docker image..."
docker build -t ${DOCKER_USERNAME}/${IMAGE_NAME}:latest \
             -t ${DOCKER_USERNAME}/${IMAGE_NAME}:${VERSION} .

# Test
echo "Testing image..."
docker run --rm ${DOCKER_USERNAME}/${IMAGE_NAME}:latest bdfr --version

# Login (if not already logged in)
echo "Logging in to Docker Hub..."
docker login

# Push
echo "Pushing to Docker Hub..."
docker push ${DOCKER_USERNAME}/${IMAGE_NAME}:latest
docker push ${DOCKER_USERNAME}/${IMAGE_NAME}:${VERSION}

echo "Done! Image published to:"
echo "  docker pull ${DOCKER_USERNAME}/${IMAGE_NAME}:latest"
echo "  docker pull ${DOCKER_USERNAME}/${IMAGE_NAME}:${VERSION}"
```

Make it executable:
```bash
chmod +x publish-docker.sh
./publish-docker.sh
```

## Troubleshooting

### "denied: requested access to the resource is denied"

- Make sure you're logged in: `docker login`
- Verify your username in the image tag matches your Docker Hub username
- Check that the repository exists or that you have permissions

### "image not found" after push

- Wait a few minutes - Docker Hub indexing can be delayed
- Refresh the Docker Hub web page
- Try pulling: `docker pull yourusername/bdfr-web:latest`

### Large image size

Current image should be ~500-800MB. If larger:
- Check that `.dockerignore` is working
- Verify multi-stage build is being used
- Clean up any unnecessary files in the image

## Private Repositories

To make your repository private:

1. Go to Docker Hub repository settings
2. Change visibility to "Private"
3. Users will need to login to pull: `docker login` before `docker pull`

## Additional Resources

- [Docker Hub Documentation](https://docs.docker.com/docker-hub/)
- [Dockerfile Best Practices](https://docs.docker.com/develop/develop-images/dockerfile_best-practices/)
- [Docker Buildx Documentation](https://docs.docker.com/buildx/working-with-buildx/)