From 4fbb8fe0423c994c60c4b576b07f3e1390cfbb45 Mon Sep 17 00:00:00 2001 From: Mo King Date: Tue, 2 Sep 2025 09:36:33 -0400 Subject: [PATCH 1/2] Rename pages, reorder TOC --- docs.json | 155 ++++++++---------- tutorials/introduction/containers.mdx | 4 +- .../introduction/containers/overview.mdx | 11 -- tutorials/introduction/overview.mdx | 12 +- tutorials/migrations/cog/overview.mdx | 4 +- tutorials/migrations/openai/overview.mdx | 4 +- 6 files changed, 86 insertions(+), 104 deletions(-) delete mode 100644 tutorials/introduction/containers/overview.mdx diff --git a/docs.json b/docs.json index 15aee603..7a995e3e 100644 --- a/docs.json +++ b/docs.json @@ -181,24 +181,7 @@ ] }, { - "group": "Integrations", - "pages": [ - "integrations/dstack", - "integrations/mods", - "integrations/skypilot" - ] - }, - { - "group": "Hosting", - "pages": [ - "hosting/overview", - "hosting/burn-testing", - "hosting/maintenance-and-reliability", - "hosting/partner-requirements" - ] - }, - { - "group": "References", + "group": "Reference", "pages": [ "references/faq", "references/glossary", @@ -206,6 +189,7 @@ "references/referrals", "references/gpu-types", "references/cpu-types", + "references/graphql-spec", { "group": "Troubleshooting", "pages": [ @@ -215,34 +199,54 @@ "references/troubleshooting/troubleshooting-502-errors", "references/troubleshooting/token-authentication-enabled", "references/faq/manage-cards" - ] }, - "references/video-resources", - "references/graphql-spec" - ] - } - ] - }, - - { - "tab": "Tutorials", - "groups": [ - { - "group": "Get started", - "pages": [ - "tutorials/introduction/overview", + { + "group": "Integrations", + "pages": [ + "integrations/dstack", + "integrations/mods", + "integrations/skypilot" + ] + }, + { + "group": "Migrations", + "pages": [ + "tutorials/migrations/cog/overview", + "tutorials/migrations/openai/overview" + ] + }, { "group": "Intro to containers", "pages": [ - "tutorials/introduction/containers/overview", "tutorials/introduction/containers", "tutorials/introduction/containers/create-dockerfiles", "tutorials/introduction/containers/persist-data", "tutorials/introduction/containers/docker-commands" ] + }, + { + "group": "Hosting", + "pages": [ + "hosting/overview", + "hosting/burn-testing", + "hosting/maintenance-and-reliability", + "hosting/partner-requirements" + ] } ] + } + ] + }, + + { + "tab": "Examples", + "groups": [ + { + "group": "Introduction", + "pages": [ + "tutorials/introduction/overview" + ] }, { "group": "Serverless", @@ -264,55 +268,6 @@ "tutorials/pods/build-docker-images", "tutorials/pods/fine-tune-llm-axolotl" ] - }, - { - "group": "Python SDK", - "pages": [ - { - "group": "Get started", - "pages": [ - "tutorials/sdks/python/get-started/introduction", - "tutorials/sdks/python/get-started/prerequisites", - "tutorials/sdks/python/get-started/hello-world", - "tutorials/sdks/python/get-started/running-locally" - ] - }, - { - "group": "Serverless handler", - "pages": [ - "tutorials/sdks/python/101/hello", - "tutorials/sdks/python/101/local-server-testing", - "tutorials/sdks/python/101/generator", - "tutorials/sdks/python/101/async", - "tutorials/sdks/python/101/error", - "tutorials/sdks/python/101/aggregate" - ] - }, - { - "group": "Handler examples", - "pages": [ - "tutorials/sdks/python/102/huggingface-models", - "tutorials/sdks/python/102/stable-diffusion-text-to-image" - ] - } - ] - }, - { - "group": "Migrations", - "pages": [ - { - "group": "Cog", - "pages": [ - "tutorials/migrations/cog/overview" - ] - }, - { - "group": "OpenAI", - "pages": [ - "tutorials/migrations/openai/overview" - ] - } - ] } ] }, @@ -350,7 +305,39 @@ "pages": [ "sdks/python/overview", "sdks/python/apis", - "sdks/python/endpoints" + "sdks/python/endpoints", + { + "group": "Tutorials", + "pages": [ + { + "group": "Get started", + "pages": [ + "tutorials/sdks/python/get-started/introduction", + "tutorials/sdks/python/get-started/prerequisites", + "tutorials/sdks/python/get-started/hello-world", + "tutorials/sdks/python/get-started/running-locally" + ] + }, + { + "group": "Serverless handler", + "pages": [ + "tutorials/sdks/python/101/hello", + "tutorials/sdks/python/101/local-server-testing", + "tutorials/sdks/python/101/generator", + "tutorials/sdks/python/101/async", + "tutorials/sdks/python/101/error", + "tutorials/sdks/python/101/aggregate" + ] + }, + { + "group": "Handler examples", + "pages": [ + "tutorials/sdks/python/102/huggingface-models", + "tutorials/sdks/python/102/stable-diffusion-text-to-image" + ] + } + ] + } ] }, { diff --git a/tutorials/introduction/containers.mdx b/tutorials/introduction/containers.mdx index c6177b6b..6f065978 100644 --- a/tutorials/introduction/containers.mdx +++ b/tutorials/introduction/containers.mdx @@ -1,5 +1,7 @@ --- -title: "Intro to containers" +title: "Overview" +sidebar_label: Overview +description: Learn about containers and how to use them with Runpod --- ## What are containers? diff --git a/tutorials/introduction/containers/overview.mdx b/tutorials/introduction/containers/overview.mdx deleted file mode 100644 index 56651543..00000000 --- a/tutorials/introduction/containers/overview.mdx +++ /dev/null @@ -1,11 +0,0 @@ ---- -title: "Overview" ---- - -This set of tutorials is meant to provide a deeper understanding of the tools that surround the Runpod platform. These tutorials help you understand how to use the Runpod platform to build and deploy your applications. - -While the documentation around the introduction section gives a holistic view and enough information to get started with Runpod, for more detailed information on the various of these tools or technologies, reach out to the source material. - -* If you are looking for an understanding of Containers and Docker, see [Container overview](/tutorials/introduction/containers). -* If you are looking to run your first Pod with Runpod, see [Run your first Fast Stable Diffusion with Jupyter Notebook](/tutorials/pods/run-your-first). -* For Serverless implementation, see [Run your first serverless endpoint with Stable Diffusion](/tutorials/serverless/run-your-first). diff --git a/tutorials/introduction/overview.mdx b/tutorials/introduction/overview.mdx index 12e4c4a0..dd7cea29 100644 --- a/tutorials/introduction/overview.mdx +++ b/tutorials/introduction/overview.mdx @@ -1,18 +1,18 @@ --- -title: "Featured tutorials" -sidebarTitle: "Featured tutorials" -description: "Learn how to build and deploy AI applications on Runpod with step-by-step guides." +title: "Featured examples" +sidebarTitle: "Featured examples" +description: "Step-by-step guides for building and deploying AI applications on Runpod." --- -This page includes our most recently tested and updated tutorials. Many of our old guides are out of date and include deprecated instructions—we're actively working on updating them. +This page includes our most recently tested and updated examples. Many of our old guides are out of date and include instructions that may no longer work. We're actively working on updating them. -This section includes tutorials that will help you build and deploy specialized AI applications on the Runpod platform, covering basic concepts and advanced implementations. +This section includes step-by-step guides for building and deploying example applications on the Runpod platform, covering basic concepts and advanced implementations. ## Get started -If you're new to Runpod, start with these foundational tutorials to understand the platform and deploy your first application: +If you're new to Runpod, start with these foundational examples to understand the platform and deploy your first application: diff --git a/tutorials/migrations/cog/overview.mdx b/tutorials/migrations/cog/overview.mdx index 802b5540..33495112 100644 --- a/tutorials/migrations/cog/overview.mdx +++ b/tutorials/migrations/cog/overview.mdx @@ -1,5 +1,7 @@ --- -title: "Overview" +title: "Cog" +sidebar_label: Cog +description: Migrate your Cog model to Runpod --- To get started with Runpod: diff --git a/tutorials/migrations/openai/overview.mdx b/tutorials/migrations/openai/overview.mdx index 360ddef6..152a99d3 100644 --- a/tutorials/migrations/openai/overview.mdx +++ b/tutorials/migrations/openai/overview.mdx @@ -1,5 +1,7 @@ --- -title: "Overview" +title: "OpenAI" +sidebar_label: OpenAI +description: Migrate your OpenAI model to Runpod --- To get started with Runpod: From 1925bb847e26cfaa9d69fcd757a7a917b8c977f2 Mon Sep 17 00:00:00 2001 From: Mo King Date: Tue, 2 Sep 2025 11:58:53 -0400 Subject: [PATCH 2/2] Add new container tutorials --- docs.json | 4 +- .../containers/build-custom-images.mdx | 598 ++++++++++++++++++ .../containers/docker-commands.mdx | 382 +++++++++++ .../containers/intro-to-docker.mdx | 354 +++++++++++ .../overview.mdx} | 5 + 5 files changed, 1342 insertions(+), 1 deletion(-) create mode 100644 tutorials/introduction/containers/build-custom-images.mdx create mode 100644 tutorials/introduction/containers/intro-to-docker.mdx rename tutorials/introduction/{containers.mdx => containers/overview.mdx} (99%) diff --git a/docs.json b/docs.json index 7a995e3e..98068fa2 100644 --- a/docs.json +++ b/docs.json @@ -219,7 +219,9 @@ { "group": "Intro to containers", "pages": [ - "tutorials/introduction/containers", + "tutorials/introduction/containers/overview", + "tutorials/introduction/containers/intro-to-docker", + "tutorials/introduction/containers/build-custom-images", "tutorials/introduction/containers/create-dockerfiles", "tutorials/introduction/containers/persist-data", "tutorials/introduction/containers/docker-commands" diff --git a/tutorials/introduction/containers/build-custom-images.mdx b/tutorials/introduction/containers/build-custom-images.mdx new file mode 100644 index 00000000..fe6bf66c --- /dev/null +++ b/tutorials/introduction/containers/build-custom-images.mdx @@ -0,0 +1,598 @@ +--- +title: "Build and deploy custom images" +sidebarTitle: "Build and deploy custom images" +description: "Create custom Docker images using Dockerfiles, build reusable containers with entrypoint scripts, and learn deployment best practices." +--- + +This tutorial teaches you how to create custom Docker images using Dockerfiles, implement entrypoint scripts for flexible container behavior, and follow best practices for building production-ready containers. You'll build complete example applications including Runpod-specific patterns like handler functions for Serverless workers and optimized environments for Pod deployments. + +Custom Docker images allow you to package your applications with specific configurations, dependencies, and runtime environments. This is essential for Runpod's BYOC (bring your own container) approach, where you create specialized containers for GPU workloads, AI model inference, and distributed training across Pods, Serverless workers, and Instant Clusters. + +## What you'll learn + +In this tutorial, you'll learn how to: + +- Write Dockerfiles to define custom image builds for Runpod deployment. +- Create handler functions and entrypoint scripts for Serverless workers. +- Build optimized Docker images with proper tagging and platform specifications. +- Optimize images for fast cold starts and minimal resource usage. +- Deploy images through Docker Hub and integrate with Runpod Hub templates. +- Follow best practices for production-ready containers on GPU infrastructure. +- Implement BYOC patterns for both persistent Pods and auto-scaling Serverless workflows. + +## Requirements + +Before starting this tutorial, you'll need: + +- Docker Desktop installed and running (see [Docker fundamentals](/tutorials/introduction/containers/intro-to-docker)). +- Basic understanding of containers and Docker commands. +- A text editor for creating files. +- A Docker Hub account for pushing images (free to create). +- Basic familiarity with shell scripting and Python (for handler functions). +- Understanding of Runpod's platform concepts from [Pods overview](/pods/overview) and [Serverless overview](/serverless/overview). + +## Step 1: Create your first Dockerfile + +A Dockerfile is a text file containing instructions for building a Docker image. Let's start by creating a simple custom image. + +### Set up your project directory + +Create a new directory for your project and navigate to it: + +```bash +mkdir my-custom-app +cd my-custom-app +``` + +### Write a basic Dockerfile + +Create a file named `Dockerfile` (no extension) with the following content: + +```dockerfile +FROM busybox +COPY entrypoint.sh / +RUN chmod +x /entrypoint.sh +ENTRYPOINT ["/entrypoint.sh"] +``` + +Let's understand each instruction: + +- `FROM busybox`: Specifies the base image to build upon. +- `COPY entrypoint.sh /`: Copies a file from your local directory into the image. +- `RUN chmod +x /entrypoint.sh`: Executes a command during the build process. +- `ENTRYPOINT ["/entrypoint.sh"]`: Defines the default command to run when the container starts. + +### Create an entrypoint script + +Create a file named `entrypoint.sh` with the following content: + +```bash +#!/bin/sh +echo "=== Custom Container Started ===" +echo "Current time: $(date)" +echo "Container hostname: $(hostname)" +echo "=== Container Ready ===" +``` + +This script will run every time a container is created from your image. + +### Build your first custom image + +Build the Docker image using the `docker build` command with Runpod's required platform specification: + +```bash +docker build --platform=linux/amd64 -t my-time-app:v1.0 . +``` + +Breaking down this command: + +- `docker build`: The command to build an image. +- `--platform=linux/amd64`: Required platform specification for Runpod compatibility. +- `-t my-time-app:v1.0`: Tags the image with a name and version. +- `.`: Specifies the build context (current directory). + +You should see output showing each build step being executed. + + +The `--platform=linux/amd64` flag is essential for Runpod deployment, ensuring your containers run correctly on Runpod's GPU infrastructure regardless of your local development machine's architecture. + + +### Test your custom image + +Run a container from your newly built image: + +```bash +docker run my-time-app:v1.0 +``` + +You should see output from your entrypoint script showing the current time and hostname. + +## Step 2: Build a more complex application + +Let's create a more realistic example that demonstrates common Dockerfile patterns and best practices. + +### Create a Python web application + +First, create a simple Python web application. Create a file named `app.py`: + +```python +#!/usr/bin/env python3 +import http.server +import socketserver +import os +from datetime import datetime + +class CustomHandler(http.server.SimpleHTTPRequestHandler): + def do_GET(self): + if self.path == '/': + self.send_response(200) + self.send_header('Content-type', 'text/html') + self.end_headers() + + html_content = f""" + + + + My Custom Container App + + + +
+

Welcome to My Custom Container!

+
+

Current Time: {datetime.now().strftime('%Y-%m-%d %H:%M:%S')}

+

Container ID: {os.environ.get('HOSTNAME', 'unknown')}

+

Python Version: {os.sys.version}

+

Environment: {os.environ.get('APP_ENV', 'development')}

+
+

This application is running inside a custom Docker container!

+
+ + + """ + + self.wfile.write(html_content.encode()) + else: + super().do_GET() + +if __name__ == "__main__": + PORT = int(os.environ.get('PORT', 8080)) + + with socketserver.TCPServer(("", PORT), CustomHandler) as httpd: + print(f"Server starting on port {PORT}") + print(f"Environment: {os.environ.get('APP_ENV', 'development')}") + httpd.serve_forever() +``` + +### Create an advanced Dockerfile + +Replace your existing Dockerfile with this more comprehensive version: + +```dockerfile +# Use Python 3.11 slim image as base +FROM python:3.11-slim + +# Set metadata labels +LABEL maintainer="your-email@example.com" +LABEL description="Custom Python web application" +LABEL version="1.0" + +# Set environment variables +ENV APP_ENV=production +ENV PORT=8080 +ENV PYTHONUNBUFFERED=1 + +# Create a non-root user for security +RUN groupadd -r appuser && useradd -r -g appuser appuser + +# Set working directory +WORKDIR /app + +# Copy application files +COPY app.py . +COPY entrypoint.sh . + +# Make entrypoint script executable +RUN chmod +x entrypoint.sh + +# Change ownership to non-root user +RUN chown -R appuser:appuser /app + +# Switch to non-root user +USER appuser + +# Expose the port the app runs on +EXPOSE 8080 + +# Use entrypoint script for flexible startup +ENTRYPOINT ["./entrypoint.sh"] + +# Default command (can be overridden) +CMD ["python3", "app.py"] +``` + +### Update the entrypoint script + +Update your `entrypoint.sh` file to be more flexible: + +```bash +#!/bin/bash +set -e + +echo "=== Starting Custom Python Application ===" +echo "Environment: $APP_ENV" +echo "Port: $PORT" +echo "Time: $(date)" + +# Allow for custom initialization +if [ -f "/app/init.sh" ]; then + echo "Running custom initialization..." + source /app/init.sh +fi + +# Execute the main command +echo "Starting application..." +exec "$@" +``` + +This entrypoint script: + +- Sets error handling with `set -e`. +- Displays startup information. +- Allows for optional custom initialization. +- Uses `exec "$@"` to run the command passed to the container. + +## Step 3: Build and test the advanced image + +Now let's build and test our more sophisticated container. + +### Build the new image + +Build the updated image with a new tag: + +```bash +docker build -t my-python-app:v2.0 . +``` + +### Test the web application + +Run the container with port mapping to access the web application: + +```bash +docker run -p 8080:8080 my-python-app:v2.0 +``` + +Open your web browser and navigate to `http://localhost:8080` to see your custom web application running. + +To stop the container, press `Ctrl+C` in the terminal. + +### Test with custom environment variables + +Run the container with custom environment variables: + +```bash +docker run -p 8080:8080 -e APP_ENV=staging -e PORT=8080 my-python-app:v2.0 +``` + +Notice how the environment variable appears in the web interface. + +### Run with a custom command + +You can override the default command while still using the entrypoint: + +```bash +docker run my-python-app:v2.0 python3 -c "print('Custom command executed!')" +``` + +## Step 4: Optimize your Docker images + +Learn techniques to make your images smaller, faster, and more secure. + +### Use multi-stage builds + +Create a new file called `Dockerfile.optimized`: + +```dockerfile +# Build stage +FROM python:3.11-slim as builder + +WORKDIR /app + +# Install build dependencies if needed +# RUN apt-get update && apt-get install -y build-essential + +# Copy and install Python dependencies +# COPY requirements.txt . +# RUN pip install --user -r requirements.txt + +# Production stage +FROM python:3.11-slim + +# Install only runtime dependencies +RUN apt-get update && apt-get install -y --no-install-recommends \ + && rm -rf /var/lib/apt/lists/* + +# Create non-root user +RUN groupadd -r appuser && useradd -r -g appuser appuser + +# Set environment variables +ENV APP_ENV=production +ENV PORT=8080 +ENV PYTHONUNBUFFERED=1 + +WORKDIR /app + +# Copy application files +COPY --chown=appuser:appuser app.py entrypoint.sh ./ + +# Make entrypoint executable +RUN chmod +x entrypoint.sh + +# Switch to non-root user +USER appuser + +EXPOSE 8080 + +ENTRYPOINT ["./entrypoint.sh"] +CMD ["python3", "app.py"] +``` + +### Build the optimized image + +```bash +docker build -f Dockerfile.optimized -t my-python-app:optimized . +``` + +### Compare image sizes + +Check the sizes of your different images: + +```bash +docker images | grep my-python-app +``` + +You'll see the different versions and their sizes. + +## Step 5: Push your image to Docker Hub + +Share your custom image by pushing it to Docker Hub. + +### Log in to Docker Hub + +```bash +docker login +``` + +Enter your Docker Hub username and password when prompted. + +### Tag your image for Docker Hub + +Tag your image with your Docker Hub username: + +```bash +docker tag my-python-app:v2.0 yourusername/my-python-app:v2.0 +docker tag my-python-app:v2.0 yourusername/my-python-app:latest +``` + +Replace `yourusername` with your actual Docker Hub username. + +### Push the image + +Push your image to Docker Hub: + +```bash +docker push yourusername/my-python-app:v2.0 +docker push yourusername/my-python-app:latest +``` + +### Test pulling and running from Docker Hub + +Remove your local image and pull it from Docker Hub to verify the upload: + +```bash +docker rmi yourusername/my-python-app:v2.0 +docker run -p 8080:8080 yourusername/my-python-app:v2.0 +``` + +## Step 6: Best practices for production images + +Follow these guidelines when building images for production deployment. + +### Security best practices + +1. **Use official base images** from trusted sources. +2. **Run as non-root user** whenever possible. +3. **Keep images updated** with security patches. +4. **Minimize attack surface** by installing only necessary packages. + +### Performance optimization + +1. **Use .dockerignore** to exclude unnecessary files: + +Create a `.dockerignore` file: + +``` +.git +.gitignore +README.md +Dockerfile* +.dockerignore +node_modules +*.log +``` + +2. **Layer caching**: Order Dockerfile instructions from least to most frequently changing. + +3. **Multi-stage builds**: Separate build and runtime environments. + +### Image tagging strategy + +Use semantic versioning and meaningful tags: + +```bash +# Version tags +docker tag myapp:latest myapp:1.0.0 +docker tag myapp:latest myapp:1.0 +docker tag myapp:latest myapp:1 + +# Environment tags +docker tag myapp:1.0.0 myapp:1.0.0-production +docker tag myapp:1.0.0 myapp:1.0.0-staging +``` + +### Documentation and metadata + +Include helpful metadata in your Dockerfile: + +```dockerfile +LABEL org.opencontainers.image.title="My Python App" +LABEL org.opencontainers.image.description="A custom Python web application" +LABEL org.opencontainers.image.version="2.0.0" +LABEL org.opencontainers.image.authors="your-email@example.com" +LABEL org.opencontainers.image.source="https://github.com/yourusername/my-python-app" +``` + +## Step 7: Build RunPod Serverless containers + +Learn how to create containers specifically designed for RunPod Serverless workers with handler functions and optimized startup patterns. + +### Create a Serverless handler function + +Create a new directory for your Serverless project: + +```bash +mkdir runpod-serverless-example +cd runpod-serverless-example +``` + +Create a handler function file named `rp_handler.py`: + +```python +import runpod +import time +import os + +def handler(event): + """ + RunPod Serverless handler function + Processes input and returns results for auto-scaling workloads + """ + # Extract input from the event + user_input = event.get("input", {}) + message = user_input.get("message", "Hello from RunPod!") + + # Simulate some processing work + time.sleep(2) + + # Return response in expected format + return { + "message": f"Processed: {message}", + "timestamp": time.time(), + "worker_id": os.environ.get("RUNPOD_POD_ID", "unknown") + } + +# Start the RunPod serverless handler +if __name__ == "__main__": + runpod.serverless.start({"handler": handler}) +``` + +### Create the Serverless Dockerfile + +Create a `Dockerfile` optimized for Serverless workers: + +```dockerfile +# Use Python base image optimized for fast startup +FROM python:3.11-slim + +# Set working directory +WORKDIR /app + +# Install system dependencies (minimal for faster builds) +RUN apt-get update && apt-get install -y \ + --no-install-recommends \ + curl \ + && rm -rf /var/lib/apt/lists/* + +# Copy requirements first for better layer caching +COPY requirements.txt . + +# Install Python dependencies +RUN pip install --no-cache-dir -r requirements.txt + +# Copy application code +COPY rp_handler.py . + +# Set environment variables for optimization +ENV PYTHONUNBUFFERED=1 +ENV PYTHONDONTWRITEBYTECODE=1 + +# Expose the port (optional, as RunPod handles networking) +EXPOSE 8000 + +# Run the handler +CMD ["python", "rp_handler.py"] +``` + +Create a `requirements.txt` file: + +```text +runpod>=1.6.0 +``` + +### Build and test the Serverless container + +Build your Serverless container: + +```bash +docker build --platform=linux/amd64 -t my-serverless-worker:latest . +``` + +Test locally by running the container: + +```bash +docker run -p 8000:8000 my-serverless-worker:latest +``` + +### Deploy to RunPod Hub + +To share your container template on [RunPod Hub](/hub/overview): + +1. **Tag for Docker Hub**: +```bash +docker tag my-serverless-worker:latest yourusername/my-serverless-worker:latest +``` + +2. **Push to Docker Hub**: +```bash +docker push yourusername/my-serverless-worker:latest +``` + +3. **Create Hub template**: Visit [RunPod Hub](/hub/publishing-guide) to publish your container as a reusable template. + +### Optimization tips for Serverless workers + +For optimal performance in RunPod Serverless environments: + +- **Minimize image size**: Use slim base images and multi-stage builds. +- **Cache dependencies**: Install packages in separate layers for better caching. +- **Implement cleanup**: Use proper resource cleanup to prevent memory leaks. +- **Handle cold starts**: Minimize initialization time in your handler function. +- **Use environment variables**: Configure behavior through ENV vars for flexibility. + +Congratulations! You've successfully learned how to build custom Docker images, implement flexible entrypoint scripts, follow production best practices, and create specialized containers for RunPod Serverless workers. Your images are now ready for deployment across RunPod's platform. + +## Next steps with RunPod + +Now that you can build custom images optimized for RunPod, explore these deployment options: + +- Learn about [data persistence and volumes](/tutorials/introduction/containers/data-persistence) for managing data across container lifecycles. +- Deploy your containers on [RunPod Pods](/pods/overview) for persistent GPU workloads and interactive development. +- Create [Serverless workers](/serverless/overview) for auto-scaling AI inference and batch processing. +- Explore [RunPod Hub](/hub/overview) to publish and discover GPU-optimized container templates. +- Learn about [network volumes](/pods/storage/create-network-volumes) for persistent storage across deployments. + +You can also experiment with different base images optimized for AI/ML workloads, such as `pytorch/pytorch`, `tensorflow/tensorflow`, or specialized CUDA images from the `nvidia/cuda` repository. \ No newline at end of file diff --git a/tutorials/introduction/containers/docker-commands.mdx b/tutorials/introduction/containers/docker-commands.mdx index 3ef6c561..1fb21bdd 100644 --- a/tutorials/introduction/containers/docker-commands.mdx +++ b/tutorials/introduction/containers/docker-commands.mdx @@ -85,3 +85,385 @@ docker run --network= # Connect container docker exec docker exec mycontainer ls -l /etc # List files in container ``` + + + +{/* NEW VERSION: */} + +--- +title: "Docker commands reference" +sidebarTitle: "Docker commands reference" +description: "Quick reference guide for essential Docker commands used in container development and deployment workflows." +--- + +This reference guide provides essential Docker commands for container development, image management, and deployment workflows, with specific emphasis on RunPod BYOC (Bring Your Own Container) requirements. Use this as a quick lookup when working with Docker containers locally or preparing optimized deployments for RunPod Pods, Serverless Workers, and Instant Clusters. + +## Authentication and registry operations + +### Log in to Docker registries + +```bash +# Log in to Docker Hub (default registry) +docker login + +# Log in with specific username +docker login -u myusername + +# Log in to a private registry +docker login myregistry.com +``` + +## Image management + +### Building images + +```bash +# Build image from Dockerfile in current directory +docker build -t myapp:latest . + +# Build for RunPod deployment (required platform specification) +docker build --platform=linux/amd64 -t myapp:latest . + +# Build RunPod Serverless worker with handler +docker build --platform=linux/amd64 -t myuser/my-worker:latest . + +# Build with custom Dockerfile for specific RunPod use case +docker build --platform=linux/amd64 -f Dockerfile.runpod -t myapp:runpod . +``` +# Build with build arguments for RunPod optimization +docker build --platform=linux/amd64 --build-arg CUDA_VERSION=11.8 -t myapp:cuda . + +# Multi-stage build for smaller RunPod images +docker build --platform=linux/amd64 --target production -t myapp:optimized . +``` + + +Always use `--platform=linux/amd64` when building images for RunPod deployment to ensure compatibility with RunPod's GPU infrastructure. + + +### Image operations + +```bash +# List local images +docker images + +# Pull RunPod-optimized base images +docker pull runpod/pytorch:2.1.0-py3.10-cuda11.8.0-devel-ubuntu22.04 +docker pull runpod/tensorflow:2.13.0-py3.10-cuda11.8.0-devel-ubuntu22.04 + +# Pull image from registry +docker pull nginx:latest + +# Push image for RunPod deployment +docker push myusername/my-runpod-worker:latest + +# Tag images for RunPod Hub deployment +docker tag myapp:latest myusername/runpod-myapp:v1.0 +docker tag myapp:latest myusername/runpod-myapp:latest + +# Remove local image +docker rmi myapp:latest + +# Remove unused images to free space +docker image prune + +# Clean up build cache (useful for RunPod image optimization) +docker builder prune +``` + + +When pushing to Docker Hub for RunPod deployment, use descriptive tags that indicate RunPod compatibility and version information. + + +## Container lifecycle + +### Running containers + +```bash +# Run container from image +docker run nginx + +# Run RunPod Serverless worker locally for testing +docker run -p 8000:8000 myuser/my-worker:latest + +# Run with RunPod-style environment variables +docker run -e RUNPOD_POD_ID=local-test -e MODEL_PATH=/workspace/models myapp + +# Run with volume mount simulating RunPod network volumes +docker run -v ./workspace:/workspace myapp + +# Run interactively for debugging RunPod containers +docker run -it --platform=linux/amd64 myapp bash + +# Test RunPod handler function locally +docker run --rm -p 8000:8000 -e RUNPOD_DEBUG=1 myuser/my-worker:latest + +# Run container with GPU access (if available locally) +docker run --gpus all myuser/my-cuda-app:latest +``` +# Run with resource limits similar to RunPod constraints +docker run --memory=8g --cpus=2 myapp +``` + + +Use environment variables and volume mounts during local testing to simulate RunPod deployment conditions. + + +### Container management + +```bash +# List running containers +docker ps + +# List all containers (including stopped) +docker ps -a + +# Stop running container +docker stop container_name + +# Start stopped container +docker start container_name + +# Restart container +docker restart container_name + +# Remove container +docker rm container_name + +# Remove all stopped containers +docker container prune +``` + +### Container inspection and debugging + +```bash +# View container logs +docker logs container_name + +# Follow log output in real-time +docker logs -f container_name + +# Execute command in running container +docker exec container_name ls -la + +# Open interactive shell in running container +docker exec -it container_name bash + +# Inspect container details +docker inspect container_name + +# View container resource usage +docker stats container_name +``` + +## Volume management + +### Volume operations + +```bash +# Create named volume +docker volume create myvolume + +# List volumes +docker volume ls + +# Inspect volume details +docker volume inspect myvolume + +# Remove volume +docker volume rm myvolume + +# Remove unused volumes +docker volume prune + +# Run container with named volume +docker run -v myvolume:/app/data myapp + +# Run container with bind mount +docker run -v /host/path:/container/path myapp +``` + +## Network management + +### Network operations + +```bash +# List networks +docker network ls + +# Create custom network +docker network create mynetwork + +# Run container on specific network +docker run --network=mynetwork myapp + +# Connect running container to network +docker network connect mynetwork container_name + +# Disconnect container from network +docker network disconnect mynetwork container_name + +# Remove network +docker network rm mynetwork +``` + +## System management + +### System information and cleanup + +```bash +# Show Docker system information +docker info + +# Show disk usage +docker system df + +# Show detailed disk usage +docker system df -v + +# Remove unused containers, networks, images, and build cache +docker system prune + +# Remove everything including unused volumes +docker system prune -a --volumes +``` + +### Docker Compose (if available) + +```bash +# Start services defined in docker-compose.yml +docker-compose up + +# Start services in background +docker-compose up -d + +# Stop services +docker-compose down + +# View service logs +docker-compose logs + +# Build services +docker-compose build +``` + +## Runpod-specific considerations + +When preparing containers for deployment on Runpod, keep these points in mind: + +### Platform compatibility + +Always build images for the correct platform: + +```bash +docker build --platform=linux/amd64 -t myapp:latest . +``` + +### Storage integration + +When using Runpod, replace local volumes with [network volumes](/pods/storage/create-network-volumes): + +```bash +# Local development +docker run -v mydata:/app/data myapp + +# On Runpod: Use network volumes through the console interface +``` + +### Port exposure + +Configure port exposure for Runpod's HTTP proxy: + +```bash +# Expose ports in Dockerfile +EXPOSE 8080 + +# Or when running locally for testing +docker run -p 8080:8080 myapp +``` + +### Environment variables + +Use environment variables for configuration: + +```bash +# Set environment variables +docker run -e API_KEY=your_key -e PORT=8080 myapp +``` + +## Common workflows + +### Development workflow + +```bash +# 1. Build image +docker build -t myapp:dev . + +# 2. Run for testing +docker run -p 8080:8080 -v $(pwd):/app myapp:dev + +# 3. Debug if needed +docker exec -it container_name bash + +# 4. Clean up +docker stop container_name && docker rm container_name +``` + +### Production deployment workflow + +```bash +# 1. Build production image +docker build --platform=linux/amd64 -t myapp:prod . + +# 2. Tag for registry +docker tag myapp:prod myregistry/myapp:1.0 + +# 3. Push to registry +docker push myregistry/myapp:1.0 + +# 4. Deploy on Runpod using the pushed image +``` + +### Debugging workflow + +```bash +# 1. Check if container is running +docker ps + +# 2. View logs +docker logs container_name + +# 3. Execute commands inside container +docker exec -it container_name bash + +# 4. Inspect container configuration +docker inspect container_name + +# 5. Check resource usage +docker stats container_name +``` + +## Tips and best practices + +### Image optimization + +- Use `.dockerignore` to exclude unnecessary files from build context. +- Use multi-stage builds to reduce final image size. +- Choose appropriate base images (prefer slim or alpine variants). +- Combine RUN commands to reduce layers. + +### Security + +- Run containers as non-root users when possible. +- Use official images from trusted sources. +- Keep base images updated with security patches. +- Avoid storing secrets in images. + +### Performance + +- Use volume mounts for frequently changing data. +- Leverage Docker's layer caching for faster builds. +- Use appropriate resource limits for containers. +- Monitor container resource usage regularly. + +This reference covers the most commonly used Docker commands for container development and deployment. For more detailed information about specific commands, use `docker COMMAND --help` or consult the [official Docker documentation](https://docs.docker.com/). \ No newline at end of file diff --git a/tutorials/introduction/containers/intro-to-docker.mdx b/tutorials/introduction/containers/intro-to-docker.mdx new file mode 100644 index 00000000..6d67f0a7 --- /dev/null +++ b/tutorials/introduction/containers/intro-to-docker.mdx @@ -0,0 +1,354 @@ +--- +title: "Docker fundamentals" +sidebarTitle: "Docker fundamentals" +description: "Learn the basics of Docker, including containers, images, and how to run your first containerized application." +--- + +This tutorial introduces you to Docker containerization fundamentals and walks you through installing Docker Desktop and running your first containers. You'll learn the core concepts that make containers essential for modern application deployment and cloud computing, with specific focus on how they enable Runpod's BYOC (bring your own container) workflows. + +Containers are isolated environments that package applications with all their dependencies, making them portable and consistent across different computing environments. This approach is fundamental to Runpod's infrastructure, where containers enable fast deployment across Pods, Serverless Workers, and Instant Clusters. Understanding containers is essential for leveraging Runpod's BYOC capabilities for both persistent infrastructure and auto-scaling workloads. + +## What you'll learn + +In this tutorial, you'll learn how to: + +- Understand what containers and Docker images are and why they're essential for Runpod deployments. +- Install Docker Desktop with all necessary tools for local development. +- Run your first container commands and explore container basics. +- Use Docker Hub to access pre-built images and understand registry workflows. +- Understand how containers enable Runpod's BYOC workflows for both Pods and Serverless. +- Connect containerization concepts to Runpod's deployment patterns and optimization strategies. + +## Requirements + +Before starting this tutorial, you'll need: + +- A computer running Windows, macOS, or Linux. +- Administrator/root access to install Docker Desktop. +- Basic familiarity with command-line interfaces. +- An internet connection to download Docker and container images. + +## Step 1: Understand containers and images + +Before diving into hands-on work, let's establish the fundamental concepts you'll be working with. + +### What are containers? + +A container is an isolated environment for your code that includes everything needed to run an application: the code itself, runtime libraries, system tools, and settings. Containers have no knowledge of your host operating system or files - they run in their own isolated space. + +This isolation makes containers perfect for Runpod's BYOC (bring your own container) approach, where your custom environments run reliably across different GPU hardware and compute types. + +Key benefits of containers for Runpod deployments include: + +- **Consistency**: Applications run identically on your local machine and Runpod infrastructure. +- **Portability**: Move workloads seamlessly between Pods, Serverless Workers, and Instant Clusters. +- **Efficiency**: Fast startup times essential for Serverless cold starts and Pod initialization. +- **Isolation**: GPU workloads run independently without interference from other users. +- **Reproducibility**: Exact environment replication for AI/ML model training and inference. + +### What are Docker images? + +Docker images are read-only templates used to create containers. Think of an image as a blueprint that contains: + +- A base operating system (like Ubuntu or Alpine Linux optimized for GPU workloads). +- Your application code and dependencies (like Python packages for AI/ML models). +- Configuration files and environment settings. +- Instructions for how to run the application. + +Images are built using a process called "Docker build" which follows instructions in a text file called a Dockerfile. For Runpod deployments, images often contain specialized components like handler functions for Serverless Workers or JupyterLab environments for Pods. + +### What is Docker Hub? + +Docker Hub is a cloud-based registry where Docker images are stored and shared. It contains millions of pre-built images for popular applications, programming languages, and services. You can pull images from Docker Hub to run containers locally or push your own custom images to share with others. + +Runpod also provides the [Runpod Hub](/hub/overview), a curated registry of GPU-optimized container templates designed specifically for AI/ML workloads. These templates include pre-configured environments for popular frameworks like PyTorch, TensorFlow, and specialized inference engines, making it easier to deploy on Runpod's infrastructure. + +## Step 2: Install Docker Desktop + +Docker Desktop provides everything you need to work with containers, including the Docker engine, command-line tools, and a graphical interface. + +### Download and install Docker Desktop + +1. Visit the [official Docker website](https://docs.docker.com/get-docker/) and download Docker Desktop for your operating system. + +2. Run the installer and follow the setup wizard: + - On Windows: Enable WSL 2 integration if prompted. + - On macOS: Run the installer and accept the default options to add Docker to your Applications folder. + - On Linux: Follow the distribution-specific installation instructions. + +3. Start Docker Desktop after installation completes. + +4. Complete the initial setup process, including creating a Docker Hub account if you don't have one. + +### Verify your installation + +Open a terminal or command prompt and run the following command to verify Docker is installed correctly: + +```bash +docker version +``` + +You should see output similar to this: + +```bash +Client: + Version: 28.0.4 + API version: 1.48 + Go version: go1.23.7 + Git commit: b8034c0 + Built: Tue Mar 25 15:06:09 2025 + OS/Arch: darwin/arm64 + Context: desktop-linux +``` + +If you see the message: + +```bash +Cannot connect to the Docker daemon at unix:///Users/moking/.docker/run/docker.sock. Is the docker daemon running? +``` + +That means you need to start the Docker Desktop application. Start it and try running the command again. + +You should see output similar to this: + +```bash +Server: Docker Desktop 4.40.0 (187762) + Engine: + Version: 28.0.4 + API version: 1.48 (minimum version 1.24) + Go version: go1.23.7 + Git commit: 6430e49 + Built: Tue Mar 25 15:07:18 2025 + OS/Arch: linux/arm64 + Experimental: false + containerd: + Version: 1.7.26 + GitCommit: 753481ec61c7c8955a23d6ff7bc8e4daed455734 + runc: + Version: 1.2.5 + GitCommit: v1.2.5-0-g59923ef + docker-init: + Version: 0.19.0 + GitCommit: de40ad0 +``` + +If you see version information for both the client and server, Docker is installed and running correctly. + + +If you need help with any Docker command, use the `--help` flag to see documentation: + +```bash +docker --help +docker run --help +``` + + +## Step 3: Run your first container + +Now that Docker is installed, let's run your first container using a simple, lightweight image. + +### Run a basic container + +Execute this command in your local terminal to run your first container: + +```bash +docker run busybox echo "Hello from my first container!" +``` + +This command does several things: + +1. **Downloads the busybox image** (if not already present locally). +2. **Creates a new container** from the busybox image. +3. **Runs the echo command** inside the container. +4. **Displays the output** and exits. + +You should see output like: + +```bash +Hello from my first container! +``` + +### Understanding what happened + +Let's break down what occurred when you ran that command: + +- `docker run`: The command to create and start a new container. +- `busybox`: A lightweight Linux image with basic utilities. +- `echo "Hello from my first container!"`: The command executed inside the container. + +The busybox image is popular for learning because it's small (about 1MB) but includes essential Linux command-line tools. + +### Run an interactive container + +Try running a container interactively to explore its environment: + +```bash +docker run -it busybox sh +``` + +This opens a shell inside the container where you can run commands: + +- `-i`: Keep the container's standard input open. +- `-t`: Allocate a pseudo-terminal for interactive use. +- `sh`: Start a shell session. + +Inside the container, try these commands: + +```bash +# List files in the root directory +ls + +# Check the current date and time +date + +# Exit the container +exit +``` + +When you type `exit`, the container stops and you return to your host system. + +## Step 4: Explore the container lifecycle + +Understanding how containers start, run, and stop is crucial for effective container management. + +### Run a container with a specific task + +Let's run a container that performs a specific task and then exits: + +```bash +docker run busybox sh -c 'echo "The current time is: $(date)"' +``` + +This creates a container, runs the command, displays the output, and automatically removes the container when finished. + +### List running containers + +To see what containers are currently running: + +```bash +docker ps +``` + +Since our previous containers have already finished and exited, you'll likely see an empty list or just column headers. + +### List all containers (including stopped ones) + +To see all containers, including those that have stopped: + +```bash +docker ps -a +``` + +This shows all containers with their status, creation time, and other details. + +### Clean up stopped containers + +Remove stopped containers to keep your system clean: + +```bash +docker container prune +``` + +Confirm when prompted to remove all stopped containers. + +## Step 5: Working with Docker images + +Learn how to manage the images that serve as templates for your containers. + +### List downloaded images + +See what images you have locally: + +```bash +docker images +``` + +You should see the busybox image you downloaded earlier. + +### Pull a specific image + +Download an image without running it immediately: + +```bash +docker pull hello-world +``` + +This downloads the official "hello-world" image, which is designed specifically for testing Docker installations. + +### Run the hello-world container + +```bash +docker run hello-world +``` + +This container displays information about how Docker works and then exits. It's a great way to verify your Docker installation is working correctly. + +### Remove an image + +If you want to remove an image you no longer need: + +```bash +docker rmi hello-world +``` + + +If the command above fails, you can force removal of the image with the `-f` flag: + +```bash +docker rmi -f hello-world +``` + + +## Step 6: Understand Docker's architecture + +Now that you've run a few containers, let's understand how Docker's components work together. + +### Key components + +- **Docker Engine**: The core runtime that manages containers and images. +- **Docker CLI**: The command-line interface you've been using. +- **Docker Desktop**: The graphical application that includes the engine and CLI. +- **Docker Hub**: The cloud registry for sharing images. + +### Container lifecycle + +1. **Image creation**: Images are built from Dockerfiles or pulled from registries. +2. **Container creation**: Containers are created from images but not yet running. +3. **Container execution**: Containers run the specified command or application. +4. **Container termination**: Containers stop when their main process exits. +5. **Container removal**: Stopped containers can be deleted to free up space. + +### Why containers matter for cloud computing + +Containers provide several advantages for cloud platforms like Runpod: + +- **Fast startup times**: Critical for Serverless workers that need to minimize cold start latency. +- **Resource efficiency**: Optimal GPU utilization across multiple concurrent workloads. +- **Scalability**: Automatic scaling from zero to hundreds of instances based on demand. +- **Consistency**: AI/ML models behave identically in development and production environments. + +### Runpod's containerization approach + +Runpod's BYOC (bring your own container) approach enables three deployment patterns: + +- **[Pods](/pods/overview)**: Persistent GPU instances with custom container environments for development and training. +- **[Serverless workers](/serverless/overview)**: Auto-scaling container functions for AI inference and batch processing. +- **[Instant Clusters](/instant-clusters)**: Distributed container deployments for multi-GPU training workloads. + +Each approach leverages containers differently, but shares the same fundamental principles you'll learn in this tutorial series. + +## Next steps + +Now that you understand container basics, you're ready to explore more advanced topics: + +- Learn how to [build custom Docker images](/tutorials/introduction/containers/build-custom-images) with Dockerfiles, including Runpod-specific patterns like handler functions for Serverless. +- Discover [data persistence patterns](/tutorials/introduction/containers/data-persistence) for managing data across container lifecycles, including network volume integration. +- Reference [Docker commands](/tutorials/introduction/containers/docker-commands-reference) optimized for Runpod deployment workflows. + +## Next steps with Runpod + +Once you've mastered container fundamentals, explore how to deploy your containers on Runpod: + +- Deploy containers on [Pods](/pods/overview) for persistent GPU workloads and interactive development. +- Create [Serverless workers](/serverless/overview) for auto-scaling AI inference and batch processing. +- Browse [Runpod Hub](/hub/overview) for pre-optimized container templates and models. \ No newline at end of file diff --git a/tutorials/introduction/containers.mdx b/tutorials/introduction/containers/overview.mdx similarity index 99% rename from tutorials/introduction/containers.mdx rename to tutorials/introduction/containers/overview.mdx index 6f065978..66815b94 100644 --- a/tutorials/introduction/containers.mdx +++ b/tutorials/introduction/containers/overview.mdx @@ -4,6 +4,11 @@ sidebar_label: Overview description: Learn about containers and how to use them with Runpod --- + + + + + ## What are containers? > A container is an isolated environment for your code. This means that a container has no knowledge of your operating system, or your files. It runs on the environment provided to you by Docker Desktop. Containers have everything that your code needs in order to run, down to a base operating system.