Development Guide

🐳 Docker Development Setup

This guide will help you get your Jekyll site running locally using Docker.

Quick Start

Clone and navigate to the repository

git clone https://github.com/nielsweistra/nielsweistra.github.io.git
cd nielsweistra.github.io

Start the development server

Windows:

start-dev.bat

Linux/macOS:

chmod +x start-dev.sh
./start-dev.sh

Open your browser
- Navigate to http://localhost:4000
- The site will automatically reload when you make changes

Docker Commands Reference

# Build and start (with logs)
docker-compose up --build

# Start in background
docker-compose up -d

# Stop the containers
docker-compose down

# View logs
docker-compose logs -f

# Rebuild from scratch
docker-compose down
docker-compose up --build --force-recreate

Development Workflow

Make changes to your files (HTML, CSS, Markdown)
Save the files - changes are automatically detected
Browser refreshes automatically via LiveReload
No manual restart needed for most changes

Troubleshooting

Port Already in Use

If port 4000 is already in use:

# Find what's using port 4000
netstat -ano | findstr :4000

# Kill the process (Windows)
taskkill /PID <PID> /F

# Or use different ports in docker-compose.yml
ports:
  - "4001:4000"  # Change 4001 to any available port

Container Won’t Start

# Clean up and restart
docker-compose down
docker system prune -f
docker-compose up --build

Permission Issues (Linux/macOS)

# Fix ownership of generated files
sudo chown -R $USER:$USER _site .sass-cache .jekyll-cache

File Structure

├── Dockerfile              # Docker image configuration
├── docker-compose.yml      # Docker Compose services
├── .dockerignore           # Files to exclude from Docker build
├── start-dev.sh            # Development startup script (Linux/macOS)
├── start-dev.bat           # Development startup script (Windows)
└── DEVELOPMENT.md          # This file

Environment Variables

You can customize the Jekyll environment by editing docker-compose.yml:

environment:
  - JEKYLL_ENV=development    # development, production
  - BUNDLE_PATH=/usr/local/bundle

Performance Tips

Use volume caching - The Docker Compose file includes bundle caching
Exclude unnecessary files - Update .dockerignore if needed
Use polling - Force polling is enabled for better file change detection

Production Build

To build for production:

# Build production version
docker-compose exec jekyll bundle exec jekyll build --env=production

# Or build a production Docker image
docker build -t nielsweistra-site:production --build-arg JEKYLL_ENV=production .

🚀 Deployment

The site automatically deploys to GitHub Pages when you push to the main branch. No additional deployment steps are needed.

Manual GitHub Pages Deployment

If you need to trigger a manual deployment:

Go to your GitHub repository
Navigate to Actions tab
Find the Jekyll workflow
Click Run workflow button

📝 Content Updates

Adding Blog Posts

Create a new file in _posts/ with the format: YYYY-MM-DD-title.md

Add front matter:

---
layout: post
title: "Your Post Title"
date: 2025-09-28
categories: [devops, kubernetes]
tags: [docker, azure, ci-cd]
---

Write your content in Markdown
Save and the site will automatically update

Updating Skills Matrix

Edit the skills section in index.html:

Update skill names, experience years, and proficiency levels
Modify progress bar values (data-width attribute)
Add or remove skill categories as needed

Customizing Design

Colors: Update CSS custom properties in _layouts/default.html
Fonts: Modify the Google Fonts import in the <head> section
Layout: Adjust the grid and flexbox layouts in the CSS

🔍 Debugging

Jekyll Build Issues

# Check Jekyll version and dependencies
docker-compose exec jekyll bundle exec jekyll --version
docker-compose exec jekyll bundle list

# Verbose build output
docker-compose exec jekyll bundle exec jekyll build --verbose

Checking Logs

# Real-time logs
docker-compose logs -f jekyll

# Specific container logs
docker logs nielsweistra-github-io

Common Issues

Gemfile.lock conflicts: Delete Gemfile.lock and rebuild
Cache issues: Clear Jekyll cache: rm -rf .jekyll-cache _site .sass-cache
Live reload not working: Check that port 35729 is accessible

📞 Support

If you encounter issues:

Check this development guide
Review the Jekyll documentation
Check GitHub Pages documentation
Open an issue in the repository