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:

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:

# 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:

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:

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:

docker stop bdfr-test
docker rm bdfr-test

Step 4: Push to Docker Hub

Push the image to Docker Hub:

# 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:

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:

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)

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

# Bootstrap the builder
docker buildx inspect --bootstrap

Build and push multi-platform image

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:

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

3. Push:

   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:

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:

docker images yourusername/bdfr-web

Complete Script

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

#!/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:

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
• Dockerfile Best Practices
• Docker Buildx Documentation