fix: add automated port visibility setting and troubleshooting docs

Add gh CLI command to automatically set port 8080 to public during setup.
Create .devcontainer/README.md with manual steps for port visibility.

The devcontainer.json visibility setting doesn't reliably work, so we now:
1. Attempt automatic setting via gh CLI in setup.sh
2. Provide clear manual steps in README if automation fails

This addresses the persistent issue where ports default to private
even with visibility: public in devcontainer.json.

Author: gounthar

.devcontainer/README.md

@@ -0,0 +1,50 @@
+# Codespaces Configuration
+
+This directory contains the GitHub Codespaces dev container configuration.
+
+## Port Visibility Issue
+
+If port 8080 shows as **private** after creating a Codespace, you need to manually change it to **public**:
+
+### Manual Steps:
+1. Open the **PORTS** panel at the bottom of VS Code (next to TERMINAL)
+2. Find port **8080** in the list
+3. **Right-click** on port 8080
+4. Select **Port Visibility** → **Public**
+5. Refresh your browser and access Jenkins
+
+### Why is this needed?
+
+The `devcontainer.json` includes `"visibility": "public"` for port 8080, but GitHub Codespaces may not always apply this setting automatically, especially:
+- On the first Codespace creation
+- If there's an organization policy
+- If the port is forwarded before the container is fully started
+
+The setup script attempts to set the port visibility automatically using the GitHub CLI, but if that fails, manual intervention is required.
+
+## Files
+
+- **devcontainer.json** - Dev container specification
+- **setup.sh** - Initialization script (installs yq, configures URLs, creates welcome message)
+- **welcome.txt** - Generated welcome message (not in git, created at runtime)
+- **README.md** - This file
+
+## Accessing Jenkins
+
+After starting a tutorial with `docker compose --profile <name> up -d`:
+- Jenkins URL: `https://<codespace>-8080.<domain>` (shown in PORTS panel)
+- Default credentials: admin/admin
+
+## Troubleshooting
+
+**Port 8080 refuses connection:**
+- Ensure port visibility is set to **public** (see steps above)
+- Verify Jenkins is running: `docker compose ps`
+- Check logs: `docker compose logs jenkins_controller`
+
+**Welcome message not showing:**
+- Run: `source ~/.bashrc` in your terminal
+- Or open a new terminal window
+
+**yq not found:**
+- Run: `bash .devcontainer/setup.sh` manually

.devcontainer/setup.sh

@@ -92,3 +92,9 @@ if ! grep -q "Jenkins Quickstart Tutorials Welcome" ~/.bashrc; then
     echo "    cat /workspaces/quickstart-tutorials/.devcontainer/welcome.txt" >> ~/.bashrc
     echo "fi" >> ~/.bashrc
 fi
+
+# Set port 8080 visibility to public using gh CLI (if in Codespaces)
+if [ -n "$CODESPACE_NAME" ]; then
+    echo "🔓 Setting port 8080 visibility to public..."
+    gh codespace ports visibility 8080:public -c "$CODESPACE_NAME" 2>/dev/null || echo "⚠️  Could not set port visibility automatically. Please set port 8080 to public manually in the PORTS panel."
+fi