Development Environment Setup¶

This guide provides step-by-step instructions for setting up a local development environment for the IT-Journey repository.

Prerequisites¶

Required Software¶

Tool	Minimum Version	Purpose
Git	2.30+	Version control
Ruby	3.2.3	Jekyll runtime
Bundler	2.4+	Dependency management
Python	3.11+	Automation scripts
Docker	20.10+ (optional)	Containerized development

Operating System Support¶

✅ macOS 11+ (Big Sur and later)
✅ Ubuntu 20.04+ / Debian 11+
✅ Windows 10+ with WSL2
✅ Other Linux distributions (with package manager adjustments)

Quick Start¶

Option 1: Automated Setup (Recommended)¶

# Clone the repository
git clone https://github.com/bamr87/it-journey.git
cd it-journey

# Run automated setup
./scripts/core/environment-setup.sh

# Start development server
bundle exec jekyll serve --config _config_dev.yml

Option 2: Docker Setup (Easiest)¶

# Clone the repository
git clone https://github.com/bamr87/it-journey.git
cd it-journey

# Start with Docker Compose
docker-compose up

# Access at http://localhost:4002

Option 3: Manual Setup¶

Follow the detailed instructions below for your operating system.

Detailed Setup Instructions¶

macOS Setup¶

1. Install Homebrew (if not installed)¶

/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"

2. Install Ruby with rbenv¶

# Install rbenv and ruby-build
brew install rbenv ruby-build

# Initialize rbenv
echo 'eval "$(rbenv init - zsh)"' >> ~/.zshrc
source ~/.zshrc

# Install Ruby 3.2.3
rbenv install 3.2.3
rbenv global 3.2.3

# Verify installation
ruby --version  # Should show 3.2.3

3. Install Bundler¶

gem install bundler
bundler --version  # Should show 2.4+

4. Install Jekyll and Dependencies¶

cd it-journey
bundle install

5. Install Python (for scripts)¶

# Python usually pre-installed on macOS
python3 --version  # Should show 3.11+

# If not, install via Homebrew
brew install python@3.11

# Install required packages
pip3 install requests pyyaml

6. Install Docker (Optional)¶

# Download Docker Desktop for Mac
# https://www.docker.com/products/docker-desktop

# Or via Homebrew
brew install --cask docker

Linux (Ubuntu/Debian) Setup¶

1. Update System¶

sudo apt update
sudo apt upgrade -y

2. Install Build Dependencies¶

sudo apt install -y \
    git \
    curl \
    build-essential \
    libssl-dev \
    libreadline-dev \
    zlib1g-dev \
    autoconf \
    bison \
    libyaml-dev \
    libffi-dev \
    libgdbm-dev \
    libncurses5-dev

3. Install rbenv and Ruby¶

# Clone rbenv
git clone https://github.com/rbenv/rbenv.git ~/.rbenv

# Add to PATH
echo 'export PATH="$HOME/.rbenv/bin:$PATH"' >> ~/.bashrc
echo 'eval "$(rbenv init -)"' >> ~/.bashrc
source ~/.bashrc

# Install ruby-build
git clone https://github.com/rbenv/ruby-build.git ~/.rbenv/plugins/ruby-build

# Install Ruby 3.2.3
rbenv install 3.2.3
rbenv global 3.2.3

# Verify
ruby --version

4. Install Bundler and Jekyll¶

gem install bundler

cd it-journey
bundle install

5. Install Python¶

sudo apt install -y python3.11 python3-pip
pip3 install requests pyyaml

6. Install Docker (Optional)¶

# Install Docker
curl -fsSL https://get.docker.com -o get-docker.sh
sudo sh get-docker.sh

# Add user to docker group
sudo usermod -aG docker $USER

# Install Docker Compose
sudo apt install -y docker-compose

# Log out and back in for group changes to take effect

Windows (WSL2) Setup¶

1. Install WSL2¶

# Run in PowerShell as Administrator
wsl --install

# Restart computer
# Set WSL2 as default
wsl --set-default-version 2

# Install Ubuntu
wsl --install -d Ubuntu-22.04

2. Open Ubuntu Terminal¶

# Update system
sudo apt update && sudo apt upgrade -y

3. Follow Linux Setup Instructions¶

Continue with the Linux (Ubuntu/Debian) setup instructions above.

4. Windows-Specific Configuration¶

# Configure Git line endings
git config --global core.autocrlf input

# Set default editor
git config --global core.editor "code --wait"  # If using VS Code

Repository Setup¶

1. Clone Repository¶

# HTTPS
git clone https://github.com/bamr87/it-journey.git

# SSH (if configured)
git clone git@github.com:bamr87/it-journey.git

cd it-journey

2. Install Dependencies¶

# Ruby gems
bundle install

# Python packages (for scripts)
pip3 install requests pyyaml

# Verify Jekyll
bundle exec jekyll --version

3. Configure Environment¶

# Copy example environment file (if exists)
cp .env.example .env

# Edit with your settings
nano .env

# Set Jekyll environment
export JEKYLL_ENV=development

4. Build and Serve¶

# Development server
bundle exec jekyll serve --config _config_dev.yml

# Or use shortcut if configured
make serve  # If Makefile exists

# Access at http://localhost:4002

Docker Development¶

Setup Docker Environment¶

1. Install Docker¶

Follow Docker installation instructions for your OS from docker.com.

2. Verify Installation¶

docker --version
docker-compose --version

3. Build and Run¶

# Build image (first time)
docker-compose build

# Start containers
docker-compose up

# Or in detached mode
docker-compose up -d

# View logs
docker-compose logs -f

# Stop containers
docker-compose down

Docker Commands¶

# Rebuild after Gemfile changes
docker-compose build --no-cache

# Access container shell
docker-compose exec jekyll bash

# Run commands in container
docker-compose exec jekyll bundle update

# Clean up
docker-compose down -v  # Removes volumes too

Docker Compose Configuration¶

File: docker-compose.yml

version: '3.8'
services:
  jekyll:
    build: .
    volumes:
      - .:/usr/src/app
      - bundle_cache:/usr/local/bundle
    ports:
      - "4002:4002"
    command: bundle exec jekyll serve --host 0.0.0.0 --config _config_dev.yml

volumes:
  bundle_cache:

IDE Setup¶

VS Code (Recommended)¶

1. Install Extensions¶

# Open VS Code
code it-journey

# Install recommended extensions (or click when prompted)
# See .vscode/extensions.json

Recommended Extensions: - Jekyll Syntax Support - Front Matter CMS - YAML - Markdown All in One - Code Spell Checker - Docker

2. Configure Settings¶

File: .vscode/settings.json

{
  "files.associations": {
    "*.html": "liquid"
  },
  "liquid.format.enable": true,
  "markdown.preview.breaks": true,
  "[markdown]": {
    "editor.wordWrap": "on",
    "editor.quickSuggestions": true
  }
}

3. Configure Tasks¶

The repo already ships a .vscode/tasks.json on the fleet convention (Serve, Stop, Build, Lint, Verify; see .vscode/README.md), so this step is only needed for a fresh, unrelated Jekyll project. A minimal one looks like:

File: .vscode/tasks.json

{
  "version": "2.0.0",
  "tasks": [
    {
      "label": "Serve Jekyll",
      "type": "shell",
      "command": "bundle exec jekyll serve --config _config_dev.yml",
      "group": {
        "kind": "build",
        "isDefault": true
      },
      "problemMatcher": []
    }
  ]
}

Other IDEs¶

RubyMine¶

Import as Ruby project
Configure Ruby SDK (3.2.3)
Enable Jekyll support

Sublime Text¶

Install Package Control
Install Jekyll packages
Configure build system

Environment Variables¶

Required Variables¶

# Add to ~/.bashrc or ~/.zshrc

# Jekyll environment
export JEKYLL_ENV=development

# Repository path
export IT_JOURNEY_HOME=~/path/to/it-journey

# Optional: OpenAI for AI features
export OPENAI_API_KEY=your-api-key-here

Loading Variables¶

# Reload shell configuration
source ~/.bashrc  # or ~/.zshrc

# Verify
echo $JEKYLL_ENV
echo $IT_JOURNEY_HOME

Common Development Tasks¶

Starting Development Server¶

# Standard
bundle exec jekyll serve --config _config_dev.yml

# With live reload
bundle exec jekyll serve --config _config_dev.yml --livereload

# Incremental builds (faster)
bundle exec jekyll serve --config _config_dev.yml --incremental

# With drafts
bundle exec jekyll serve --config _config_dev.yml --drafts

# Specific port
bundle exec jekyll serve --config _config_dev.yml --port 4003

Building Site¶

# Development build
bundle exec jekyll build --config _config_dev.yml

# Production build
JEKYLL_ENV=production bundle exec jekyll build

# Clean build
bundle exec jekyll clean
bundle exec jekyll build

Updating Dependencies¶

# Update all gems
bundle update

# Update specific gem
bundle update jekyll

# Update GitHub Pages gems
bundle update github-pages

# Check for outdated gems
bundle outdated

Running Scripts¶

# Link checker
python3 scripts/validation/link-checker.py --scope website

# Environment setup
./scripts/core/environment-setup.sh

# Build script
./scripts/development/build/build-site.sh

Troubleshooting¶

Common Issues¶

Issue: Port Already in Use¶

# Error: Address already in use - bind(2) for 127.0.0.1:4002

# Solution 1: Find and kill process
lsof -i :4002
kill -9 <PID>

# Solution 2: Use different port
bundle exec jekyll serve --config _config_dev.yml --port 4003

Issue: Bundle Install Fails¶

# Error: An error occurred while installing ffi

# Solution: Install system dependencies
# macOS
xcode-select --install

# Linux
sudo apt install build-essential libffi-dev

# Then retry
bundle install

Issue: Jekyll Command Not Found¶

# Error: command not found: jekyll

# Solution: Use bundle exec
bundle exec jekyll serve

# Or add to PATH
bundle install --binstubs
export PATH="./bin:$PATH"

Issue: Permission Denied¶

# Error: Permission denied

# Solution: Fix permissions
chmod +x scripts/**/*.sh

# Or run with bash
bash scripts/script-name.sh

Issue: Docker Build Fails¶

# Error: Docker build failed

# Solution 1: Clear cache and rebuild
docker-compose down -v
docker-compose build --no-cache

# Solution 2: Check Docker resources
# Increase memory/CPU in Docker Desktop settings

Getting Help¶

Check logs:
```
bundle exec jekyll serve --verbose
```
Run doctor:
```
bundle exec jekyll doctor
```
Search issues:
Jekyll Issues
IT-Journey Issues
Ask for help:
Create issue in IT-Journey repository
Include error messages and system info

Next Steps¶

After setup is complete:

Read Documentation:
Repository Structure
Jekyll Implementation
Content Guidelines
Explore the Code:
Browse pages/ directory
Review existing posts and quests
Check out scripts in scripts/
Make Your First Change:
Create a test post
Modify a page
Run local tests
Start Contributing:
Read Contributing Guide
Pick an issue to work on
Submit your first PR

Additional Resources¶

Last Updated: 2025-10-13 Version: 1.0.0