GitHub Codespaces

GitHub Codespaces is the cloud development environment that powers WP2Astro's IDE. This guide explains what codespaces are, how they work, and how to manage them effectively.

What are GitHub Codespaces?

GitHub Codespaces provides complete development environments in the cloud:

• Virtual machines running Linux (Ubuntu)
• Pre-configured with Node.js, npm, and Git
• Accessible via web browser
• Scalable from 2-core to 32-core machines
• Integrated with GitHub repositories

Think of it as "VS Code in the cloud" with your entire development environment.

Why WP2Astro Uses Codespaces

Benefits Over Local Development

No Installation Required:

• No Node.js to install
• No npm setup
• No dependency issues
• No OS compatibility problems

Consistent Environment:

• Same setup for all users
• No "works on my machine" problems
• Pre-configured for Astro
• Reproducible builds

Accessible Anywhere:

• Work from any device
• Continue on different computers
• Access via browser
• No files to sync

Powerful Hardware:

• Cloud servers handle builds
• Fast npm installs
• Quick rebuilds
• Parallel processing

Cost Effective:

• GitHub provides free tier
• Only pay for usage time
• Auto-stops when inactive
• Share resources across projects

How Codespaces Work

Architecture

Lifecycle

1. Created

2. Available (Running)

3. Idle

4. Shutdown (Stopped)

5. Deleted

Resource Allocation

Free Tier (GitHub Free Account)

Monthly Allowance:

• 120 core-hours of compute
• 15 GB of storage
• 2-core machines

What This Means:

Storage:

• 15 GB total across all codespaces
• Each codespace typically uses 2-4 GB
• Can have 3-7 codespaces active

Pro Tier (GitHub Pro Account)

Monthly Allowance:

• 180 core-hours of compute
• 20 GB of storage
• Access to larger machines (4-core, 8-core)

What This Means:

Team/Enterprise Tier

Organization-Managed:

• Usage pooled across team
• Custom limits set by admin
• Advanced security features
• Audit logs

Managing Your Codespaces

From WP2Astro Dashboard

Your dashboard shows:

• Total codespaces: How many you've created
• Active codespaces: Currently running
• Your plan: Free, Pro, Team, Enterprise

Actions:

• Create Codespace: New codespace for project
• Start Codespace: Wake up stopped codespace
• Stop Codespace: Suspend running codespace (via inactivity)
• Delete Codespace: Remove permanently

Codespace Status

Off (Stopped):

• Not consuming resources
• Click "Start Codespace"
• Starts in 20-30 seconds
• All files preserved

Starting:

• Booting up VM
• Installing dependencies
• Starting dev server
• Wait 30-60 seconds

Running (Available):

• Ready to use
• Click "Content" or "Dev Mode"
• IDE accessible
• Consuming compute hours

Shutting Down:

• Stopping VM
• Saving state
• Wait before restarting

Auto-Stop Behavior

Default Timeout

Codespaces automatically stop after:

• 4 hours of inactivity (default)
• Can be customized (30 min to 4 hours)

What counts as activity:

• Typing in editor
• Running terminal commands
• Browser focused on IDE
• Active WebSocket connection

What doesn't count:

• Just having browser tab open
• Switched to different tab
• Computer asleep
• Browser closed

Manual Stop

You can't manually stop codespaces from WP2Astro, but they auto-stop:

• After inactivity timeout
• When browser disconnected for extended period
• If you close the IDE

Why Auto-Stop Matters

• Saves resources: Don't waste compute hours
• Cost control: Only pay for active use
• Environment protection: Prevents runaway processes

Storage Management

What Uses Storage

Per Codespace:

• Project files (your code)
• node_modules/ (dependencies)
• Build output (dist/ folder)
• Git history
• Logs and cache

Typical Sizes:

Storage Limits

Free Tier:

• 15 GB total
• Can have 3-7 codespaces

Pro Tier:

• 20 GB total
• Can have 5-10 codespaces

Freeing Up Space

Delete Unused Codespaces:

1. Go to your dashboard
2. Find codespace to delete
3. Click "Remove" on codespace
4. Confirm deletion
5. Space freed immediately

Note: Your code is always safe in GitHub, only the codespace copy is deleted.

Check Usage

View your usage at:

• github.com/settings/billing
• See compute hours used
• See storage used
• Upgrade if needed

Machine Types

2-Core Machines (Default)

Specifications:

• 2 CPU cores
• 4 GB RAM
• 15-20 GB SSD

Cost: 1× compute rate

Best For:

• Content editing
• Small to medium projects
• Learning and experimentation
• Most Astro projects

4-Core Machines (Pro+)

Specifications:

• 4 CPU cores
• 8 GB RAM
• 30-40 GB SSD

Cost: 2× compute rate

Best For:

• Large projects
• Faster builds
• Heavy dependencies
• Multiple concurrent tasks

8-Core+ Machines (Pro+)

Specifications:

• 8-32 CPU cores
• 16-64 GB RAM
• 60-120 GB SSD

Cost: 4-16× compute rate

Best For:

• Very large projects
• Monorepos
• Extreme performance needs
• Team development

Note: WP2Astro uses 2-core by default, which is perfect for most Astro sites.

Customizing Your Codespace

Configuration File

WP2Astro sets up .devcontainer/devcontainer.json:

{
  "name": "Astro Development",
  "image": "mcr.microsoft.com/devcontainers/javascript-node:20",
  
  // Commands to run after creation
  "postCreateCommand": "npm install && npm run dev",
  
  // Ports to forward
  "forwardPorts": [4321, 8080],
  
  // Features to install
  "features": {
    "ghcr.io/devcontainers/features/github-cli:1": {}
  },
  
  // VS Code settings
  "customizations": {
    "vscode": {
      "extensions": [
        "astro-build.astro-vscode"
      ]
    }
  }
}

What You Can Customize

Base Image:

"image": "mcr.microsoft.com/devcontainers/javascript-node:20"

Change Node.js version or use different base.

Startup Commands:

"postCreateCommand": "npm install && npm run dev"

Commands to run when codespace starts.

Port Forwarding:

"forwardPorts": [4321, 8080]

Expose additional ports for services.

Additional Tools:

"features": {
  "ghcr.io/devcontainers/features/python:1": {},
  "ghcr.io/devcontainers/features/docker-in-docker:1": {}
}

Networking and Ports

Port Forwarding

Codespaces automatically forward ports:

Default Ports:

• 4321: Astro dev server (your site)
• 8080: WP2Astro WebSocket server

How It Works:

Accessing Other Ports

If you start additional services:

# Start additional server
npm run api-server # Port 3000

# GitHub auto-forwards it to:
# https://[codespace-name]-3000.app.github.dev

Port Visibility

Ports can be:

• Private: Only you can access
• Public: Anyone with URL can access

WP2Astro ports are private by default for security.

Security Considerations

What Codespaces Can Access

Your Repository:

• Read and write all files
• Push commits
• Create branches

GitHub Account:

• Limited to repository access
• Cannot access other repos
• Cannot change account settings

Network:

• Can make outbound requests
• Can install npm packages
• Cannot accept inbound connections (except forwarded ports)

What's Protected

Your GitHub Password:

• Never exposed to codespace
• OAuth tokens used instead

Other Repositories:

• Isolated per project
• Cannot access other codespaces

Environment Secrets:

• Encrypted at rest
• Only accessible in authorized codespaces

Best Practices

Don't Store Secrets in Code:

// ❌ Bad
const apiKey = "sk_live_123456";

// ✅ Good - Use environment variables
const apiKey = import.meta.env.API_KEY;

Use GitHub Secrets:

1. Repository Settings → Secrets
2. Add secret (e.g., API_KEY)
3. Access in code via env var

Be Careful with Extensions:

• Only install trusted extensions
• Review permissions
• Disable unused extensions

Troubleshooting

Codespace Won't Start

Problem: Stuck on "Starting..."

Solutions:

1. Wait 2 minutes (sometimes slow)
2. Check GitHub status page
3. Try deleting and recreating
4. Check quota isn't exceeded

Codespace Keeps Stopping

Problem: Stops after few minutes

Causes:

• Inactivity timeout triggered
• Browser tab not focused
• Poor internet connection
• WebSocket disconnected

Solutions:

• Keep IDE tab active
• Check internet stability
• Increase timeout in settings
• Use wired connection if possible

Running Out of Hours

Problem: "Quota exceeded" message

Solutions:

1. Check usage:

   • GitHub Settings → Billing
   • See hours remaining

2. Conserve hours:

   • Stop codespaces when done
   • Delete unused codespaces
   • Work in shorter sessions

3. Upgrade:

   • GitHub Pro for more hours
   • Team plan for unlimited (org-paid)

4. Work locally:

   • Clone repository
   • Run locally (free)
   • Push changes when done

Running Out of Storage

Problem: "Storage quota exceeded"

Solutions:

1. Delete old codespaces
2. Clean up node_modules:

   rm -rf node_modules
   npm install

3. Clear build artifacts:

   rm -rf dist .astro

4. Upgrade to Pro for 20 GB

Slow Performance

Problem: IDE is sluggish

Causes:

• Too many tabs open
• Large files open
• Heavy terminal output
• Low compute power

Solutions:

• Close unused tabs
• Split large files
• Clear terminal (Ctrl+L)
• Upgrade to 4-core machine (Pro)
• Restart codespace

Best Practices

Resource Conservation

Stop When Done:

• Don't leave codespaces running
• They auto-stop after 4 hours
• Manually navigate away to trigger stop

Delete Unused:

• Remove codespaces you don't need
• Keep only active projects
• Recreate if needed (quick)

Monitor Usage:

• Check monthly quota regularly
• Plan work within limits
• Upgrade if consistently running out

Optimal Workflow

Short Sessions:

Long Sessions:

Multiple Projects:

Alternatives to Codespaces

Local Development

If you prefer working locally:

# Clone your repository
git clone https://github.com/you/yourproject.git

# Install dependencies
cd yourproject
npm install

# Start dev server
npm run dev

Pros:

• No quota limits
• Works offline
• Full control
• Faster sometimes

Cons:

• Need to install Node.js, npm
• Setup required
• OS-specific issues
• No browser-based access

Hybrid Approach

Best of both worlds:

• Use codespaces for quick edits
• Use local for heavy development
• Git syncs changes between both
• Choose based on context

GitHub Settings

Configure Timeouts

1. Go to github.com/settings/codespaces
2. Adjust default timeout (30 min to 4 hours)
3. Set retention period (kept after stop)
4. Configure other preferences

View All Codespaces

1. Go to github.com/codespaces
2. See all your codespaces
3. Start, stop, or delete any
4. Monitor usage

Billing

1. Go to github.com/settings/billing
2. View compute hours used
3. View storage used
4. Set spending limits
5. Upgrade plan if needed

Cost Comparison

GitHub Free vs Pro

Free ($0/month):

• 120 core-hours
• 15 GB storage
• Good for: Hobbyists, learners, side projects

Pro ($4/month):

• 180 core-hours
• 20 GB storage
• Good for: Serious developers, multiple projects

Break Even: If you need more than 120 hours, Pro is worth it.

vs Cloud IDEs

GitHub Codespaces vs Others:

| Feature | Codespaces | Gitpod | Replit | |---------|-----------|--------|--------| | Free tier | 120 hrs | 50 hrs | Limited | | Storage | 15 GB | 30 GB | 500 MB | | Performance | Excellent | Good | Moderate | | GitHub integration | Native | Good | Basic | | Price (Pro) | $4/mo | $9/mo | $7/mo |

Future Improvements

GitHub Codespaces is actively developed:

Coming Soon:

• GPU support for ML workloads
• Better mobile experience
• Faster start times
• More regions worldwide

Next Steps

Now that you understand Codespaces:

• Start using the IDE effectively
• Explore Dev Mode features
• Learn about deployment

Additional Resources

• GitHub Codespaces Docs
• Codespaces Pricing
• Dev Containers Spec
• WP2Astro Support