🐧 Docker 101 - Streamlit Penguins Demo

A Streamlit application showcasing the Palmer Penguins dataset, containerized with Docker and deployable to Google Cloud Run.

📋 Table of Contents

• Prerequisites
• Local Setup
• Local Docker Development
• Deployment to Google Cloud Run

---

🔧 Prerequisites

• Git - Version control
• pyenv and pyenv-virtualenv - Python version management
• Docker - Container runtime
• direnv - Environment variable management (optional but recommended)
• gcloud CLI - Google Cloud SDK (for deployment)

---

🚀 Local Setup

1. Clone the Repository

git clone https://github.com/vivadata/docker-101.git
cd docker-101

2. Setup Python Environment with pyenv-virtualenv

# Install Python 3.11.8 if not already installed
pyenv install 3.11.8

# Create a virtual environment named 'pingouins'
pyenv virtualenv 3.11.8 pingouins

# Set the local Python version for this project
pyenv local pingouins

The .python-version file will automatically activate the pingouins environment when you enter the directory.

3. Install Dependencies

pip install --upgrade pip
pip install -r requirements.txt

4. Test the Application Locally

streamlit run app.py

The application will open automatically in your browser at http://localhost:8501. You can stop it in your terminal with CTRL+C.

---

🐳 Local Docker Development

1. Setup Environment Variables

# Rename the template file
cp .env.copy .env

# Create .envrc file for direnv
echo 'dotenv' > .envrc

# Allow direnv to load the environment variables
direnv allow

2. Configure Environment Variables

Edit the .env file and replace the placeholder values:

# .env
LOCATION=europe-west1                    # Your GCP region
PROJECT_ID=your-project-id               # Your GCP project ID
REPOSITORY=your-artifact-registry        # Your Artifact Registry name
IMAGE=little-pengouins                   # Your image name
PORT=8080                                # Application port

3. Build and Run with Docker

Using the Makefile:

# Build the Docker image
make build

# Build and run the container
make run

Or using Docker commands directly:

# Build
docker build -t little-pengouins .

# Run
docker run -p 8080:8080 -e PORT=8080 little-pengouins

Access the application at http://localhost:8080.

---

☁️ Deployment to Google Cloud Run

1. Prerequisites

Ensure you have:

• A Google Cloud Platform account
• The gcloud CLI installed and configured
• A GCP project created

# Login to GCP
gcloud auth login

# Set your project
gcloud config set project YOUR_PROJECT_ID

2. Create Artifact Registry

# Set variables (or source from .env)
export LOCATION="europe-west1"
export PROJECT_ID="your-project-id"
export REPOSITORY="asod-public-images"

# Create the repository
gcloud artifacts repositories create ${REPOSITORY} \
    --repository-format=docker \
    --location=${LOCATION} \
    --description="Docker repository for Streamlit apps"

# Configure Docker authentication
gcloud auth configure-docker ${LOCATION}-docker.pkg.dev

3. Build for GCP

Choose the appropriate build command based on your machine:

For Linux/Cloud Shell:

make build_gcp

For Mac (M1/M2/M3):

make build_gcp_mac

This builds the image with the correct platform for Cloud Run.

4. Push to Artifact Registry

make push_gcp

Or manually:

docker push ${LOCATION}-docker.pkg.dev/${PROJECT_ID}/${REPOSITORY}/${IMAGE}

5. Deploy to Cloud Run

gcloud run deploy little-pengouins \
    --image=${LOCATION}-docker.pkg.dev/${PROJECT_ID}/${REPOSITORY}/${IMAGE} \
    --platform=managed \
    --region=${LOCATION} \
    --allow-unauthenticated \
    --port=8080

After deployment, Cloud Run will provide a URL where your application is accessible.

---

📦 Project Structure

docker-101/
├── app.py              # Streamlit application
├── requirements.txt    # Python dependencies
├── Dockerfile         # Container definition
├── Makefile          # Build and deploy commands
├── .env.copy         # Environment variables template
├── .envrc            # direnv configuration
├── .python-version   # pyenv virtual environment
├── .gitignore        # Git ignore rules
└── README.md         # This file

---

🛠️ Makefile Commands

Command	Description
make hello	Test command
make build	Build Docker image locally
make run	Build and run container locally
make build_gcp	Build image for GCP (Linux/Cloud Shell)
make build_gcp_mac	Build image for GCP (Mac M1/M2/M3)
make push_gcp	Build and push image to Artifact Registry

---

🐛 Troubleshooting

Port Already in Use

# Find and kill the process using port 8080
lsof -ti:8080 | xargs kill -9

Docker Permission Issues

# Add your user to the docker group (Linux)
sudo usermod -aG docker $USER

direnv Not Loading

# Ensure direnv is hooked to your shell
# Add to ~/.zshrc or ~/.bashrc:
eval "$(direnv hook zsh)"   # for zsh

---

📚 Resources

• Streamlit Documentation
• Docker Documentation
• Google Cloud Run Documentation
• Palmer Penguins Dataset

---

📝 License

This project is for educational purposes.

---

Happy Coding! 🐧