Merge pull request #406 from nix-community/docs

.github/workflows/run_docs.yml

@@ -31,10 +31,16 @@ jobs:
         with:
           expression: ".#docs"
 
+      - name: Patch 404.html 🩹
+        run: |
+          cp -r ${{ steps.build.outputs.derivation }}/. dist
+          chmod -R +w dist
+          sed -i 's|<base href="/">|<base href="/NixOS-WSL">|' dist/404.html
+
       - name: Upload documentation 📥
         uses: actions/upload-pages-artifact@v3
         with:
-          path: ${{ steps.build.outputs.derivation }}
+          path: dist
 
       - name: Deploy to GitHub Pages 🚀
         if: github.ref == 'refs/heads/main'

docs/book.toml

@@ -7,4 +7,4 @@ title = "NixOS-WSL"
 [output.html]
 additional-css = ["custom.css"]
 edit-url-template = "https://github.com/nix-community/nixos-wsl/tree/main/docs/{path}"
-git-repository-url = "https://github.com/NixOS/nix"
+git-repository-url = "https://github.com/nix-community/nixos-wsl"

docs/src/SUMMARY.md

@@ -7,7 +7,10 @@
 - [Installation](./install.md)
 - [Design](./design.md)
 - [Building](./building.md)
-- [How-To](./howto.md)
+- [How-To](./how-to/README.md)
+  - [Setup VSCode Remote](./how-to/vscode.md)
+  - [Change the username](./how-to/change-username.md)
+  - [Setup Nix Flakes](./how-to/nix-flakes.md)
 - [Troubleshooting](./troubleshooting/README.md)
   - [Recovery Shell](./troubleshooting/recovery-shell.md)
 

docs/src/building.md

@@ -18,7 +18,7 @@ sudo nix run .#nixosConfigurations.your-hostname.config.system.build.tarballBuil
 Without a flakes-enabled Nix, you can build a tarball using:
 
 ```sh
-nix-build -A nixosConfigurations.mysystem.config.system.build.tarballBuilder && sudo ./result/bin/nixos-wsl-tarball-builder
+nix-build -A nixosConfigurations.default.config.system.build.tarballBuilder && sudo ./result/bin/nixos-wsl-tarball-builder
 
 ```
 

docs/src/design.md

@@ -6,5 +6,5 @@ Getting NixOS to run under WSL requires some workarounds:
 - some additional binaries required by WSL's internal tooling are symlinked to FHS paths on activation
 
 Running on older WSL versions also requires a workaround to spawn systemd by hijacking the root shell and
-spawning a container with systemd inside. This method of running things is deprecated and not recommended,
-however still available as `nixos-wsl-legacy.tar.gz` or via `wsl.nativeSystemd = false`.
+spawning a container with systemd inside. This method of running things is deprecated and will be removed
+with the 24.11 release.

docs/src/how-to/README.md

@@ -0,0 +1,3 @@
+# How-To
+
+This section contains guides for some common things you might want to do with your NixOS-WSL installation.

docs/src/how-to/change-username.md

@@ -0,0 +1,19 @@
+# How to change the username
+
+If you want to change the default username to something other than `nixos`, use the `wsl.defaultUser` option.
+When building your own tarball, this should be sufficient. A user with the name specified in that option will be created automatically.
+
+Changing the username on an already installed system is possible as well.
+Follow these instructions to make sure, the change gets applied correctly:
+
+1. Change the `wsl.defaultUser` setting in your configuration to the desired username.
+2. Apply the configuration:\
+   `sudo nixos-rebuild boot`\
+   Do not use `nixos-rebuild switch`! It may lead to the new user account being misconfigured.
+3. Exit the WSL shell and stop your NixOS distro:\
+   `wsl -t NixOS`.
+4. Start a shell inside NixOS and immediately exit it to apply the new generation:\
+   `wsl -d NixOS --user root exit`
+5. Stop the distro again:\
+   `wsl -t NixOS`
+6. Open a WSL shell. Your new username should be applied now!

docs/src/howto.md → docs/src/how-to/nix-flakes.md

@@ -1,9 +1,9 @@
-# How-To
+# How to configure NixOS-WSL with flakes
 
-## How to configure NixOS-WSL with flakes?
 First add a `nixos-wsl` input, then add `nixos-wsl.nixosModules.default` to your nixos configuration.
 
 Below is a minimal `flake.nix` for you to get started:
+
 ```nix
 {
   inputs = {

docs/src/how-to/vscode.md

@@ -0,0 +1,43 @@
+# Setup VSCode Remote
+
+The VSCode Remote server can not be run as-is on NixOS, because it downloads a nodejs binary that
+requires `/lib64/ld-linux-x86-64.so.2` to be present, which isn't the case on NixOS.
+
+There are two options to get the server to run.
+Option 1 is more robust but might impact other programs. Option 2 is a little bit more brittle and sometimes breaks on updates but doesn't influence other programs.
+Both options require `wget` to be installed:
+
+```nix
+environment.systemPackages = [
+    pkgs.wget
+];
+```
+
+## Option 1: Set up nix-ld
+
+[nix-ld](https://github.com/Mic92/nix-ld) is a program that provides `/lib64/ld-linux-x86-64.so.2`,
+allowing foreign binaries to run on NixOS.
+
+Running the VSCode server on NixOS-WSL requires using [nix-ld-rs](https://github.com/nix-community/nix-ld-rs), instead of the regular nix-ld.
+
+To set it up, add the following to your configuration:
+
+```nix
+programs.nix-ld = {
+    enable = true;
+    package = pkgs.nix-ld-rs;
+};
+```
+
+## Option 2: Patch the server
+
+The other option is to replace the nodejs binary that ships with the vscode server with one from the nodejs nixpkgs package.
+[This module will set up everything that is required to get it running](https://github.com/K900/vscode-remote-workaround/blob/main/vscode.nix).  
+If you are [using flakes](./nix-flakes.md), you can add that repo as a flake input and include it from there.
+Otherwise, copy the file to your configuration and add it to your imports.
+
+Add the following to your configuration to enable the module:
+
+```nix
+vscode-remote-workaround.enable = true;
+```

docs/src/troubleshooting/README.md

@@ -1,3 +1,14 @@
 # Troubleshooting
 
-This section contains information on how to debug your NixOS-WSL installation.
+## General Tips
+
+- Try fully restarting WSL by running `wsl --shutdown`. This will close all your terminal windows. Then just restart wsl in your terminal. \
+  Please keep in mind that this will also end any process you might have running in other WSL distros.
+  If that is currently not an option, you may try `wsl -t nixos`, which will just stop the `nixos` distro.
+  (You may need to change that if you imported the distro under some other name). However, some issues will only be resolved after a _full_ restart of WSL.
+- Make sure that you are using the [Microsoft Store version](https://www.microsoft.com/store/productId/9P9TQF7MRM4R) of WSL
+- Update WSL2 to the latest version
+  - To update, run: `wsl --update`
+  - To check which version you currently have installed, run `wsl --version`
+    - The latest version can be found on the [Microsoft/WSL](https://github.com/microsoft/WSL/releases/latest) repo
+    - If this command does not work, you are probably not using the Microsoft Store version of WSL!