Search posts...

Docker Development Environment Setup

Docker Development Environment Setup

This guide will help you set up a Docker-based development environment for the Kelomai blog using Docker Desktop.

Prerequisites

Quick Start

  1. Start the development server: 
    docker-compose up
  2. Access your blog:
    • Open your browser to http://localhost:4000
    • The site will auto-reload when you make changes (LiveReload enabled)
  3. Stop the server:
    • Press Ctrl+C in the terminal
    • Or run: docker-compose down

Option 2: Using VS Code Dev Containers

  1. Open in VS Code:
    • Open this folder in VS Code
    • You should see a prompt: “Reopen in Container”
    • Click “Reopen in Container” (or use Command Palette: “Dev Containers: Reopen in Container”)
  2. Wait for the container to build:
    • First time will take a few minutes to build the image and install dependencies
    • Subsequent opens will be much faster
  3. Start Jekyll:
    • The dev container automatically runs bundle install
    • Open a terminal in VS Code and run: 
      bundle exec jekyll serve --host 0.0.0.0 --livereload
    • Or simply run: ./build.sh
  4. Access your blog:
    • VS Code will automatically forward port 4000
    • Click the notification or go to http://localhost:4000

Common Commands

Rebuild the Docker image:

docker-compose build --no-cache

Run in detached mode (background):

docker-compose up -d

View logs:

docker-compose logs -f

Stop and remove containers:

docker-compose down

Execute commands in the running container:

docker-compose exec jekyll bash

Install new gems:

# If you add gems to Gemfile, rebuild:
docker-compose down
docker-compose build
docker-compose up

Working with Your Blog

Creating a new post:

  1. Create a new file in _posts/ directory with the format: YYYY-MM-DD-title.md
  2. Add front matter and content
  3. Save the file
  4. Your browser will automatically refresh with the new post

Editing existing posts:

  1. Open any file in _posts/
  2. Make your changes
  3. Save the file
  4. Changes will appear immediately in your browser

Troubleshooting

Port 4000 is already in use:

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

# Or change the port in docker-compose.yml:
# ports:
#   - "4001:4000"

Container won’t start:

# Clean everything and rebuild
docker-compose down -v
docker-compose build --no-cache
docker-compose up

Changes not appearing:

  • Ensure the container is running: docker-compose ps
  • Check the logs: docker-compose logs -f
  • Try a hard refresh in your browser: Cmd+Shift+R (Mac) or Ctrl+Shift+R (Windows/Linux)

Permission issues:

# The container runs as root to avoid permission issues on macOS
# If you encounter issues, try:
docker-compose down
docker-compose up

What’s Included

  • Ruby 3.2: Latest stable Ruby version
  • Jekyll 4.4.1: Latest Jekyll with all your plugins
  • Bundler 2.6.6: For dependency management
  • LiveReload: Automatic browser refresh on file changes
  • Volume caching: Faster gem installation with persistent bundle cache

Development Workflow

  1. Start Docker Desktop
  2. Run docker-compose up
  3. Edit your blog posts in _posts/
  4. View changes instantly at http://localhost:4000
  5. When done, press Ctrl+C to stop

Benefits of This Setup

  • No Ruby installation needed on your Mac
  • Consistent environment across different machines
  • Isolated dependencies won’t conflict with other projects
  • Easy cleanup - just remove the containers
  • Fast setup for new team members or machines
  • Works on macOS, Windows, and Linux

Next Steps

  • Check Jekyll documentation for more features
  • Explore the _config.yml for site configuration
  • Review existing posts in _posts/ for examples
  • Customize the theme in css/ and _includes/