Fixed misc bugs

2025-10-15 13:31:18 +13:00
parent 9f5a25fcf5
commit 7580dc3f94
13 changed files with 609 additions and 47 deletions
@@ -0,0 +1,262 @@
+# 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/)