Skip to content

Building Custom Docker Images

Jump to bottom Edit New page
crocodilestick edited this page Oct 27, 2025 · 1 revision

Building Custom Docker Images

This guide explains how to build custom Docker images of Calibre-Web Automated using the build.sh script.

Table of Contents

What is build.sh?

build.sh is a convenience script that automates the process of building custom Docker images of Calibre-Web Automated. It handles:

  • Repository cloning (or uses your local checkout)
  • Version tagging for dev and production builds
  • Build argument injection (version, build date)
  • Docker image creation with proper naming conventions

The script is located at the root of the CWA repository: build.sh

When to Use It

Use build.sh when you need to:

  • Test local changes before pushing to GitHub
  • Build from a fork or custom branch
  • Create versioned images for deployment
  • Automate builds in CI/CD pipelines
  • Develop new features with live-reload capabilities

Note: If you just want to use CWA, you don't need this script - use the official Docker images instead.

Prerequisites

Before running build.sh, ensure you have:

  1. bash - The script requires bash shell
  2. git - For cloning the repository (unless using -l flag)
  3. docker - Docker daemon must be running
  4. Permissions - User must have Docker access (typically via docker group)

Check your setup:

# Verify dependencies
bash --version
git --version
docker --version

# Test Docker access
docker info

Quick Start

Interactive Mode (Original Behavior)

Simply run the script without arguments and follow the prompts:

cd /path/to/calibre-web-automated
./build.sh

The script will ask you to provide:

  1. Directory where repo should be cloned
  2. Docker Hub username for image tagging
  3. Build type (development or production)
  4. Version number
  5. Test number (for dev builds)

Local Development Build (New Feature)

Build from your current working directory without cloning:

cd /path/to/your-cwa-fork
./build.sh -l -u myusername -v v3.2.0-dev -r 1

This creates a dev image tagged as myusername/calibre-web-automated:dev-1

Command-Line Options

Flag Argument Description
-l None Local build mode - Skip git clone, build from current directory
-u DH_USER Docker Hub username for image tagging
-v VERSION Version number (e.g., v3.1.5 or v3.2.0-dev)
-r TESTNUM Test version number (numeric only, for dev builds)
-d REPO_DIR Directory to clone repo into (ignored with -l)
-c CLONE_URL Git URL to clone from (default: official CWA repo)
-h None Show help message and exit

Flag Behavior

  • Flags override prompts: If you provide a value via flag, the script won't ask for it
  • Partial automation: Mix flags with interactive prompts (provide some, get prompted for rest)
  • Environment variables: Still supported for backward compatibility (see below)

Usage Examples

Example 1: Interactive First-Time Build

./build.sh

Output:

Enter directory for repo files [ENTER for default: /home/user/cwa-repo-download]: /tmp/cwa-build
Enter Docker Hub username [ENTER for default: user]: myusername
Select build type:
  [1] Development image
  [2] Production image
Enter 1 or 2: 1
Enter Version Number (e.g., "V2.0.1"): v3.1.5
Enter test version number (numeric only): 1
...

Example 2: Automated Production Build

Build a production image with all options specified:

./build.sh \
  -u mydockerhub \
  -v v3.1.5 \
  -d ~/cwa-builds/v3.1.5

Creates: mydockerhub/calibre-web-automated:v3.1.5

Example 3: Local Development Build

Test your uncommitted changes:

cd /path/to/your-cwa-fork
./build.sh -l -u myusername -v v3.2.0-dev -r 5
  • No git clone performed
  • Uses your current directory
  • Automatically sets build type to "dev"
  • Creates: myusername/calibre-web-automated:dev-5

Example 4: Build from Custom Fork/Branch

./build.sh \
  -u myusername \
  -v v3.1.5-custom \
  -d /tmp/custom-build \
  -c https://github.com/myusername/calibre-web-automated.git

Clone from your fork and build a custom version.

Example 5: CI/CD Pipeline

Fully automated build for continuous integration:

#!/bin/bash
BUILD_NUMBER=${GITHUB_RUN_NUMBER:-1}

./build.sh \
  -u "${DOCKER_USERNAME}" \
  -v "v3.2.0-ci" \
  -r "${BUILD_NUMBER}" \
  -d /tmp/ci-build \
  -c "${GITHUB_REPOSITORY_URL}"

Example 6: Quick Dev Build with Defaults

Provide only the essentials, accept defaults for the rest:

./build.sh -l -v v3.2.0-test -r 1

The script will prompt for Docker Hub username if not provided.

Build Modes

Development Mode

Characteristics:

  • Image tagged as username/calibre-web-automated:dev-<testnum>
  • Version string includes test number: v3.1.5-TEST-1
  • Intended for testing and iteration
  • Can create multiple dev builds with different test numbers

When to use:

  • Testing new features
  • Debugging issues
  • Pre-release validation

Example:

./build.sh -l -u myuser -v v3.2.0 -r 3
# Creates: myuser/calibre-web-automated:dev-3
# Version: v3.2.0-TEST-3

Production Mode

Characteristics:

  • Image tagged as username/calibre-web-automated:<version>
  • Clean version string: v3.1.5
  • Intended for deployment and distribution

When to use:

  • Official releases
  • Stable deployments
  • Distribution to end users

Example:

./build.sh -u myuser -v v3.1.5 -d ~/builds
# Creates: myuser/calibre-web-automated:v3.1.5
# Version: v3.1.5

Environment Variables

For backward compatibility, the script still supports environment variables:

REPO_DIR

Directory where the repository will be cloned.

export REPO_DIR="$HOME/cwa-builds"
./build.sh

The script will confirm the location with you. To skip confirmation, use the -d flag instead.

DH_USER

Docker Hub username for tagging the image.

export DH_USER="mydockerusername"
./build.sh

The script will confirm the username with you. To skip confirmation, use the -u flag instead.

REPO_URL

Git URL to clone from (default: https://github.com/crocodilestick/calibre-web-automated.git)

export REPO_URL="https://github.com/myusername/calibre-web-automated.git"
./build.sh

Note: CLI flags (-d, -u, -c) take precedence over environment variables.

Troubleshooting

Error: "Missing dependency: docker"

Solution: Install Docker and ensure it's running:

# Check if Docker is installed
docker --version

# Start Docker daemon (Linux)
sudo systemctl start docker

# Add your user to docker group (Linux)
sudo usermod -aG docker $USER
# Then log out and back in

Error: "Docker daemon not reachable"

Solution: Ensure Docker is running and you have permissions:

# Check Docker status
docker info

# Start Docker if needed
sudo systemctl start docker

Error: "Failed to change to directory"

Cause: The specified directory doesn't exist or is not accessible.

Solution:

  • Check the path is correct
  • Ensure you have permissions
  • For local builds (-l), run the script from within the repository

Build Fails with "No such file or directory"

Cause: When using -l flag, you're not in the repository directory.

Solution:

# Make sure you're in the repository
cd /path/to/calibre-web-automated
./build.sh -l -u myuser -v v3.2.0 -r 1

Images Not Appearing in Docker

Check built images:

docker images | grep calibre-web-automated

If the build completed successfully, the image should be listed.

"Permission denied" when running build.sh

Solution: Make the script executable:

chmod +x build.sh
./build.sh

Advanced Usage

Using with docker-compose.yml.dev

After building a custom image, update your docker-compose.yml.dev:

services:
  calibre-web-automated:
    image: myusername/calibre-web-automated:dev-1  # Your custom image
    volumes:
      # Mount your local code for live-reload
      - ./cps:/app/calibre-web-automated/cps
      - ./scripts:/app/calibre-web-automated/scripts
    # ... rest of config

Start the service:

docker compose -f docker-compose.yml.dev up -d

See docker-compose.yml.dev for live-reload configuration details.

Pushing to Docker Hub

After building, push your image:

# Log in to Docker Hub
docker login

# Push the image
docker push myusername/calibre-web-automated:dev-1

Building Multiple Versions

Create multiple test versions quickly:

# Build multiple dev versions
for i in {1..3}; do
  ./build.sh -l -u myuser -v v3.2.0 -r $i
done

# Results:
# myuser/calibre-web-automated:dev-1
# myuser/calibre-web-automated:dev-2
# myuser/calibre-web-automated:dev-3

Related Documentation

Contributing

If you find issues with the build script or have suggestions for improvements:

  1. Join the Discord to discuss
  2. Open an issue
  3. Submit a pull request

Happy Building! 🐳🔨

Add a custom footer
Add a custom sidebar

Clone this wiki locally