Refresh deploy/ and bin/ from the boilerplate at 09e144d (the release split between the distro and Windows, wsl-setup, the server config, USER 1000, python:3.15-slim) with roledesk's facts put back: no frontend stage, desk, plugins and seed copied, the extras passkeys, embeddings and llm, roles as the table the backup and the importer require, bin/pull.sh and bin/worker.sh with their profile commands, and Install Server.md and Install WSL.md as copies in place of the five old deployment docs
Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
This commit is contained in:
1 parent
83e965dfeb
commit
a1f281a23a
40 files changed
+2226
-1287
No files matched your search
@@ -0,0 +1,408 @@
|
||||
> A copy of the boilerplate's `documentation/Install WSL.md` at commit 09e144d, unedited below this line; the fix lands upstream first.
|
||||
|
||||
# Abstract
|
||||
|
||||
The sandbox is a WSL distro. Claude Code runs inside it from the desktop app with all permissions, because the distro cannot reach anything on Windows. Interops is turned off, no drives are mounted, and to keep it this way admin permissions are not granted.
|
||||
|
||||
Root is reached only from Windows, with `wsl -d claudebox -u root`. That is how you install and update packages later.
|
||||
|
||||
The repos live inside the distro in `/home/claude/cboxcode`. [Working from Windows](#working-from-windows) covers working with them from Windows.
|
||||
|
||||
# Install
|
||||
|
||||
## 1. Check that WSL 2 runs
|
||||
|
||||
```
|
||||
PS> wsl --status
|
||||
```
|
||||
|
||||
It should say `Default Version: 2` and nothing about virtualisation.
|
||||
|
||||
If it says virtualisation is not enabled, run `wsl.exe --install --no-distribution` once in an admin PowerShell and reboot. If it still complains, switch on Intel VT-x or AMD-V in the BIOS. This is the only step that can need admin rights.
|
||||
|
||||
If a `claudebox` from an earlier attempt exists, `wsl -l -v` lists it. `wsl --unregister claudebox` deletes it with everything inside.
|
||||
|
||||
## 2. Install Ubuntu as `claudebox`
|
||||
|
||||
```
|
||||
PS> wsl --install Ubuntu-24.04 --name claudebox --no-launch --web-download
|
||||
```
|
||||
|
||||
- `--name claudebox` names the distro, so it does not collide with an ordinary Ubuntu.
|
||||
- `--no-launch` skips Ubuntu's first-start wizard, which would create a user with sudo. We create our own user in step 5.
|
||||
- `--web-download` downloads it directly instead of through the Microsoft Store.
|
||||
|
||||
## 3. Open a root shell
|
||||
|
||||
```
|
||||
PS> wsl -d claudebox -u root
|
||||
```
|
||||
|
||||
The prompt changes to something like `root@PC:/mnt/c/...#`. You are now inside Linux as root. `C:` is still visible at this point; step 7 takes it away.
|
||||
|
||||
## 4. Update and install packages
|
||||
|
||||
```
|
||||
# apt update
|
||||
# apt upgrade -y
|
||||
# apt install -y build-essential git curl ripgrep sqlite3 jq unzip
|
||||
```
|
||||
|
||||
`apt update` fetches the package lists, `apt upgrade` installs updates, and `apt install` adds the tools: compilers for Python packages that build from source, git, curl, ripgrep for Claude's searches, sqlite3 to look into the databases, jq for JSON, unzip.
|
||||
|
||||
## 5. Create the user `claude`, without sudo
|
||||
|
||||
```
|
||||
# useradd --create-home --shell /bin/bash claude
|
||||
# groups claude
|
||||
```
|
||||
|
||||
`useradd` creates the user with a home directory and bash. It gets no password and no groups. `groups claude` must print only `claude : claude`. If `sudo` appears there, the user can become root, and `gpasswd -d claude sudo` removes it.
|
||||
|
||||
```
|
||||
# passwd -l root
|
||||
```
|
||||
|
||||
This locks root's password, so `su` cannot become root from inside either. Ubuntu ships it locked, so this only makes sure.
|
||||
|
||||
## 6. Install uv and Claude Code as `claude`
|
||||
|
||||
Switch to the user. Root can do that without a password:
|
||||
|
||||
```
|
||||
# su - claude
|
||||
```
|
||||
|
||||
The prompt ends in `$` now. Install the two tools into `~/.local/bin`, which belongs to `claude`, so they update without root:
|
||||
|
||||
```
|
||||
$ curl -LsSf https://astral.sh/uv/install.sh | sh
|
||||
$ curl -fsSL https://claude.ai/install.sh | bash
|
||||
$ echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.bashrc
|
||||
```
|
||||
|
||||
The third line puts `~/.local/bin` on the path for every new shell.
|
||||
|
||||
Set the git identity, with your own name and email, and create the folder for the repos:
|
||||
|
||||
```
|
||||
$ git config --global user.name "Your Name"
|
||||
$ git config --global user.email "you@example.com"
|
||||
$ git config --global init.defaultBranch main
|
||||
$ mkdir ~/cboxcode
|
||||
```
|
||||
|
||||
Back to root:
|
||||
|
||||
```
|
||||
$ exit
|
||||
```
|
||||
|
||||
## 7. Cut the distro off from Windows
|
||||
|
||||
`/etc/wsl.conf` is the file WSL reads when the distro starts. Open it in the editor:
|
||||
|
||||
```
|
||||
# nano /etc/wsl.conf
|
||||
```
|
||||
|
||||
Delete what is there and type this:
|
||||
|
||||
```
|
||||
[boot]
|
||||
systemd=true
|
||||
|
||||
[user]
|
||||
default=claude
|
||||
|
||||
[automount]
|
||||
enabled=false
|
||||
mountFsTab=false
|
||||
|
||||
[interop]
|
||||
enabled=false
|
||||
appendWindowsPath=false
|
||||
```
|
||||
|
||||
- `[user] default=claude` makes every normal start log in as `claude`, not root.
|
||||
- `[automount] enabled=false` stops WSL from mounting `C:` and the other drives under `/mnt`. `mountFsTab=false` also ignores `/etc/fstab`, so no other way of mounting them applies.
|
||||
- `[interop] enabled=false` stops Linux from starting Windows programs. That includes `wsl.exe`, which would otherwise be a way back to root. `appendWindowsPath=false` keeps the Windows folders off the Linux path.
|
||||
- `[boot] systemd=true` is Ubuntu's default and stays.
|
||||
|
||||
Save with `Ctrl+O` then `Enter`, quit with `Ctrl+X`.
|
||||
|
||||
The first start in step 3 left an empty folder per Windows drive under `/mnt`. Nothing will be mounted on them any more, so remove them to avoid confusion. `rmdir` only removes empty folders, so it cannot delete anything:
|
||||
|
||||
```
|
||||
# rmdir /mnt/c /mnt/d
|
||||
```
|
||||
|
||||
Name every drive letter that `ls /mnt` shows. `wsl` and `wslg` belong to WSL and stay. Leave the distro:
|
||||
|
||||
```
|
||||
# exit
|
||||
```
|
||||
|
||||
WSL only reads the file on a fresh start, so stop the distro:
|
||||
|
||||
```
|
||||
PS> wsl --terminate claudebox
|
||||
```
|
||||
|
||||
## 8. Check the isolation
|
||||
|
||||
Start it the normal way, which now logs in as `claude`:
|
||||
|
||||
```
|
||||
PS> wsl -d claudebox
|
||||
```
|
||||
|
||||
Each check and what it must answer:
|
||||
|
||||
```
|
||||
$ whoami
|
||||
claude
|
||||
$ groups
|
||||
claude
|
||||
$ passwd -S claude
|
||||
claude L ...
|
||||
$ sudo -n true
|
||||
sudo: a password is required
|
||||
$ ls /mnt
|
||||
wsl wslg
|
||||
$ uv --version
|
||||
$ claude --version
|
||||
```
|
||||
|
||||
- `groups` showing only `claude` means no admin group, so sudo refuses even with a password.
|
||||
- `L` in `passwd -S` means the password is locked: no password exists, so nothing can be typed at a sudo or su prompt that works. A plain `sudo` still asks for one, and any answer fails.
|
||||
- `ls /mnt` showing no drive letters means no Windows drive is there. `mount | grep -i drvfs` printing nothing confirms it.
|
||||
- The last two print version numbers.
|
||||
|
||||
The real test that Windows programs cannot start needs one. In a second PowerShell window, copy a harmless one in from Windows, run it inside, and delete it again:
|
||||
|
||||
```
|
||||
PS> Copy-Item C:\Windows\System32\whoami.exe \\wsl.localhost\claudebox\tmp\
|
||||
PS> wsl -d claudebox -- /tmp/whoami.exe
|
||||
PS> Remove-Item \\wsl.localhost\claudebox\tmp\whoami.exe
|
||||
```
|
||||
|
||||
With interop off it prints no Windows user name, only a WSL error after a few seconds. If it prints your Windows name, step 7 did not take.
|
||||
|
||||
If any check answers differently, the step it belongs to did not take: 5 for `groups` and `passwd`, 7 for `/mnt` and `whoami.exe`.
|
||||
|
||||
```
|
||||
$ exit
|
||||
```
|
||||
|
||||
## PowerShell 7
|
||||
|
||||
Our scripts are running on powershell 7, which needs to be installed.
|
||||
|
||||
Then, set it to the default profile in the terminal app.
|
||||
|
||||
```
|
||||
PS> winget install Microsoft.PowerShell
|
||||
```
|
||||
|
||||
## The execution policy
|
||||
|
||||
Running commands in the WSL need extra permissions:
|
||||
|
||||
```
|
||||
PS> pwsh -ExecutionPolicy Bypass -File <command>
|
||||
```
|
||||
|
||||
This is one reason why we add all important commands into the profile
|
||||
|
||||
|
||||
|
||||
## PyCharm
|
||||
|
||||
### Remote execution agent failure
|
||||
|
||||
PyCharm on Windows is not able to read folders on the cut-off WSL. Its bundled plugin Remote Execution Agent copies a helper called IJent into the distro from `/mnt/c/Program Files/JetBrains/...` and reads files and runs Git through it. With the drives unmounted the copy fails: opening a file reports "unable to locate", Git reports `execvpe(.../ttyfix) failed`, and `idea.log` shows `cp: cannot stat '/mnt/c/...ijent...'`.
|
||||
|
||||
So you need to disable the plugin: Settings > Plugins > Installed, search for `Remote Execution Agent`, untick it, restart PyCharm.
|
||||
|
||||
### Git
|
||||
|
||||
Set Settings > Version Control > Git > Path to Git executable to `C:\Program Files\Git\cmd\git.exe`, so it uses Windows Git instead of trying to start the distro's.
|
||||
|
||||
### Run configurations
|
||||
|
||||
We currently don't use them.
|
||||
|
||||
## Maintenance
|
||||
|
||||
### Update
|
||||
|
||||
Packages, as root from Windows:
|
||||
|
||||
```
|
||||
PS> wsl -d claudebox -u root -- apt update
|
||||
PS> wsl -d claudebox -u root -- apt upgrade -y
|
||||
```
|
||||
|
||||
Claude Code updates itself. uv updates with the line below. The full path is needed because a command passed from PowerShell does not load `~/.bashrc`:
|
||||
|
||||
```
|
||||
PS> wsl -d claudebox -- /home/claude/.local/bin/uv self update
|
||||
```
|
||||
|
||||
### Remove WSL
|
||||
|
||||
Remove the distro with all repos in it, after pushing what matters:
|
||||
|
||||
```
|
||||
PS> wsl --unregister claudebox
|
||||
```
|
||||
|
||||
# Getting it ready for use
|
||||
|
||||
## Git
|
||||
|
||||
Tell Windows Git to trust that folder, since its files belong to the Linux user:
|
||||
|
||||
```
|
||||
PS> git config --global --add safe.directory '%(prefix)///wsl.localhost/claudebox/home/claude/cboxcode/news'
|
||||
```
|
||||
|
||||
`git config core.autocrlf false` stops Git from converting line endings in this repo. `git checkout -- .` rewrites the files Windows Git checked out with Windows line endings, so Linux Git does not report every line as changed.
|
||||
|
||||
## Working from Windows
|
||||
|
||||
The only direction that works is Windows into WSL: Windows reads and writes the checkout through `\\wsl.localhost\<distro>\...` and starts processes with `wsl.exe`. The distro never reaches back. Editing and the Git UI happen on Windows; the agents, the tests, `serve`, the jobs, `uv sync`, release step 1 and `db.sh` run in the distro, typed from Windows through the profile commands below; release steps 2 and 3 run on Windows with `wslc`, since the distro must not hold a container socket.
|
||||
|
||||
A `.venv` belongs to one OS: `bin/python` on Linux, `Scripts\python.exe` on Windows. The `.venv` in the checkout is the distro's. A Windows `uv sync` or `uv run` in that folder would replace it with a Windows one, and the distro's next `uv run` would swap it back, so run `uv` in the distro (`<folder>-sh` opens a shell there). A Windows interpreter for an editor's code insight belongs outside the checkout.
|
||||
|
||||
Run the app in the distro, not from Windows. Only one side may open a SQLite file at a time, since locking through the share is unreliable, and file change notifications through the share are unreliable too, so `--reload` started from Windows can miss edits.
|
||||
|
||||
## WSL Containers for the image
|
||||
|
||||
We don't need Docker Desktop but build images directly on WSL with `wslc`. It needs WSL 2.9.3 or later:
|
||||
|
||||
```
|
||||
PS> wsl --update
|
||||
PS> wsl --version
|
||||
PS> wslc version
|
||||
```
|
||||
|
||||
Log it in to the registry once, with a token that has package-write access, typed at its password prompt:
|
||||
|
||||
```
|
||||
PS> wslc login git.rittershofer.org -u wolf
|
||||
```
|
||||
|
||||
## Env files
|
||||
|
||||
Once per checkout, including every new repo, and again when `DISTRO` or `CHECKOUT` changes:
|
||||
|
||||
1. Copy `deploy/release.env.example` to `deploy/release.env` in the checkout (`cp` in the distro, or Explorer) and fill in `DISTRO` (`claudebox`), `CHECKOUT` (the path in the distro, `/home/claude/cboxcode/news`) and `IMAGE`. The file is gitignored.
|
||||
|
||||
## PS Profile commands
|
||||
|
||||
We want a simple way to run and deploy the app, `cd` into the repo. So we have script adding the relevant commands to the PS profile:
|
||||
|
||||
```
|
||||
PS> pwsh -ExecutionPolicy Bypass -File \\wsl.localhost\claudebox\home\claude\cboxcode\news\deploy\wsl-setup.ps1
|
||||
```
|
||||
|
||||
It creates commands into the profie
|
||||
|
||||
The prefix is the checkout folder's name, `news-` for `news` and `boilerplate-` for `boilerplate`; `-Name` on the `.ps1` sets another. The setup writes one block between `# >>> news (deploy/wsl-setup.ps1) >>>` and `# <<< news (deploy/wsl-setup.ps1) <<<` into `$PROFILE` and replaces it when run again. Blocks written by older versions of the setup, `newsdesk (deploy/wsl-setup.ps1)` and `wsl shared (deploy/wsl-setup.ps1)`, call scripts that no longer exist; delete them with `notepad $PROFILE`.
|
||||
|
||||
| Command | Runs | Does |
|
||||
|---|---|---|
|
||||
| `news-cd` | `Set-Location` | PowerShell into the checkout's folder |
|
||||
| `news-sh` | `wsl.exe` | a shell in claudebox, in the checkout |
|
||||
| `news-backend [-v]` | `bin/backend.sh` in claudebox | `uv run app serve` on :8787, until Ctrl-C |
|
||||
| `news-frontend` | `bin/frontend.sh` in claudebox | Vite with hot reload on :5173, until Ctrl-C |
|
||||
| `news-check` | `bin/check.sh` in claudebox | the gate on the working tree, without promoting |
|
||||
| `news-1test [--push-branch] [--no-tests]` | `deploy/1-test-and-promote.sh` in claudebox | test local main, fast-forward `production`, export it |
|
||||
| `news-2build` | `deploy\2-build-image.ps1` on Windows | build the exported tree with `wslc`, tags `<sha>` and `latest` |
|
||||
| `news-3push` | `deploy\3-push-image.ps1` on Windows | push both tags with `wslc` |
|
||||
| `news-0release [--push-branch] [--no-tests]` | the three above | `1test`, `2build`, `3push`, stopping at the first that fails |
|
||||
| `<folder>-db pull\|push` | `deploy/db.sh` in claudebox | only where `deploy/db.sh` exists, as in the boilerplate |
|
||||
|
||||
If the setup does not run, paste the block by hand. `New-Item -Force $PROFILE` creates the file if `Test-Path $PROFILE` says it is missing; `notepad $PROFILE` opens it. For `news`, with `DISTRO=claudebox` and `CHECKOUT=/home/claude/cboxcode/news`, the setup writes exactly this:
|
||||
|
||||
```powershell
|
||||
# >>> news (deploy/wsl-setup.ps1) >>>
|
||||
function news-cd { Set-Location '\\wsl.localhost\claudebox\home\claude\cboxcode\news' }
|
||||
function news-sh { wsl.exe -d claudebox --cd /home/claude/cboxcode/news }
|
||||
function news-backend { wsl.exe -d claudebox --cd /home/claude/cboxcode/news -- bash bin/backend.sh @args }
|
||||
function news-frontend { wsl.exe -d claudebox --cd /home/claude/cboxcode/news -- bash bin/frontend.sh @args }
|
||||
function news-check { wsl.exe -d claudebox --cd /home/claude/cboxcode/news -- bash bin/check.sh @args }
|
||||
function news-1test { wsl.exe -d claudebox --cd /home/claude/cboxcode/news -- bash deploy/1-test-and-promote.sh @args }
|
||||
function news-2build { & (Get-Process -Id $PID).Path -NoProfile -ExecutionPolicy Bypass -File '\\wsl.localhost\claudebox\home\claude\cboxcode\news\deploy\2-build-image.ps1' }
|
||||
function news-3push { & (Get-Process -Id $PID).Path -NoProfile -ExecutionPolicy Bypass -File '\\wsl.localhost\claudebox\home\claude\cboxcode\news\deploy\3-push-image.ps1' }
|
||||
function news-0release { news-1test @args; if ($LASTEXITCODE -ne 0) { return }; news-2build; if ($LASTEXITCODE -ne 0) { return }; news-3push }
|
||||
# <<< news (deploy/wsl-setup.ps1) <<<
|
||||
```
|
||||
|
||||
For another checkout, replace `news` and the path.
|
||||
|
||||
### When a command fails
|
||||
|
||||
- `wsl -l -v` lists the distros. `DISTRO` must be one of the names exactly.
|
||||
- `Test-Path \\wsl.localhost\claudebox\home\claude\cboxcode\news` must say `True`. `\\wsl$\claudebox\...` is the older spelling of the same share; if only that one answers, use it in the block.
|
||||
- `$PROFILE` prints the profile file this PowerShell loads, and `Get-Command news-*` lists the commands it defined. Commands missing in one PowerShell and present in another means the setup ran in the other one.
|
||||
- `Get-ExecutionPolicy -List` shows the policy per scope. `Restricted` or `AllSigned` where it applies means the profile does not load; a `MachinePolicy` or `UserPolicy` entry is group policy and overrides `CurrentUser`.
|
||||
- `wslc version` failing means WSL is older than 2.9.3: `wsl --update`.
|
||||
- `news-2build` saying there is no `production` file means step 1 has not exported yet: run `news-1test`.
|
||||
- If `wslc build` refuses the `\\wsl.localhost` folder as its context, which Microsoft's documentation neither promises nor rules out, copy the tree to Windows and build there: `Copy-Item -Recurse \\wsl.localhost\claudebox\home\claude\cboxcode\release\news\<sha> $env:TEMP\release-<sha>`, then the `wslc build` line of `2-build-image.ps1` with that folder.
|
||||
|
||||
# Kill and restart
|
||||
|
||||
Run everything in an **admin PowerShell** on Windows.
|
||||
|
||||
### Normal shutdown
|
||||
|
||||
`wsl --shutdown`
|
||||
|
||||
### Killing it
|
||||
|
||||
If normal shutdown hangs:
|
||||
|
||||
```
|
||||
taskkill /f /im wsl.exe
|
||||
taskkill /f /im wslhost.exe
|
||||
taskkill /f /im wslrelay.exe
|
||||
```
|
||||
|
||||
### Check the service
|
||||
|
||||
`sc queryex WslService`
|
||||
|
||||
If it says `STOP_PENDING` or `START_PENDING`, take the PID from the output and run `taskkill /PID <PID> /F`.
|
||||
|
||||
If it says `STOPPED`, start it with `sc start WslService`, then run `wsl`.
|
||||
|
||||
### **Kill a lingering VM**
|
||||
|
||||
IF it still does not work check the VM
|
||||
|
||||
```
|
||||
hcsdiag list
|
||||
hcsdiag kill <ID>
|
||||
```
|
||||
|
||||
If the old WSL VM is still listed, kill it with the ID shown. This was reported as the only fix short of a reboot in a complete-freeze case.
|
||||
|
||||
### **Restart the Hyper-V Host Compute Service**
|
||||
|
||||
```
|
||||
Restart-Service vmcompute
|
||||
```
|
||||
|
||||
A wedged vmcompute service is a common reason WSL stops working after it ran fine earlier in the same Windows session.
|
||||
|
||||
If it still hangs after all four, a reboot is the reliable fix.
|
||||
|
||||
Once it’s back up, running `wsl --update` is worth doing, since hangs like this are often fixed in newer versions.
|
||||
|
||||
# Pitfalls
|
||||
|
||||
- **Only open the distro from a normal PowerShell.** Opened from an admin one, WSL mounts the Windows drives despite `automount` being off ([microsoft/WSL#12443](https://github.com/microsoft/WSL/issues/12443)). `wsl --terminate claudebox` and a normal shell undo it.
|
||||
- **Changes to `/etc/wsl.conf` apply only after `wsl --terminate claudebox`.**
|
||||
Reference in new issue
Block a user