Workspace Setup

This guide covers cloning the EMS (Event Management System) repositories and setting up your development workspace in WSL2.

1. Prerequisites

Before proceeding, ensure you have completed:

  • Development Tools installation (especially Git with SSH keys)

  • SSH key added to your GitHub account

Verify SSH access to GitHub:

ssh -T [email protected]

You should see: "Hi <username>! You’ve successfully authenticated…​"

2. Directory structure

The EMS projects are organised under ~/dev/ems/:

~/dev/ems/                     # Clone of ems-workspace repository
├── .ai/                       # AI agent guidance
├── .claude/                   # Claude Code settings
├── .vscode/                   # VS Code settings
├── CLAUDE.md                  # Environment guidance for Claude Code
├── ems.code-workspace         # VS Code workspace file
├── admin-service/             # Spring Boot backend service
├── admin-ui/                  # Admin Angular application
├── common-db/                 # Shared libraries
├── database/                  # Database schemas and migrations
├── docs-event/                # Project documentation
├── membership-ui/             # Membership Angular application
├── parent-pom/                # Parent POM module
├── registration-portal/       # Registration Angular application
└── skills/                    # AI skills (clone of ems-skills repository)

The workspace configuration comes from the ems-workspace repository, which provides IDE settings, Claude Code configuration, and AI guidance out of the box.

3. Automated workspace setup

3.1. Quick start

The fastest way to set up the EMS workspace:

# 1. Clone the workspace configuration
mkdir -p ~/dev
cd ~/dev
git clone [email protected]:christhonie/ems-workspace.git ems
cd ems

# 2. Clone project repositories
git clone [email protected]:christhonie/event-admin-service.git admin-service
git clone [email protected]:christhonie/event-admin-ui.git admin-ui
git clone [email protected]:christhonie/event-common.git common-db
git clone [email protected]:christhonie/event-database.git database
git clone [email protected]:christhonie/docs-event.git docs-event
git clone [email protected]:christhonie/membership-ui.git membership-ui
git clone [email protected]:christhonie/event.git parent-pom
git clone [email protected]:christhonie/event-registration-ui.git registration-portal

# 3. Clone the AI skills repository
git clone [email protected]:christhonie/ems-skills.git skills

# 4. Configure sensitive files
cp .mcp.json.example .mcp.json
cp .claude/settings.local.json.example .claude/settings.local.json
# Edit these files with your credentials

# 5. Open in VS Code
code ems.code-workspace

3.2. Using the setup script

Alternatively, use this script to automate the cloning:

cat > ~/ems-workspace-setup.sh << 'EOF'
#!/bin/bash

# EMS Workspace Setup Script
# Clones ems-workspace and all project repositories

set -e

EMS_DIR="$HOME/dev/ems"
GITHUB_ORG="christhonie"

# Repository mappings: github-repo-name:local-directory-name
REPOS=(
    "event-admin-service:admin-service"
    "event-admin-ui:admin-ui"
    "event-common:common-db"
    "event-database:database"
    "docs-event:docs-event"
    "membership-ui:membership-ui"
    "event:parent-pom"
    "event-registration-ui:registration-portal"
    "ems-skills:skills"
)

# Clone workspace configuration first
if [ ! -d "$EMS_DIR" ]; then
    echo "Cloning ems-workspace..."
    mkdir -p "$(dirname "$EMS_DIR")"
    git clone "[email protected]:$GITHUB_ORG/ems-workspace.git" "$EMS_DIR"
else
    echo "Workspace directory exists, updating..."
    (cd "$EMS_DIR" && git pull)
fi

cd "$EMS_DIR"

# Clone project repositories
for repo_mapping in "${REPOS[@]}"; do
    github_repo="${repo_mapping%%:*}"
    local_dir="${repo_mapping##*:}"

    if [ -d "$local_dir" ]; then
        echo "Skipping $local_dir (already exists)"
    else
        echo "Cloning $github_repo as $local_dir..."
        git clone "[email protected]:$GITHUB_ORG/$github_repo.git" "$local_dir"
    fi
done

# Set up configuration files from examples
if [ ! -f ".mcp.json" ] && [ -f ".mcp.json.example" ]; then
    cp .mcp.json.example .mcp.json
    echo "Created .mcp.json from example - edit with your credentials"
fi

if [ ! -f ".claude/settings.local.json" ] && [ -f ".claude/settings.local.json.example" ]; then
    cp .claude/settings.local.json.example .claude/settings.local.json
    echo "Created .claude/settings.local.json from example - edit as needed"
fi

echo ""
echo "Workspace setup complete!"
echo "Projects cloned to: $EMS_DIR"
echo ""
echo "Next steps:"
echo "  1. Edit .mcp.json with your Azure DevOps credentials"
echo "  2. Edit .claude/settings.local.json as needed"
echo "  3. Open workspace: code $EMS_DIR/ems.code-workspace"
EOF

chmod +x ~/ems-workspace-setup.sh
~/ems-workspace-setup.sh

3.3. What the script does

  1. Clones the ems-workspace repository to ~/dev/ems/

  2. Clones each project repository from GitHub using SSH

  3. Clones the AI skills repository

  4. Creates configuration files from examples

  5. Uses local directory names that may differ from GitHub repository names

  6. Skips repositories that already exist (safe to re-run)

3.4. Renaming existing directories

If you have previously cloned the repositories with old directory names, use this script to rename them:

#!/bin/bash

# EMS Directory Rename Script
# Renames old directory names to new standardised names

cd ~/dev/ems

# Rename directories (only if old name exists and new name doesn't)
declare -A RENAMES=(
    ["event"]="parent-pom"
    ["event-admin-ui"]="admin-ui"
    ["event-common"]="common-db"
    ["event-database"]="database"
)

for old_name in "${!RENAMES[@]}"; do
    new_name="${RENAMES[$old_name]}"
    if [ -d "$old_name" ] && [ ! -d "$new_name" ]; then
        echo "Renaming $old_name -> $new_name"
        mv "$old_name" "$new_name"
    elif [ -d "$old_name" ] && [ -d "$new_name" ]; then
        echo "Warning: Both $old_name and $new_name exist. Skipping."
    elif [ ! -d "$old_name" ]; then
        echo "Skipping $old_name (does not exist)"
    fi
done

echo "Directory rename complete."
ls -la ~/dev/ems

4. Automated tool installation

You can also use a script to install all development tools:

cat > ~/install-dev-tools.sh << 'EOF'
#!/bin/bash

# EMS Development Tools Installation Script
# Run this on a fresh Ubuntu WSL2 installation

set -e

echo "=== Updating system packages ==="
sudo apt update && sudo apt upgrade -y

echo "=== Installing OpenJDK 21 ==="
sudo apt install openjdk-21-jdk -y

echo "=== Installing Maven ==="
sudo apt install maven -y

echo "=== Installing Git ==="
sudo apt install git -y

echo "=== Removing old Node.js (if present) ==="
sudo apt remove nodejs npm -y 2>/dev/null || true
sudo apt autoremove -y

echo "=== Installing Node.js 20 ==="
curl -fsSL https://deb.nodesource.com/setup_20.x | sudo -E bash -
sudo apt install nodejs -y

echo "=== Installing Angular CLI ==="
npm install -g @angular/cli

echo "=== Installing GitHub CLI ==="
sudo apt install gh -y

echo "=== Installing Liquibase ==="
cd /tmp
curl -L https://github.com/liquibase/liquibase/releases/download/v4.29.2/liquibase-4.29.2.tar.gz -o liquibase.tar.gz
sudo mkdir -p /opt/liquibase
sudo tar -xzf liquibase.tar.gz -C /opt/liquibase
rm liquibase.tar.gz

echo "=== Installing Azure CLI ==="
curl -sL https://aka.ms/InstallAzureCLIDeb | sudo bash

echo "=== Installing kubectl ==="
curl -LO "https://dl.k8s.io/release/$(curl -L -s https://dl.k8s.io/release/stable.txt)/bin/linux/amd64/kubectl"
sudo install -o root -g root -m 0755 kubectl /usr/local/bin/kubectl
rm kubectl

echo "=== Installing Claude Code ==="
npm install -g @anthropic-ai/claude-code

echo "=== Configuring environment ==="
cat >> ~/.bashrc << 'BASHRC'

# Java
export JAVA_HOME=/usr/lib/jvm/java-21-openjdk-amd64
export PATH="$PATH:$JAVA_HOME/bin"

# Liquibase
export PATH="$PATH:/opt/liquibase"

# npm global
export PATH="$PATH:$(npm config get prefix)/bin"
BASHRC

source ~/.bashrc

echo ""
echo "=== Installation complete! ==="
echo "Installed versions:"
echo "Java: $(java --version 2>&1 | head -1)"
echo "Maven: $(mvn --version 2>&1 | head -1)"
echo "Git: $(git --version)"
echo "Node.js: $(node --version)"
echo "npm: $(npm --version)"
echo "Angular CLI: $(ng version 2>&1 | grep 'Angular CLI' || echo 'installed')"
echo "GitHub CLI: $(gh --version 2>&1 | head -1)"
echo "kubectl: $(kubectl version --client --short 2>/dev/null || echo 'installed')"
echo "Liquibase: $(liquibase --version 2>&1 | head -1)"
echo "Azure CLI: $(az --version 2>&1 | head -1)"
echo "Claude Code: $(claude --version 2>&1 || echo 'installed')"
EOF

chmod +x ~/install-dev-tools.sh

Run the script:

~/install-dev-tools.sh

5. Manual repository cloning

If you prefer to clone repositories manually, start with the workspace configuration:

# Clone workspace configuration first
mkdir -p ~/dev
cd ~/dev
git clone [email protected]:christhonie/ems-workspace.git ems
cd ems

# Clone each project repository
git clone [email protected]:christhonie/event-admin-service.git admin-service
git clone [email protected]:christhonie/event-admin-ui.git admin-ui
git clone [email protected]:christhonie/event-common.git common-db
git clone [email protected]:christhonie/event-database.git database
git clone [email protected]:christhonie/docs-event.git docs-event
git clone [email protected]:christhonie/membership-ui.git membership-ui
git clone [email protected]:christhonie/event.git parent-pom
git clone [email protected]:christhonie/event-registration-ui.git registration-portal

# Clone AI skills
git clone [email protected]:christhonie/ems-skills.git skills

6. VS Code workspace file

The ems.code-workspace file is included in the ems-workspace repository. It contains:

  • All project folders with descriptive names

  • LF line ending configuration for WSL2 compatibility

  • Java and Maven settings

  • Search exclusions for build directories

  • Recommended extensions

Open the workspace:

code ~/dev/ems/ems.code-workspace

VS Code will prompt to install recommended extensions including Java, Maven, Angular, and Claude Code.

7. Opening projects in IntelliJ

For IntelliJ, open each project individually using the WSL2 path:

\\wsl$\Ubuntu\home\<username>\dev\ems\admin-service
\\wsl$\Ubuntu\home\<username>\dev\ems\parent-pom

IntelliJ’s project model works best with one project per window. Open multiple IntelliJ windows for different projects.

8. Verify workspace setup

After setup, verify all projects are cloned:

cd ~/dev/ems
ls -la

# Check Git status for each project
for dir in */; do
    echo "=== $dir ==="
    (cd "$dir" && git status --short)
done

9. Building projects

9.1. Java projects (Maven)

Build a Java project:

cd ~/dev/ems/admin-service
mvn clean install

Build all Java projects:

cd ~/dev/ems
for dir in parent-pom common-db database admin-service; do
    echo "=== Building $dir ==="
    (cd "$dir" && mvn clean install -DskipTests)
done

9.2. Angular projects (npm)

Install dependencies and build:

cd ~/dev/ems/registration-portal
npm install
npm run build

10. Next steps

Your development environment is now ready. For common issues, refer to the Troubleshooting guide.

10.1. Recommended next steps

  1. Open a project in IntelliJ or VS Code

  2. Run Claude Code in the project directory:

    cd ~/dev/ems/admin-service
claude

  3. Build and run the project to verify everything works