From 8b05573f2c314682b3647cc72bb05268dae7c73f Mon Sep 17 00:00:00 2001 From: Claude Date: Thu, 5 Nov 2026 16:04:58 +0000 Subject: [PATCH 1/2] docs: expand Claude Code docs, add Coder CLI page, replace outdated workspace guides MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit ## Short Summary (TL;DR) Expands the Claude Code page (terminal, VS Code extension, tips for DDEV projects), adds a "Using the Coder CLI" page that links to Coder's docs, and replaces the two guides carried over from the old docs, which gave wrong instructions for coder.ddev.com. ## The Issue A walk through the live docs.coder.ddev.com found: - The Claude Code page covered only remote control and the self-hosted runner, not using Claude Code in a terminal or in VS Code. - There was no single page on the local `coder` CLI; its commands were scattered across several pages. - "Your first workspace" and the "Detailed workspace guide" came from the old self-hosting-oriented docs. They tell readers to ask an administrator for a server URL, choose CPU and memory, work in `~/projects/`, set `router_disabled: true` (which breaks freeform routing) and use port forwarding instead of the site's URL. - The `coder-ddev-com` message templates for org operators were published as pages, reachable through search and the sitemap. - The docs header had no way back to start.coder.ddev.com. ## How This PR Solves The Issue - `workspaces/ai-tools.md`: adds the four ways of using Claude Code side by side, logging in from a remote workspace, terminal use (including keeping a session alive in `tmux`), the VS Code extension in VS Code for Web and in desktop VS Code, tips for DDEV projects, and updating, alongside the existing remote-control and runner sections. - New `workspaces/coder-cli.md`: installing, logging in, managing workspaces, template updates, schedules, SSH, `config-ssh` with `scp`/`rsync`, port forwarding, `coder open`, connection troubleshooting and tokens, each linking to the matching page in Coder's docs. Every command was checked against `coder --help` (v2.38.2). `editors-and-ssh.md` now links to it instead of repeating it, and other pages' CLI links point to it. - `getting-started/first-workspace.md` is now a five-minute walkthrough on coder.ddev.com: create a freeform workspace, start a PHP site, open it, stop the workspace. - `workspaces/guide.md` is removed. Its coder.ddev.com-relevant content was already covered by the shorter pages, and the rest is generic DDEV material that docs.ddev.com covers. A redirect sends `workspaces/guide/` to the lifecycle page, and the start.coder.ddev.com stub for the old `/user/using-workspaces` URL now points there too. - `mkdocs.yml`: excludes the `coder-ddev-com` templates from the build, and adds a "Start a workspace" link to start.coder.ddev.com in the navigation. ## Manual Testing Instructions - Open the Read the Docs preview and read the Claude Code, Using the Coder CLI and Your first workspace pages. - Follow "Your first workspace" on coder.ddev.com or staging; it has not been run end to end. - Install the Claude Code extension in VS Code for Web as described. I confirmed it installs from the Marketplace that VS Code for Web uses, but did not open its panel in a browser. - Check that `https://docs.coder.ddev.com/workspaces/guide/` redirects to the lifecycle page after deploy. ## Automated Testing Overview `make docs-check` passes (strict Zensical build, markdownlint, deep-link parameters). A full local linkspector run (0.5.6) reports all links valid. A headless-browser walk of the live site found no broken in-page anchors, images or unrendered Markdown; in the rebuilt pages no code block scrolls horizontally at 1280px. 🤖 Developed with assistance from [Claude Code](https://claude.ai/code) Co-Authored-By: Claude Opus 5.5 Claude-Session: https://claude.ai/code/session_01UrTUMw3UoHt66UH5tSoYTd --- docs/content/freeform/create.md | 2 +- docs/content/freeform/first-project.md | 2 +- docs/content/getting-started/access.md | 4 +- .../getting-started/first-workspace.md | 795 +---------- docs/content/getting-started/index.md | 2 +- docs/content/index.md | 2 +- docs/content/workspaces/ai-tools.md | 93 +- docs/content/workspaces/coder-cli.md | 148 ++ docs/content/workspaces/editors-and-ssh.md | 26 +- docs/content/workspaces/guide.md | 1228 ----------------- docs/content/workspaces/lifecycle.md | 2 +- docs/user/using-workspaces.html | 2 +- mkdocs.yml | 12 +- 13 files changed, 283 insertions(+), 2035 deletions(-) create mode 100644 docs/content/workspaces/coder-cli.md delete mode 100644 docs/content/workspaces/guide.md diff --git a/docs/content/freeform/create.md b/docs/content/freeform/create.md index 5a99f89..8d6014a 100644 --- a/docs/content/freeform/create.md +++ b/docs/content/freeform/create.md @@ -42,7 +42,7 @@ Off by default. Turn it on to have this workspace run sessions you start on clau ## From the command line -With the [Coder CLI](https://coder.com/docs/install/cli) logged in to coder.ddev.com: +With the [Coder CLI](../workspaces/coder-cli.md) logged in to coder.ddev.com: ```bash coder create --template freeform my-workspace diff --git a/docs/content/freeform/first-project.md b/docs/content/freeform/first-project.md index 0d64210..0c4d42e 100644 --- a/docs/content/freeform/first-project.md +++ b/docs/content/freeform/first-project.md @@ -6,7 +6,7 @@ This walkthrough takes you from an empty workspace to a running site. It assumes On the workspace page, click **VS Code**. When it opens, choose **Terminal → New Terminal** from the menu (☰). VS Code opens in `~/my-site`, a directory named after the workspace; it may not exist yet, in which case VS Code opens your home directory. -You can also use SSH from your computer. See [Editors, SSH and files](../workspaces/editors-and-ssh.md). +You can also use SSH from your computer. See [Using the Coder CLI](../workspaces/coder-cli.md#ssh-into-a-workspace). ## 2. Get your code diff --git a/docs/content/getting-started/access.md b/docs/content/getting-started/access.md index d0a32cf..9dbb279 100644 --- a/docs/content/getting-started/access.md +++ b/docs/content/getting-started/access.md @@ -29,10 +29,10 @@ If you see an "access denied" page, your GitHub account isn't in one of the orga ## Use the CLI (optional) -The [Coder CLI](https://coder.com/docs/install/cli) lets you SSH into workspaces, copy files, and connect desktop editors. +The [Coder CLI](../workspaces/coder-cli.md) lets you SSH into workspaces, copy files, and connect desktop editors. ```bash coder login https://coder.ddev.com ``` -This opens your browser to approve the login. See [Editors, SSH and files](../workspaces/editors-and-ssh.md) for what you can do next. +This opens your browser to approve the login. See [Using the Coder CLI](../workspaces/coder-cli.md) for how to install it and what you can do with it. diff --git a/docs/content/getting-started/first-workspace.md b/docs/content/getting-started/first-workspace.md index 054d8ed..c50e2c4 100644 --- a/docs/content/getting-started/first-workspace.md +++ b/docs/content/getting-started/first-workspace.md @@ -1,793 +1,56 @@ -# Getting Started with DDEV Coder Workspaces +# Your First Workspace -This guide helps you create your first DDEV workspace and start developing in the cloud. +This walkthrough takes about five minutes. You create a freeform workspace, start a small PHP site in it with DDEV, open it in your browser, and stop the workspace. You only need a browser and a GitHub account with [access](access.md). -## What is Coder? +## 1. Create the workspace -**Coder** is an open-source platform for creating remote development environments. Instead of developing on your local machine, you work in a cloud-based workspace with all tools pre-installed. +1. Sign in at [coder.ddev.com](https://coder.ddev.com/login) with GitHub. +2. Open the [freeform template](https://coder.ddev.com/templates/coder/freeform/workspace?mode=manual). +3. Name the workspace `hello`. Leave **DDEV project names** empty, so the workspace has one project, also named `hello`. +4. Click **Create workspace**. -**Key concepts:** +The workspace page shows the startup log. When the workspace is ready, usually in about a minute, the app buttons become active: **VS Code**, **hello**, **Mailpit (hello)** and **xhgui (hello)**. -- **Workspace** - Your personal development environment (like a remote VM) -- **Template** - A blueprint for creating workspaces (pre-configured tools, settings) -- **Agent** - Software running in your workspace that connects to Coder server +## 2. Open VS Code -**What is DDEV?** +Click **VS Code**. It opens in your browser. Open a terminal with **Terminal → New Terminal** from the menu (☰). -**DDEV** is a local development tool for PHP, Node.js, and Python projects. It uses Docker containers to provide consistent development environments with databases, web servers, and development tools. - -With this template, DDEV runs inside your cloud workspace, giving you all DDEV features without local setup. - -## Prerequisites - -### Coder Account - -You need access to a Coder server. Ask your administrator for: - -- Coder server URL (e.g., `https://coder.example.com`) -- Username and password (or SSO login) -- Confirmation that the `freeform` template is available - -### Local Tools - -Install on your local machine: - -**Coder CLI** (required for SSH access): +Check that everything is there: ```bash -# macOS (Homebrew) -brew install coder/coder/coder - -# Linux (curl) -curl -L https://coder.com/install.sh | sh - -# Windows (PowerShell) -winget install Coder.Coder - -# Or download from: https://github.com/coder/coder/releases -``` - -**SSH client** (usually pre-installed): - -```bash -# Verify SSH is available -ssh -V -``` - -**Git** (optional, for cloning repositories): - -```bash -# macOS -brew install git - -# Linux -apt-get install git # or yum install git - -# Windows -winget install Git.Git - -# Verify -git --version -``` - -### Optional: Desktop VS Code - -If you prefer desktop VS Code over the web version: - -```bash -# Download from https://code.visualstudio.com/ -# Install Remote-SSH extension -code --install-extension ms-vscode-remote.remote-ssh -``` - -## Step 1: Login to Coder - -### Via Web UI - -1. Open your Coder server URL in a browser -2. Enter your username and password -3. Click **Login** - -You'll see the Coder dashboard. - -### Via CLI - -```bash -# Login to Coder server -coder login https://coder.example.com - -# Enter your credentials when prompted -# Or use an API token if provided -``` - -**Verify login:** - -```bash -coder list -# Should show your workspaces (empty if this is your first time) -``` - -## Step 2: Create Your First Workspace - -### Via Web UI - -1. Click **Create Workspace** button -2. Select **freeform** template -3. Enter a workspace name (e.g., `my-first-workspace`) - - Use lowercase, numbers, hyphens - - No spaces or special characters -4. (Optional) Configure parameters: - - **CPU**: Number of cores (default: 4) - - **Memory**: RAM in GB (default: 8) - - **Node.js version**: Node version (default: 24) -5. Click **Create Workspace** - -**Wait for workspace to start** (1-3 minutes): - -- Status will change from "Starting" to "Running" -- You'll see the workspace dashboard - -### Via CLI - -```bash -# Create workspace with defaults -coder create --template freeform my-first-workspace --yes - -# Or with custom parameters -coder create --template freeform my-first-workspace \ - --parameter cpu=8 \ - --parameter memory=16 \ - --yes -``` - -**Check workspace status:** - -```bash -coder list -# Should show your workspace as "Running" -``` - -## Step 3: Access Your Workspace - -### Option 1: VS Code for Web (Recommended for Beginners) - -1. In Coder dashboard, find your workspace -2. Under **Apps**, click **VS Code** -3. VS Code opens in your browser - -**You now have a full IDE in the cloud!** - -### Option 2: SSH (Command Line) - -```bash -# SSH into workspace -coder ssh my-first-workspace - -# You're now inside your workspace -# The prompt changes to: coder@my-first-workspace:~$ -``` - -**Run your first command:** - -```bash -# Check DDEV is installed ddev version - -# Check Docker is running -docker ps - -# Check Node.js version -node --version - -# Exit SSH session -exit -``` - -### Option 3: Desktop VS Code with Remote-SSH - -```bash -# Configure SSH for Coder workspaces -coder config-ssh - -# Open desktop VS Code -# Use Remote-SSH extension to connect to: coder.my-first-workspace -``` - -## Step 4: Verify Your Environment - -### Check Docker - -```bash -# Inside workspace (via SSH or VS Code terminal) -docker ps -# Should show: CONTAINER ID IMAGE COMMAND ... -# (Empty list is normal - no containers running yet) - -docker info -# Should show Docker system information -``` - -If Docker doesn't work, see [Troubleshooting](#troubleshooting) below. - -### Check DDEV - -```bash -ddev version -# Should show DDEV version (latest version from image) - -ddev list -# Should show: No running DDEV projects were found. -``` - -### Check Disk Space - -```bash -df -h -# Should show plenty of free space on / and /home/coder -``` - -### Check Available Resources - -```bash -# CPU cores -nproc - -# RAM -free -h - -# Should match what you configured (default: 4 cores, 8GB RAM) -``` - -## Step 5: Create Your First DDEV Project - -### Option A: New Project from Scratch - -```bash -# Create project directory -mkdir -p ~/projects/my-site -cd ~/projects/my-site - -# Initialize DDEV project -# Choose a project type: php, wordpress, drupal, laravel, etc. -ddev config --project-type=php --docroot=web - -# Start DDEV -ddev start -``` - -**Wait for DDEV to start** (1-2 minutes first time): - -``` -Starting my-site... -... -Successfully started my-site -Project can be reached at https://my-site.ddev.site -``` - -### Option B: Clone Existing Project - -```bash -# Set up Git SSH first (see Step 8 below) - -# Clone your repository -cd ~/projects -git clone git@github.com:username/repo.git my-site -cd my-site - -# Configure DDEV (if not already configured) -ddev config --auto - -# Start DDEV -ddev start -``` - -### Option C: Quick Demo with Composer Project - -```bash -# Create a Laravel project -mkdir -p ~/projects/demo-laravel -cd ~/projects/demo-laravel - -# Configure DDEV -ddev config --project-type=laravel --docroot=public - -# Use DDEV's Composer to create Laravel project -ddev composer create laravel/laravel - -# Start DDEV -ddev start -``` - -## Step 6: Access Your DDEV Project - -### Understanding Coder Port Forwarding - -DDEV normally uses URLs like `https://my-site.ddev.site`, but in Coder, you access projects via **port forwarding**. - -**How it works:** - -1. DDEV listens on ports 80/443 inside workspace -2. Coder forwards these ports through its proxy -3. You access via Coder's forwarded URLs - -### Access Your Project - -**Via Coder Web UI (Recommended):** - -1. Go to Coder dashboard -2. Find your workspace -3. Under **Apps**, click **DDEV Web** -4. Your DDEV project loads in a new tab - -The URL follows the pattern: `https://ddev-web--workspace-name--owner.coder.example.com/` - -**Via CLI Port Forward:** - -```bash -# Forward port to your local machine -coder port-forward my-first-workspace --tcp 8080:80 - -# Then access in your browser: -# http://localhost:8080 -``` - -**Check DDEV status:** - -```bash -ddev describe -# Shows project details and status -# Note: URLs shown by ddev describe won't work - use Coder's forwarded URLs instead -``` - -## Step 7: Make Changes and Test - -### Edit Files - -**Via VS Code for Web:** - -1. Open VS Code (Apps → VS Code in Coder UI) -2. Navigate to `~/projects/my-site` -3. Edit files normally -4. Changes are saved automatically - -**Via SSH and vim:** - -```bash -coder ssh my-first-workspace -cd ~/projects/my-site -vim web/index.php -``` - -### Reload and Test - -```bash -# Refresh your browser to see changes -# Or use DDEV commands: - -ddev describe # Show project info -ddev logs # View container logs -ddev exec # Run command in web container -``` - -### Common DDEV Commands - -```bash -# Start project -ddev start - -# Stop project -ddev stop - -# Restart project -ddev restart - -# View status -ddev describe - -# View logs -ddev logs - -# SSH into web container -ddev ssh - -# Run Composer -ddev composer install - -# Run npm -ddev npm install -ddev npm run dev - -# Import database -ddev import-db --file=dump.sql.gz - -# Export database -ddev export-db --file=dump.sql.gz - -# View all commands -ddev help -``` - -## Step 8: Working with Git - -### Configure Git - -```bash -# Inside workspace -git config --global user.name "Your Name" -git config --global user.email "your.email@example.com" -``` - -### Set Up Git SSH for Private Repositories - -To clone private repositories or push to GitHub/GitLab/etc, you need to add your Coder public key to your Git host. - -#### Step 1: Get your Coder public key - -```bash -# Inside workspace (via SSH or VS Code terminal) -coder publickey - -# This shows your Coder-managed public key -# Copy the entire output (starts with ssh-ed25519 or ssh-rsa) -``` - -## Step 2: Add key to your Git host - -**For GitHub:** - -1. Go to -2. Click **New SSH key** -3. Paste your Coder public key -4. Click **Add SSH key** - -**For GitLab:** - -1. Go to -2. Paste your Coder public key -3. Click **Add key** - -**For Bitbucket:** - -1. Go to -2. Click **Add key** -3. Paste your Coder public key - -### Step 3: Test SSH connection - -```bash -# Test GitHub -ssh -T git@github.com -# Should say: "Hi username! You've successfully authenticated..." - -# Test GitLab -ssh -T git@gitlab.com -# Should say: "Welcome to GitLab, @username!" -``` - -### Clone and Push - -```bash -# Clone private repository -cd ~/projects -git clone git@github.com:username/private-repo.git - -# Make changes -cd private-repo -# ... edit files ... - -# Commit and push -git add . -git commit -m "Update from Coder workspace" -git push -``` - -**How it works:** Coder's GitSSH wrapper automatically uses your Coder-managed SSH key for all Git operations. You don't need to manage SSH keys inside the workspace. - -## Managing Your Workspace - -### Stop Workspace (Save Costs) - -When not actively developing: - -```bash -# Via CLI -coder stop my-first-workspace - -# Via UI: Click "Stop" button on workspace -``` - -**What happens when stopped:** - -- Workspace container stops -- All files in `/home/coder` are preserved -- DDEV projects are preserved -- Billing/resource usage stops - -### Start Workspace - -```bash -# Via CLI -coder start my-first-workspace - -# Via UI: Click "Start" button on workspace -``` - -**Startup time:** faster than initial create (no reinstall needed) - -**After starting:** - -```bash -# SSH in -coder ssh my-first-workspace - -# Restart DDEV projects -cd ~/projects/my-site -ddev start -``` - -### Delete Workspace (Permanent) - -⚠️ **Warning:** This deletes all data permanently! - -```bash -# Via CLI -coder delete my-first-workspace - -# Via UI: Click "Delete" button, confirm -``` - -**What gets deleted:** - -- Workspace container -- All files in `/home/coder` -- All DDEV projects and databases -- Docker images and volumes inside workspace - -**Before deleting:** - -```bash -# Backup important data -cd ~/projects -tar -czf backup.tar.gz my-site/ -# Download via VS Code or scp -``` - -## Troubleshooting - -### Workspace Won't Start - -**Check status:** - -```bash -coder list -# If stuck in "Starting", check logs: -coder logs my-first-workspace -``` - -**Common causes:** - -- Template not deployed correctly (contact admin) -- Resource limits exceeded (contact admin) -- Sysbox runtime not installed on host (contact admin) - -### Docker Not Working - -**Symptom:** `Cannot connect to Docker daemon` - -**Solution:** - -```bash -# Check Docker service -systemctl status docker - -# Restart Docker -sudo systemctl restart docker - -# Wait a few seconds, then test -docker ps -``` - -If still broken, restart workspace: `coder restart my-first-workspace` - -### DDEV Won't Start - -**Symptom:** `ddev start` fails - -**Check Docker first:** - -```bash docker ps -# If this fails, fix Docker before DDEV -``` - -**Common DDEV issues:** - -```bash -# Reset DDEV project -ddev poweroff -ddev start - -# Or delete and recreate -ddev delete --omit-snapshot -ddev config --auto -ddev start -``` - -### Can't Access DDEV Project - -**Symptom:** Port forwarding shows ports but URLs don't load - -**Check:** - -```bash -# Inside workspace -ddev describe -curl localhost:80 -# Should return HTML -``` - -**Solution:** - -- Use Coder's port forwarding links (not DDEV URLs) -- Find port URLs in the **Ports** section of Coder web UI -- DDEV's URLs (*.ddev.site) won't work in Coder - -### Git SSH Not Working - -**Symptom:** `Permission denied (publickey)` when cloning - -**Solution:** - -1. Get your Coder public key: `coder publickey` -2. Add that key to GitHub/GitLab (Settings → SSH Keys) -3. Test: `ssh -T git@github.com` -4. If still failing, regenerate: `coder publickey --reset` and add new key to Git host - -### Out of Disk Space - -**Symptom:** `No space left on device` - -**Solution:** - -```bash -# Clean Docker images and volumes -docker system prune -a --volumes -f - -# Check disk usage -df -h -du -sh ~/projects/* - -# Delete unused projects -rm -rf ~/projects/old-project -``` - -### Workspace is Slow - -**Check resources:** - -```bash -# Inside workspace -top # Check CPU usage -free -h # Check RAM usage -docker stats # Check Docker container resources ``` -**Solution:** - -- Stop unused DDEV projects: `ddev stop --all` -- Increase workspace resources (delete and recreate with higher CPU/RAM) -- Contact admin to increase default resources - -## Next Steps - -### Learn More About DDEV +## 3. Start a site -- **[DDEV Documentation](https://docs.ddev.com/)** - Full DDEV docs -- **[DDEV Quickstart](https://docs.ddev.com/en/stable/users/quickstart/)** - DDEV basics -- **[DDEV Commands](https://docs.ddev.com/en/stable/users/usage/commands/)** - Command reference - -### Learn More About Coder - -- **[Using Workspaces](../workspaces/guide.md)** - Daily workflows and tips -- **[Coder CLI](https://coder.com/docs/reference/cli)** - CLI reference -- **[VS Code for Web](https://coder.com/docs/ides/web-ides)** - IDE features - -### Try More Project Types +Paste this into the terminal: ```bash -# WordPress -ddev config --project-type=wordpress --docroot=web -ddev composer create roots/bedrock - -# Drupal -ddev config --project-type=drupal --docroot=web -ddev composer create drupal/recommended-project - -# Laravel -ddev config --project-type=laravel --docroot=public -ddev composer create laravel/laravel - -# Node.js (generic) -ddev config --project-type=php --docroot=. -echo "console.log('Hello');" > server.js -node server.js - -# Static site -ddev config --project-type=php --docroot=. -echo "

Hello World

" > index.html +mkdir -p ~/hello/public && cd ~/hello +echo ' public/index.php +ddev config --project-name=hello --project-type=php --docroot=public +ddev coder-setup ddev start ``` -### Customize Your Workspace - -```bash -# Install additional tools -sudo apt-get update -sudo apt-get install - -# Install global npm packages -npm install -g - -# Add shell aliases -echo 'alias ll="ls -la"' >> ~/.bashrc -source ~/.bashrc -``` - -**Note:** Changes to system packages are lost when workspace is deleted. For permanent changes, ask admin to modify Docker image. - -## Tips and Best Practices - -### File Organization - -```bash -~/projects/ # All DDEV projects here - ├── project1/ - ├── project2/ - └── project3/ -~/.ddev/ # DDEV global config (auto-created) -~/.ssh/ # SSH keys (managed by Coder) -``` - -### Resource Management - -- **Stop workspaces** when not in use (saves costs) -- **Stop unused DDEV projects**: `ddev stop --all` -- **Clean Docker regularly**: `docker system prune -a` - -### Backup Important Data - -- **Commit to Git** regularly (safest backup) -- **Export databases**: `ddev export-db --file=backup.sql.gz` -- **Download files** via VS Code or `scp` (after `coder config-ssh`) - -### Performance - -- **Use smaller workspaces** for simple projects (2 CPU, 4GB RAM) -- **Increase resources** for large projects (8 CPU, 16GB RAM) -- **Stop background services** when not needed - -## Getting Help +`ddev coder-setup` connects the project to the workspace's routing; every freeform project needs it once. -### Documentation +## 4. Open the site -- [Using Workspaces](../workspaces/guide.md) - Advanced workflows -- [Troubleshooting Guide](../workspaces/troubleshooting.md) - Detailed debugging -- [DDEV Docs](https://docs.ddev.com/) - DDEV reference +Click the **hello** button on the workspace page, or run `ddev launch` in the terminal and open the URL it prints. The address looks like `https://hello--hello--.coder.ddev.com`. Only you can open it, unless you turn on [public sharing](../freeform/sharing.md). -### Support +Edit `public/index.php` in VS Code and reload the page to see the change. -- **Ask your administrator** for Coder-specific issues -- **GitHub Issues**: [Report bugs](https://github.com/ddev/coder-ddev/issues) -- **DDEV Community**: [DDEV Discord](https://discord.gg/hCZFfAMc5k) -- **Coder Community**: [Coder Discord](https://discord.gg/coder) +## 5. Stop the workspace -### Before Asking for Help +When you're done, click **Stop** on the workspace page. Your files and database are kept; click **Start** to continue later, then run `ddev start` in the project again. -1. Check this guide's [Troubleshooting](#troubleshooting) section -2. Review [Troubleshooting Guide](../workspaces/troubleshooting.md) -3. Collect error messages and logs -4. Try restarting workspace: `coder restart my-first-workspace` +Workspaces that go unused are deleted after a warning email. See [Workspace lifecycle](../workspaces/lifecycle.md) for what persists and for how long. ---- +## Next steps -**Congratulations!** You've created your first DDEV workspace. Happy coding! 🎉 +- Bring your own project, or run several: [Freeform workspaces](../freeform/index.md). +- Work on a Drupal issue instead: [Drupal quickstart](../drupal/quickstart.md). +- Use SSH, `scp` or desktop editors from your computer: [Using the Coder CLI](../workspaces/coder-cli.md). +- Let Claude Code work in the workspace: [Claude Code](../workspaces/ai-tools.md). diff --git a/docs/content/getting-started/index.md b/docs/content/getting-started/index.md index 7b0f8d0..8e358e2 100644 --- a/docs/content/getting-started/index.md +++ b/docs/content/getting-started/index.md @@ -22,7 +22,7 @@ DDEV Coder Workspaces are cloud development environments hosted at [coder.ddev.c - A web browser. Everything else is optional. - A GitHub account that has access. See [Getting access](access.md). -- Optional: the [Coder CLI](https://coder.com/docs/install/cli) if you want to use SSH, `scp` or desktop editors. See [Editors, SSH and files](../workspaces/editors-and-ssh.md). +- Optional: the [Coder CLI](../workspaces/coder-cli.md) if you want to use SSH, `scp` or desktop editors. ## Next steps diff --git a/docs/content/index.md b/docs/content/index.md index 61318cf..37255a1 100644 --- a/docs/content/index.md +++ b/docs/content/index.md @@ -26,7 +26,7 @@ --- - What persists, VS Code and SSH, Claude Code, and fixing common problems. + What persists, the Coder CLI, editors and SSH, Claude Code, and fixing common problems. diff --git a/docs/content/workspaces/ai-tools.md b/docs/content/workspaces/ai-tools.md index 419c9c7..2ab2ff4 100644 --- a/docs/content/workspaces/ai-tools.md +++ b/docs/content/workspaces/ai-tools.md @@ -1,24 +1,104 @@ # Claude Code -Every workspace has [Claude Code](https://claude.com/claude-code) installed. You can use it three ways. +Every workspace has [Claude Code](https://claude.com/claude-code) installed, and Claude can use everything in the workspace: DDEV, Docker, Git, Composer and the rest. You can use it in four ways: + +| Way | Where you talk to Claude | Setup | +| ------------------------------------------------------------ | ------------------------------------------------ | --------------------------------------------- | +| [In a terminal](#in-a-terminal) | A terminal in VS Code for Web, or over SSH | None | +| [VS Code extension](#in-vs-code) | A panel in VS Code for Web or desktop VS Code | Install the extension once | +| [Remote control](#claude-code-remote-control) | claude.ai/code or the Claude mobile app | Turn on a workspace setting | +| [Self-hosted runner](#claude-code-self-hosted-runner) | Sessions you start on claude.ai/code | Turn on a workspace setting, save a secret | + +All of them use the same installation and the same login, both kept in your home directory, so they survive restarts. + +## Logging in + +The first time you run Claude Code, it asks how to log in: + +1. Run `claude` in a terminal and choose to log in with your Claude account. +2. Claude Code prints a link. Open it in your browser, approve the login, and copy the code it shows. +3. Paste the code back into the terminal. + +Claude Code works with a Claude Pro, Max, Team or Enterprise subscription, or with an Anthropic API key (set `ANTHROPIC_API_KEY`, for example in `~/.bashrc`). Remote control needs a subscription; API keys don't work for it. ## In a terminal -Open a terminal in the workspace and run `claude` in your project directory. The first time, it asks you to log in. Your login is kept in your home directory, so it survives restarts. +Open a terminal in the project directory (in VS Code for Web, **Terminal → New Terminal**) and start Claude: + +```bash +cd ~/my-site +claude +``` + +Useful options: + +```bash +claude --continue # continue the last conversation here +claude --resume # pick an earlier conversation + +# one-off question: prints the answer and exits +claude -p "why does ddev start fail?" +``` + +!!! tip "Keep Claude running when you close the browser" + A terminal in VS Code for Web ends when you close the tab, and so does a Claude session running in it. Start Claude inside `tmux` to keep it running, and reattach later from any terminal or SSH session: + + ```bash + tmux new -s claude # run claude in here; Ctrl-b d detaches + tmux attach -t claude # reattach later + ``` + + Or turn on [remote control](#claude-code-remote-control), which does this for you. + +From your own computer, you can run Claude in the workspace over SSH with `coder ssh my-site`, then `cd` to the project and run `claude`. See [Using the Coder CLI](coder-cli.md). + +## In VS Code + +The [Claude Code extension](https://marketplace.visualstudio.com/items?itemName=anthropic.claude-code) adds a Claude panel to VS Code, with inline diffs of Claude's proposed changes. + +**In VS Code for Web:** + +1. Open the Extensions view (++ctrl+shift+x++, or ++cmd+shift+x++ on macOS). +2. Search for **Claude Code** and install the one published by **Anthropic**. +3. Open it with the Claude icon in the editor toolbar or the activity bar, or run **Claude Code: Open** from the Command Palette (++ctrl+shift+p++). + +The extension is installed in the workspace, so it stays installed across restarts. + +**In desktop VS Code:** connect to the workspace with the [Coder extension](https://marketplace.visualstudio.com/items?itemName=coder.coder-remote) (or `coder open vscode my-site`), then install the Claude Code extension in that remote window. VS Code installs it in the workspace, and Claude runs there, next to DDEV, rather than on your computer. + +If you have already logged in from a terminal, the extension uses the same login. See Anthropic's [VS Code documentation](https://code.claude.com/docs/en/vs-code) for everything the extension can do. + +## Tips for working with DDEV + +- **Tell Claude the project uses DDEV.** Put a `CLAUDE.md` (or `AGENTS.md`) in the project saying to run PHP, Composer, Drush and tests through DDEV, for example `ddev composer install`, `ddev drush cr`, `ddev exec vendor/bin/phpunit`. Otherwise Claude may try to run them directly in the workspace, where the project's PHP version and extensions aren't installed. +- **Let Claude check the site from inside the workspace.** Claude can test its work with `curl`. Inside the workspace, the project's `https://.ddev.site` URL reaches the site directly; the `coder.ddev.com` URLs need your browser login, so Claude can't use them. If `curl` rejects the certificate, run `mkcert -install` once. +- **Projects share one Docker daemon.** `ddev poweroff`, `ddev stop --all` or `docker system prune` affect every project in the workspace. Say so in `CLAUDE.md` if you run several projects. +- **Permission prompts.** By default Claude asks before running commands or editing files. You can allow specific commands as you go. Skipping prompts entirely (`--dangerously-skip-permissions`) lets Claude run anything in the workspace, including deleting databases. + +## Keeping Claude Code up to date + +Claude Code is installed with Homebrew, which persists across restarts: + +```bash +brew upgrade claude-code@latest +claude --version +``` + +The VS Code extension updates itself from the Marketplace. ## Claude Code remote control Turn on **Enable Claude Code remote control** in the workspace's settings (all templates offer it) to drive Claude Code in the workspace from [claude.ai/code](https://claude.ai/code) or the Claude mobile app, even when no browser tab or terminal is open. 1. Turn the setting on when creating the workspace, or later in **Settings → Parameters**, then restart. -2. **First use:** click the **Claude Code** app button on the workspace page (or SSH in) and complete the one-time Claude login and the workspace trust prompt. +2. **First use:** click the **Claude Code** app button on the workspace page (or SSH in and run `tmux attach -t `) and complete the one-time login and the workspace trust prompt. 3. The session then shows up on claude.ai/code under the workspace's name. -To work in a particular project, `cd` into it in any terminal and run `claude-here`. That starts a new remote-control session in that directory, named after it, and the previous session stops appearing in claude.ai/code. +Claude runs in the `tmux` session named after the workspace, starting in your home directory. To work in a particular project, `cd` into it in any terminal and run `claude-here`. That starts a new remote-control session in that directory, named `-`, and the previous session stops appearing in claude.ai/code. - **Claude Code: skip permission prompts** runs Claude with `--dangerously-skip-permissions`. Only use it if you're comfortable with Claude running any command in the workspace without asking. - Requires a Claude Pro, Max, Team or Enterprise subscription. API keys, Bedrock, Vertex and custom gateways are not supported. -- Remote sessions disconnect after about 10 minutes offline. +- Remote sessions disconnect after about 10 minutes offline. The workspace restarts Claude when it starts, or when you click the **Claude Code** app button. ## Claude Code self-hosted runner @@ -31,7 +111,8 @@ One-time setup: ```bash mkdir -p ~/.claude-runner - cat > ~/.claude-runner/environment-secret # paste, press Enter, then Ctrl-D + # paste the secret, press Enter, then Ctrl-D + cat > ~/.claude-runner/environment-secret chmod 600 ~/.claude-runner/environment-secret ``` diff --git a/docs/content/workspaces/coder-cli.md b/docs/content/workspaces/coder-cli.md new file mode 100644 index 0000000..b337fe3 --- /dev/null +++ b/docs/content/workspaces/coder-cli.md @@ -0,0 +1,148 @@ +# Using the Coder CLI + +Everything in a workspace can be done from the browser, but the `coder` command-line tool on your own computer adds SSH, file copying, port forwarding and desktop editors. Coder's own [CLI reference](https://coder.com/docs/reference/cli) documents every command; this page covers the ones you need for coder.ddev.com. + +## Install + +=== "macOS" + + ```bash + brew install coder + ``` + +=== "Linux" + + ```bash + curl -L https://coder.com/install.sh | sh + ``` + +=== "Windows" + + ```powershell + winget install Coder.Coder + ``` + +See [Coder's installation docs](https://coder.com/docs/install/cli) for other methods. Check that it works with `coder version`. + +!!! tip "Keep the CLI up to date" + The CLI warns you when its version doesn't match the server's. Upgrade it the same way you installed it (for example `brew upgrade coder`). + +## Log in + +```bash +coder login https://coder.ddev.com +``` + +This opens your browser, where you approve the login with your coder.ddev.com account; the CLI then stores a session token. `coder whoami` shows who you're logged in as, and `coder logout` removes the token. + +## Manage workspaces + +```bash +coder list # your workspaces and their status +coder create --template freeform my-site # create one (asks for each setting) +coder start my-site +coder stop my-site +coder restart my-site +coder delete my-site # deletes everything in it +coder show my-site # resources, agents and apps +``` + +`coder start`, `coder stop`, `coder restart` and `coder delete` each take one workspace name. + +To give a list of project names, which contain commas, use a parameter file instead of `--parameter`; see [Creating a freeform workspace](../freeform/create.md#from-the-command-line). + +### Template updates + +When the template gets a new version, the workspace page shows an **Update** button. From the CLI: + +```bash +coder update my-site +``` + +This stops the workspace if it is running, rebuilds it with the new template version and starts it again. Your home directory and databases are kept. + +To change a setting from the CLI, use `coder update my-site --always-prompt`, which asks for every setting again. Changing settings in the web UI (**Settings → Parameters**) is usually simpler. + +### Schedules + +```bash +coder schedule show my-site # when it stops automatically +coder schedule extend my-site 2h # keep a running workspace up 2 more hours +``` + +See [Coder's workspace scheduling docs](https://coder.com/docs/user-guides/workspace-scheduling). + +## SSH into a workspace + +```bash +coder ssh my-site # interactive shell +coder ssh my-site -- ddev list # run one command + +# run a command in a particular directory +coder ssh my-site -- env -C /home/coder/my-site ddev describe +``` + +Add `-A` (`--forward-agent`) to forward your computer's SSH agent, so Git and DDEV's containers in the workspace can use the keys on your computer or in a password manager such as 1Password. See [Git and SSH keys](editors-and-ssh.md#git-and-ssh-keys). + +## Use plain `ssh`, `scp` and `rsync` + +```bash +coder config-ssh --yes +``` + +This adds an entry to `~/.ssh/config` for each of your workspaces, so any SSH-based tool can reach them as `.coder`: + +```bash +ssh my-site.coder +scp dump.sql.gz my-site.coder:~/my-site/ +rsync -av ./files/ my-site.coder:~/my-site/web/sites/default/files/ +``` + +Run `coder config-ssh` again when you create a new workspace. Desktop editors that connect over SSH (VS Code Remote - SSH, JetBrains Gateway, Zed and others) use the same entries. See [Editors, SSH and files](editors-and-ssh.md). + +## Forward ports to your computer + +```bash +# local port 3306 → workspace port 32789 +coder port-forward my-site --tcp 3306:32789 + +# same port number on both ends +coder port-forward my-site --tcp 5173 +``` + +The forward stays open until you press Ctrl-C. Use it for desktop database clients or for anything else listening in the workspace; see [Database tools](../freeform/services.md#database-tools). For the web-based alternative, see [Coder's port forwarding docs](https://coder.com/docs/user-guides/workspace-access/port-forwarding). + +## Open apps and editors + +```bash +# desktop VS Code, in the workspace's default directory +coder open vscode my-site + +# desktop VS Code, in a specific directory +coder open vscode my-site /home/coder/my-site + +# an app by its slug; here, the site of the project my-site +coder open app my-site my-site +``` + +`coder open vscode` needs desktop VS Code with the [Coder extension](https://marketplace.visualstudio.com/items?itemName=coder.coder-remote). + +## Troubleshooting connections + +```bash +coder ping my-site # latency; direct or relayed connection +coder speedtest my-site # throughput to the workspace +coder netcheck # network diagnostics +``` + +## Tokens for scripts + +For scripts or CI that need to talk to coder.ddev.com, create a token instead of using your login: + +```bash +coder tokens create --name my-script +coder tokens list +coder tokens remove my-script +``` + +Use it with `CODER_URL=https://coder.ddev.com CODER_SESSION_TOKEN= coder list`. See [Coder's token docs](https://coder.com/docs/admin/users/sessions-tokens). diff --git a/docs/content/workspaces/editors-and-ssh.md b/docs/content/workspaces/editors-and-ssh.md index fd550c9..fb0e868 100644 --- a/docs/content/workspaces/editors-and-ssh.md +++ b/docs/content/workspaces/editors-and-ssh.md @@ -4,27 +4,13 @@ Click **VS Code** on the workspace page. It opens in the directory named after the workspace (`~/`), with a built-in terminal (**Terminal → New Terminal**). Extensions you install from the Extensions view persist across restarts. The extensions installed by default are chosen with the **VS Code Extensions** setting; see [Creating a workspace](../freeform/create.md#vs-code-extensions). -## Set up the Coder CLI +## SSH from your computer -Everything else on this page uses the [Coder CLI](https://coder.com/docs/install/cli) on your computer: - -```bash -coder login https://coder.ddev.com -coder config-ssh --yes -``` - -`coder config-ssh` adds an entry to your `~/.ssh/config` for each of your workspaces, named `.coder`. Run it again after creating a new workspace. - -## SSH - -```bash -coder ssh my-workspace # or: ssh my-workspace.coder -coder ssh -A my-workspace # forward your local SSH agent (see below) -``` +Install the Coder CLI and run `coder config-ssh` once; then `coder ssh my-workspace` or plain `ssh my-workspace.coder` opens a shell. See [Using the Coder CLI](coder-cli.md) for installation, logging in, and the other commands. ## Desktop editors -- **VS Code**: install the [Coder extension](https://marketplace.visualstudio.com/items?itemName=coder.coder-remote), or use the Remote - SSH extension and connect to `my-workspace.coder`. +- **VS Code**: install the [Coder extension](https://marketplace.visualstudio.com/items?itemName=coder.coder-remote) and run `coder open vscode my-workspace`, or use the Remote - SSH extension and connect to `my-workspace.coder`. See [Coder's VS Code docs](https://coder.com/docs/user-guides/workspace-access/vscode). - **JetBrains IDEs** (PhpStorm and others): use [JetBrains Toolbox with the Coder plugin](https://coder.com/docs/user-guides/workspace-access/jetbrains), or JetBrains Gateway over SSH to `my-workspace.coder`. - **Any SSH-capable editor** works the same way, with `my-workspace.coder` as the host. @@ -48,11 +34,7 @@ For small files, you can also drag them into the VS Code for Web file explorer, ## Forwarding ports to your computer -```bash -coder port-forward my-workspace --tcp 3306: -``` - -This makes a port in the workspace available as `localhost` on your computer, for example for a desktop database client. See [Database tools](../freeform/services.md#database-tools). +`coder port-forward my-workspace --tcp :` makes a port in the workspace available on your computer, for example for a desktop database client. See [Using the Coder CLI](coder-cli.md#forward-ports-to-your-computer) and [Database tools](../freeform/services.md#database-tools). ## Git and SSH keys diff --git a/docs/content/workspaces/guide.md b/docs/content/workspaces/guide.md deleted file mode 100644 index 92b9155..0000000 --- a/docs/content/workspaces/guide.md +++ /dev/null @@ -1,1228 +0,0 @@ -# Detailed Workspace Guide - -This guide covers daily workflows, tips, and best practices for working with DDEV in Coder workspaces in more depth than the other pages in this section. - -!!! note "Being reorganized" - Parts of this guide are being moved into the shorter pages in this section: [Workspace lifecycle](lifecycle.md), [Editors, SSH and files](editors-and-ssh.md), [Claude Code](ai-tools.md) and [Troubleshooting](troubleshooting.md). Where they disagree, those pages are current. - -## Table of Contents - -- [Workspace Lifecycle](#workspace-lifecycle) -- [VS Code for Web](#vs-code-for-web) -- [DDEV Workflows](#ddev-workflows) -- [Git Workflows](#git-workflows) -- [Port Forwarding](#port-forwarding) -- [Sharing and Collaboration](#sharing-and-collaboration) -- [Common Tasks](#common-tasks) -- [Tips and Tricks](#tips-and-tricks) -- [Performance Optimization](#performance-optimization) - -## Workspace Lifecycle - -### Understanding Persistence - -Your workspace has two types of storage: - -**Persistent (survives stop/restart):** - -- `/home/coder` directory (all your files) -- Docker volumes (DDEV databases, images, containers) - -**Non-persistent (reset on restart):** - -- Running processes -- Temporary files in `/tmp` -- System packages installed with `apt-get` (unless in Docker image) - -**What this means:** - -- Your code, databases, and DDEV projects are safe when stopping workspace -- You need to restart DDEV projects after workspace restart -- System-level changes (installed packages) are lost unless in Docker image - -### Starting Your Day - -```bash -# 1. Start workspace (if stopped) -coder start my-workspace - -# 2. SSH into workspace (or open VS Code) -coder ssh my-workspace - -# 3. Navigate to project -cd ~/projects/my-site - -# 4. Start DDEV -ddev start - -# 5. Start developing! -``` - -### Running Things Automatically on Workspace Start - -If `~/.coder-startup.sh` exists and is executable, the workspace startup script runs it every time the workspace starts, after Docker and DDEV are ready. No terminal or SSH session has to be open. Use it for anything you would otherwise start by hand after each restart, such as `ddev start` for your projects or a long-running process in `tmux`. - -```bash -cat > ~/.coder-startup.sh <<'SCRIPT' -#!/usr/bin/env bash -ddev start my-site -y -tmux new-session -d -s worker 'my-long-running-command' -SCRIPT -chmod +x ~/.coder-startup.sh -``` - -- It runs detached from the Coder agent, so a slow or never-ending hook doesn't delay the workspace becoming ready. A failing hook doesn't fail workspace startup. -- Output goes to `/tmp/coder-startup-user.log`. -- It runs non-interactively, so `~/.bashrc` is not sourced. `PATH` includes `~/.local/bin`, `~/.npm-global/bin` and Homebrew (`/home/linuxbrew/.linuxbrew/bin`). Export anything else the hook needs inside the script. -- It runs on every start, so make it safe to run more than once, e.g. check whether a process is already running before starting it. - -### Running a Claude Code Self-Hosted Runner - -In a `freeform` workspace, turn on **Run a Claude Code self-hosted runner** when creating or editing it to have it run a Claude Code self-hosted runner. Sessions you start on claude.ai/code in that runner's environment then run in this workspace, with its Docker and DDEV. - -One-time setup: - -1. On claude.ai, create a self-hosted environment and copy its environment secret. -2. In the workspace, save it: - - ```bash - mkdir -p ~/.claude-runner - cat > ~/.claude-runner/environment-secret # paste, then Ctrl-D - chmod 600 ~/.claude-runner/environment-secret - ``` - -3. Restart the workspace. - -On every start the runners run in the tmux session `claude-runner` (`tmux attach -t claude-runner`), one window per runner, logging to `/tmp/claude-runner-.log`. Runner `` clones session repositories under `~/workspace/runner-`. - -- **Use a workspace only for the runner.** The runner deletes and rewrites `~/.gitconfig` and `~/.config/git` before every session, so the template puts the sessions' git identity (`Claude `) and ignore list in `/etc/gitconfig` instead. The option refuses to start the runner when Claude Code remote control is also on. -- **Finding a session's work.** Run `claude-sessions` in the workspace to list live sessions with their checkout, branch and the number of commits not on any remote. -- **Concurrent sessions.** "Claude Code runner: concurrent sessions" (1 to 4) sets how many sessions run at once. The template starts one runner per session, because a runner using Anthropic-managed git takes only one session. The sessions share one Docker daemon and one DDEV install, so the template installs the skill `~/.claude/skills/coder-shared-workspace`, which tells sessions how to stay out of each other's way: separate checkouts, a DDEV global directory per session (`DDEV_XDG_CONFIG_HOME`), no `ddev poweroff`, and a lock around test suites that take over Docker. For full isolation, use several workspaces with one session each instead; the same environment secret works in all of them. - -### Ending Your Day - -```bash -# 1. Commit your changes -git add . -git commit -m "End of day commit" -git push - -# 2. Stop DDEV projects (optional, saves a few seconds on next start) -ddev stop - -# 3. Exit workspace -exit - -# 4. Stop workspace (saves costs) -coder stop my-workspace -``` - -**Note:** Stopping workspace is optional. Some teams leave workspaces running 24/7. - -### Workspace States - -| State | Description | Billing | Data Preserved | -|-------|-------------|---------|----------------| -| **Running** | Active, can SSH and access | Yes | Yes | -| **Stopped** | Powered off, cannot access | No | Yes | -| **Starting** | Booting up, wait a moment | No | Yes | -| **Deleting** | Being deleted | No | No | - -### Managing Multiple Workspaces - -```bash -# List all your workspaces -coder list - -# Create second workspace -coder create --template freeform my-second-workspace --yes - -# Switch between workspaces -coder ssh my-first-workspace -coder ssh my-second-workspace - -# Stop all workspaces -for ws in my-first-workspace my-second-workspace; do coder stop "$ws"; done -``` - -**Use cases for multiple workspaces:** - -- Different projects with different requirements -- Testing configurations without affecting main workspace -- Separate staging and development environments -- Different resource configurations (small vs large projects) - -## VS Code for Web - -### Accessing VS Code - -**From Coder dashboard:** - -1. Find your workspace -2. Click **VS Code** under "Apps" -3. VS Code opens in new tab - -**Direct URL** (bookmark this): - -``` -https://coder.example.com/@me/my-workspace/apps/code -``` - -### Pre-installed Extensions - -All workspaces come with these extensions automatically installed at workspace start: - -| Extension | Purpose | -|-----------|---------| -| **PHP Debug** (`xdebug.php-debug`) | Xdebug step debugging | -| **PHP Intelephense** (`bmewburn.vscode-intelephense-client`) | PHP IntelliSense, go-to-definition, autocomplete | -| **ESLint** (`dbaeumer.vscode-eslint`) | JavaScript/TypeScript linting | -| **Prettier** (`esbenp.prettier-vscode`) | Code formatting | -| **PHPStan** (`sanderronde.phpstan-vscode`) | PHP static analysis | -| **Code Spell Checker** (`streetsidesoftware.code-spell-checker`) | Spell checking in code and comments | -| **Stylelint** (`stylelint.vscode-stylelint`) | CSS/SCSS linting | -| **PHP Sniffer & Beautifier** (`valeryanm.vscode-phpsab`) | PHPCS/PHPCBF integration | -| **DDEV Manager** (`biati.ddev-manager`) | DDEV control panel: start/stop/Xdebug toggle/etc. | - -### Installing Additional Extensions - -Extensions are installed from the **[Open VSX Registry](https://open-vsx.org/)** — the open-source alternative to the Microsoft Marketplace used by VS Code Server and other non-Microsoft VS Code deployments. - -**To install an extension manually:** - -1. Open Extensions panel (`Ctrl+Shift+X`) -2. Search for the extension by name -3. Click Install - -**Important:** Not all extensions on the Microsoft Marketplace are available on Open VSX. Authors must publish to both registries independently. Some notable extensions that are **only** on the Microsoft Marketplace (and therefore unavailable here) include Pylance and GitHub Copilot. - -If an extension you need is missing, check if it exists on [open-vsx.org](https://open-vsx.org) first. If the author hasn't published there, you can request it via the extension's issue tracker. - -### Adding Extensions to All Workspaces - -Admins can pre-install additional extensions for all users by adding extension IDs to the `extensions` list in the template's `vscode-web` module. See the [server setup guide](../self-hosting/server-setup.md) for details. - -### Future IDE Possibilities - -The current setup uses **VS Code for Web** (browser-based VS Code Server). Other IDE options are possible: - -- **VS Code Desktop** — Connect your locally-installed VS Code to the workspace via the Coder CLI (`coder ssh`). Requires the Coder CLI on your machine. -- **JetBrains IDEs** (PhpStorm, GoLand, WebStorm, etc.) — Connect via JetBrains Gateway with the Coder plugin. Full native IDE with remote execution. Currently supported by the Coder platform but not configured in these templates by default. -- **Neovim / terminal editors** — Available in any SSH session via `coder ssh`. - -### Terminal in VS Code - -**Open terminal:** - -- Menu: Terminal → New Terminal -- Keyboard: Ctrl+` (backtick) - -**Multiple terminals:** - -- Click `+` to add terminal -- Split terminal with split button -- Switch between terminals with dropdown - -**Terminal tips:** - -```bash -# Terminal opens in /home/coder by default -# Navigate to project -cd ~/projects/my-site - -# Run DDEV commands -ddev start -ddev describe - -# Run composer/npm through DDEV -ddev composer install -ddev npm run dev -``` - -### File Management - -**Opening projects:** - -1. File → Open Folder -2. Navigate to `~/projects/my-site` -3. Click **OK** - -**Drag and drop:** - -- Drag files from your computer into VS Code to upload -- Works for single files and folders (up to reasonable size) - -**File search:** - -- **Ctrl+P** (Cmd+P): Quick file open -- **Ctrl+Shift+F** (Cmd+Shift+F): Search in files -- **Ctrl+Shift+E** (Cmd+Shift+E): File explorer - -### Git Integration - -**Built-in Git features:** - -- **Source Control** panel (Ctrl+Shift+G) -- Stage changes (click `+` next to file) -- Commit (type message, click ✓) -- Push/pull (click `...` menu) -- View diff (click modified file) - -**GitLens extension features:** - -- Blame annotations (who changed each line) -- Commit history -- Repository explorer -- Compare branches - -### Debugging - -VS Code supports debugging for most languages: - -**PHP (with Xdebug via DDEV):** - -The **DDEV Manager** extension provides a UI panel for toggling Xdebug. Alternatively, use the terminal: - -```bash -ddev xdebug on # Enable Xdebug -ddev xdebug off # Disable when done (improves performance) -``` - -Then in VS Code: - -1. Add a breakpoint (click left of line number — should appear solid red) -2. Press **F5** → select "Listen for Xdebug" -3. Refresh your browser to trigger the breakpoint -4. The bottom bar turns orange when the debug session is active - -**Node.js:** - -```json -// .vscode/launch.json -{ - "type": "node", - "request": "launch", - "name": "Launch Program", - "program": "${workspaceFolder}/server.js" -} -``` - -Press **F5** to start debugging. - -### Extensions for DDEV Projects - -Beyond the pre-installed set, these are useful additions for specific project types (search Open VSX by name): - -**Drupal:** - -- Drupal Smart Snippets - -**WordPress:** - -- WordPress Snippets - -**Laravel:** - -- Laravel Blade Snippets - -**Node.js:** - -- npm Intellisense -- ES7+ React/Redux/React-Native snippets - -### Keyboard Shortcuts - -| Action | macOS | Windows/Linux | -|--------|-------|---------------| -| Command palette | Cmd+Shift+P | Ctrl+Shift+P | -| Quick open file | Cmd+P | Ctrl+P | -| Terminal | Cmd+` | Ctrl+` | -| Find in files | Cmd+Shift+F | Ctrl+Shift+F | -| Save | Cmd+S | Ctrl+S | -| Format document | Shift+Alt+F | Shift+Alt+F | -| Go to definition | F12 | F12 | -| Find references | Shift+F12 | Shift+F12 | - -## DDEV Workflows - -### Project Types - -DDEV supports 20+ project types. Common examples: - -**WordPress:** - -```bash -mkdir ~/projects/my-wordpress -cd ~/projects/my-wordpress -ddev config --project-type=wordpress --docroot=web -ddev start -ddev composer create roots/bedrock -``` - -**Drupal:** - -```bash -mkdir ~/projects/my-drupal -cd ~/projects/my-drupal -ddev config --project-type=drupal --docroot=web -ddev composer create drupal/recommended-project -ddev drush site:install --account-name=admin --account-pass=admin -y -``` - -**Laravel:** - -```bash -mkdir ~/projects/my-laravel -cd ~/projects/my-laravel -ddev config --project-type=laravel --docroot=public -ddev composer create laravel/laravel -ddev exec php artisan key:generate -``` - -**Generic PHP:** - -```bash -mkdir ~/projects/my-php-site -cd ~/projects/my-php-site -ddev config --project-type=php --docroot=web -mkdir web -echo " web/index.php -ddev start -``` - -**Node.js:** - -```bash -mkdir ~/projects/my-node-app -cd ~/projects/my-node-app -ddev config --project-type=php --docroot=. -npm init -y -npm install express -# Create server.js -ddev start -ddev exec node server.js -``` - -### Database Management - -**Import database:** - -```bash -# From SQL file -ddev import-db --file=dump.sql - -# From compressed file -ddev import-db --file=dump.sql.gz - -# From URL -ddev import-db --url=https://example.com/dump.sql.gz -``` - -**Export database:** - -```bash -# Export to file -ddev export-db --file=dump.sql.gz - -# Export to stdout (for piping) -ddev export-db > dump.sql -``` - -**Direct MySQL access:** - -```bash -# MySQL CLI -ddev mysql - -# Run SQL file -ddev mysql < query.sql - -# One-line query -ddev mysql -e "SELECT * FROM users LIMIT 10;" -``` - -**Database GUI** (via browser): - -```bash -# phpMyAdmin (if configured in .ddev/config.yaml) -ddev launch -p - -# Or use MySQL Workbench/TablePlus via SSH tunnel: -coder port-forward my-workspace --tcp 3306:3306 -# Connect to localhost:3306 from your machine -``` - -### Running Commands - -**Execute commands in web container:** - -```bash -# Generic command -ddev exec - -# Examples -ddev exec pwd -ddev exec ls -la -ddev exec which php - -# Run as root -ddev exec sudo -``` - -**SSH into web container:** - -```bash -ddev ssh - -# You're now inside the web container -# Run any command -composer install -npm run build -exit -``` - -**Composer commands:** - -```bash -ddev composer install -ddev composer require vendor/package -ddev composer update -ddev composer dump-autoload -``` - -**npm/yarn commands:** - -```bash -ddev npm install -ddev npm run dev -ddev npm run build -ddev yarn install -ddev yarn build -``` - -### Custom Commands - -**Create custom DDEV commands:** - -```bash -# Create .ddev/commands/web/ directory -mkdir -p .ddev/commands/web - -# Create custom command -cat > .ddev/commands/web/mycommand <<'EOF' -#!/bin/bash -## Description: My custom command -## Usage: mycommand [args] -echo "Running my custom command" -# Your commands here -EOF - -chmod +x .ddev/commands/web/mycommand - -# Use it -ddev mycommand -``` - -### Multiple Projects - -**Running multiple DDEV projects:** - -```bash -# Start all projects -cd ~/projects/project1 && ddev start -cd ~/projects/project2 && ddev start -cd ~/projects/project3 && ddev start - -# List running projects -ddev list - -# Stop specific project -cd ~/projects/project1 -ddev stop - -# Stop all projects -ddev stop --all - -# Power off all (removes containers) -ddev poweroff -``` - -**Port conflicts:** -If you run multiple projects simultaneously, they'll use different ports automatically. Check with: - -```bash -ddev describe -# Shows URLs and ports for each project -``` - -## Git Workflows - -### Initial Configuration - -```bash -# Set your identity (one-time setup) -git config --global user.name "Your Name" -git config --global user.email "your.email@example.com" - -# Set default branch name -git config --global init.defaultBranch main - -# Useful aliases -git config --global alias.st status -git config --global alias.co checkout -git config --global alias.br branch -git config --global alias.ci commit -``` - -### SSH Keys - -**Your SSH key is managed by Coder** and automatically available in workspaces. - -**Get your Coder public key:** - -```bash -# Inside workspace -coder publickey - -# Copy the output (starts with ssh-ed25519 or ssh-rsa) -``` - -**Add key to your Git host:** - -1. **GitHub**: → New SSH key -2. **GitLab**: → Add key -3. **Bitbucket**: → Add key - -**Test SSH:** - -```bash -# Test GitHub -ssh -T git@github.com -# Should say: "Hi username! You've successfully authenticated..." - -# Test GitLab -ssh -T git@gitlab.com -# Should say: "Welcome to GitLab, @username!" -``` - -**How it works:** Coder's GitSSH wrapper uses your Coder-managed SSH key automatically. No need to manage keys inside the workspace. - -### SSH Keys in DDEV Containers - -DDEV's containers can use the same keys, for example for `composer install` with private repositories, `drush` aliases, or `git` in a post-start hook. There's nothing to set up, and `ddev auth ssh` isn't needed: - -```bash -ddev auth ssh # lists the keys the containers can use -ddev exec ssh -T git@github.com # tests them -``` - -The workspace runs an SSH agent relay at `~/.ssh-agent-relay/agent.sock`, and DDEV's `ssh_agent_upstream` points at it. Each time something uses the relay, it connects to the first of these that is available: - -1. **Your own agent, if it's forwarded.** VS Code Desktop forwards your local agent (for example 1Password), and so does `coder ssh -A`. Each new terminal or `coder ssh -A` session makes its agent the one the relay uses. -2. **Your Coder-managed key**, loaded into an agent when the workspace starts. - -The relay picks again on every use, so after VS Code reconnects, DDEV containers that are already running keep working, and they fall back to the Coder key when you disconnect. Terminals use the relay too, so plain `ssh` in the workspace works the same way. - -Notes: - -- The most recent terminal or session with a forwarded agent wins for the whole workspace. If you [share a workspace](#sharing-your-workspace) and a collaborator connects with `coder ssh -A`, your DDEV containers use their keys until you open a new terminal. -- While an agent is forwarded, any container on the DDEV network can ask it to sign. Agents that confirm each use, like 1Password, limit that exposure. -- To use only key files instead, run `ddev config global --ssh-agent-upstream=""` and `ddev auth ssh`. The workspace sets the relay again on its next start. - -### Common Workflows - -**Clone and start working:** - -```bash -cd ~/projects -git clone git@github.com:username/repo.git -cd repo -ddev config --auto # If .ddev/config.yaml exists -ddev start -``` - -**Daily workflow:** - -```bash -# Pull latest changes -git pull - -# Create feature branch -git checkout -b feature/my-feature - -# Make changes -# ... edit files ... - -# Check status -git status - -# Stage changes -git add . - -# Commit -git commit -m "Add my feature" - -# Push -git push origin feature/my-feature -``` - -**Stash changes:** - -```bash -# Stash uncommitted changes -git stash - -# Pull latest -git pull - -# Restore stashed changes -git stash pop -``` - -**Merge conflicts:** - -```bash -# If pull creates conflicts -git pull -# Auto-merging file.php -# CONFLICT (content): Merge conflict in file.php - -# Resolve in VS Code (shows conflict markers) -# Edit file, remove <<<<<<, ======, >>>>>> - -# Stage resolved files -git add file.php - -# Complete merge -git commit -``` - -### Pre-commit Hooks - -```bash -# Install pre-commit hooks (if project uses them) -cd ~/projects/my-site - -# If using PHP CodeSniffer -ddev composer require --dev phpcodesniffer - -# If using ESLint -ddev npm install --save-dev eslint - -# Hooks run automatically on git commit -git commit -m "Test commit" -# Runs linters, formatters, etc. -``` - -## Port Forwarding - -### How Port Forwarding Works - -In Coder, you **don't** access services via direct URLs. Instead: - -1. Service listens on port inside workspace (e.g., DDEV on port 80) -2. Coder proxies port through its server -3. You access via Coder's secure URL - -**Traditional DDEV:** - -``` -https://my-site.ddev.site ← Doesn't work in Coder -``` - -**Coder DDEV:** - -``` -https://ddev-web--workspace-name--owner.coder.example.com/ ← Use DDEV Web app URL -``` - -### Accessing DDEV Projects - -**Via Coder UI (Recommended):** - -1. Go to workspace in Coder dashboard -2. Under **Apps**, click **DDEV Web** -3. Your DDEV project loads in a new tab - -The URL follows the pattern: `https://ddev-web--workspace-name--owner.domain/` - -**Common DDEV ports:** - -- **80**: HTTP web server -- **443**: HTTPS web server -- **8025**: Mailpit web UI (email testing) -- **3306**: MySQL (for external DB tools) - -### Port Forwarding via CLI - -```bash -# Forward port to local machine -coder port-forward my-workspace --tcp 80:80 - -# Now access via: -# http://localhost:80 - -# Forward MySQL for database tools -coder port-forward my-workspace --tcp 3306:3306 - -# Connect MySQL Workbench or TablePlus to: -# Host: localhost, Port: 3306 -``` - -### Custom Services - -If you run custom services, add port forwarding in `template.tf` (ask admin) or use CLI: - -```bash -# Forward custom port (e.g., Node.js on 3000) -coder port-forward my-workspace --tcp 3000:3000 - -# Access via: -# http://localhost:3000 -``` - -## Sharing and Collaboration - -### Sharing Your Workspace - -You can share a running workspace with another user for pair programming or review. The recipient gets a live view of your workspace in their browser — same URL, same running site. - -**Via the web UI:** - -1. Open your workspace in the Coder dashboard -2. Click **Share** in the top-right corner -3. Enter the Coder username to share with and set the permission level -4. Send them the workspace URL - -**Via the CLI:** - -```bash -# Share with another user (specify role: use or admin) -coder sharing add / --user : - -# Example -coder sharing add rfay/issue-3453474 --user stasadev:use - -# List current shares -coder sharing status rfay/issue-3453474 - -# Remove a share -coder sharing remove rfay/issue-3453474 --user stasadev -``` - -See [Coder's shared workspaces docs](https://coder.com/docs/user-guides/shared-workspaces) for full details on permission levels. - -### Admin Access - -Admins can access any workspace on the server — useful for debugging or support. From the Coder dashboard, admins see all workspaces under **Admin settings → Workspaces** and can SSH into or open any of them. - -### Sharing Individual Ports - -You can share a specific port (e.g., a site you're working on) without sharing the full workspace: - -**Via the web UI:** - -1. Open your workspace -2. Click **Open ports** (top right of the agent section) -3. Click the share icon next to the port you want to expose -4. Set visibility: **Owner** (private), **Authenticated** (any logged-in user), or **Public** (anyone with the URL) - -**Via the CLI** (forward a port to your local machine): - -```bash -coder port-forward --tcp 8080:8080 -``` - -Port visibility (public/authenticated/owner) is managed via the Coder web UI dashboard. - -## Common Tasks - -### Importing Existing Projects - -**From Git repository:** - -```bash -cd ~/projects -git clone git@github.com:username/existing-project.git -cd existing-project -ddev config --auto # Auto-detect project type -ddev start -ddev composer install # Or npm install -ddev import-db --file=backup.sql.gz -``` - -**From local machine:** - -```bash -# Option 1: Via VS Code drag-and-drop -# Open VS Code, drag project folder into file explorer - -# Option 2: Via SCP (requires coder config-ssh) -scp -r ./local-project my-workspace.coder:~/projects/ - -# Then in workspace: -cd ~/projects/local-project -ddev config --auto -ddev start -``` - -### Database Snapshots - -```bash -# Create snapshot (backup current state) -ddev snapshot - -# Restore snapshot (revert to last snapshot) -ddev snapshot restore - -# List snapshots -ddev snapshot --list - -# Delete snapshots -ddev snapshot --cleanup -``` - -**Use case:** Before risky database changes: - -```bash -ddev snapshot -# Try risky migration -ddev exec drush updatedb -# If fails, restore: -ddev snapshot restore -``` - -### File Sync and Backup - -**Download files from workspace** (requires `coder config-ssh`): - -```bash -# Via SCP -scp -r my-workspace.coder:~/projects/my-site ./local-backup/ - -# Via VS Code -# Right-click file/folder → Download -``` - -**Upload files to workspace** (requires `coder config-ssh`): - -```bash -# Via SCP -scp -r ./local-files my-workspace.coder:~/projects/my-site/ - -# Via VS Code drag-and-drop -``` - -**Backup entire project:** - -```bash -# Inside workspace -cd ~/projects -tar -czf my-site-backup.tar.gz my-site/ - -# Download (requires coder config-ssh) -exit -scp my-workspace.coder:~/projects/my-site-backup.tar.gz ./ -``` - -### Package Management - -**Composer (PHP):** - -```bash -ddev composer install # Install dependencies -ddev composer require pkg/name # Add package -ddev composer update # Update packages -ddev composer dump-autoload # Rebuild autoloader -``` - -**npm (Node.js):** - -```bash -ddev npm install # Install dependencies -ddev npm install package # Add package -ddev npm update # Update packages -ddev npm run