dotfiles-wsl2/README.md

WSL2 Arch Linux Development Environment

My minimal setup for Arch Linux development environment optimized for WSL2, designed for daily workflow. This setup combines essential tools and configurations to create a powerful yet minimalist development workspace.

Mirror on my Git

Features

Core Components

• OS: Arch Linux on WSL2
• Terminal: WezTerm
• Shell: Fish
• Multiplexer: Tmux
• Prompt: Starship

Additional Tools

• Package Manager: paru
• Editor: Neovim
• System Info: fastfetch
• File Listing: exa
• System Monitor: htop

Installation

Software Requirements

• Windows 10 version 2004 (build 19041) or higher / Windows 11
• Windows Subsystem for Linux (WSL2) component enabled
• Virtual Machine Platform feature enabled
• Windows Terminal (optional but recommended for initial setup)
• Git for Windows

Note: WSL2 is configured to use up to 16GB of RAM in this setup (can be adjusted in .wslconfig)

Note: Throughout this guide, we'll use:

• Distribution name: Arch (if you choose a different name, update it in WezTerm config under default_domain = "WSL:Arch")
• Username: user (if you want a different username, update relevant configs like ./wsl/etc/wsl.conf)

1. Windows Host Setup

# Install WezTerm (or download directly: https://wezterm.org/install/windows.html)
winget install wezterm

# Clone repository
git clone https://github.com/xzeldon/dotfiles-wsl2
cd dotfiles-wsl2

# Copy Windows configs (THIS OVERWRITE IF FILES EXISTS!)
Copy-Item -Path ".\windows\*" -Destination $HOME -Force -Recurse

2. Arch Linux WSL Setup

1. Download the latest Arch Linux WSL image (you need .wsl file)

2. Import to WSL2:

wsl --import NAME INSTALL_PATH IMAGE_PATH

Where:

• NAME: Your preferred WSL distribution name (e.g., "Arch")
• INSTALL_PATH: Where to store the WSL2 virtual disk (e.g., "D:\wsl\Arch")
• IMAGE_PATH: Path to the downloaded Arch Linux image (e.g., "D:\Downloads\archlinux-latest.wsl")

Example:

wsl --import Arch D:\wsl\Arch "D:\Downloads\archlinux-latest.wsl"

3. System Configuration

Initial Setup

# Run first-time setup
/usr/lib/wsl/first-setup.sh

# Update system
pacman -Syu

# Install dependencies
pacman -S sudo git vim neovim openssh wget binutils less debugedit fakeroot \
          fastfetch starship exa fish tmux htop python base-devel go

User Configuration

# Set root user password
passwd

# Configure locale
echo "en_US.UTF-8 UTF-8" >> /etc/locale.gen
locale-gen

# Create user
useradd -m user
# Set user password
passwd user

# Configure sudo
echo "user ALL=(ALL) ALL" >> /etc/sudoers.d/user

# Configure WSL default user
# 1. Copy WSL configuration file from host to guest
# (From Windows PowerShell, assuming you're in the repo directory and Arch is a WSL distribution name, from 2.2)
cp .\wsl\etc\wsl.conf \\wsl.localhost\Arch\etc\wsl.conf

# 2. Restart WSL for changes to take effect
# (Run this in PowerShell on Windows)
wsl --shutdown

Aur helper and ssh bridge

# Install AUR helper
git clone https://aur.archlinux.org/paru-bin.git
cd paru-bin
makepkg -si

# Install agent for ssh bridge (see: https://wiki.archlinux.org/title/Install_Arch_Linux_on_WSL#Bridge_the_ssh-agent_service_from_Windows)
paru -S wsl2-ssh-agent

# Create .ssh directory (this not exists by default, but required for wsl2-ssh-agent)
mkdir ~/.ssh

Copy Configuration Files

You need to copy all configuration files from the repository to your WSL environment:

From powershell:

# Assuming you're in the repo directory, `Arch` is a WSL distribution name (from 2.2) and arch username is `user`
Copy-Item -Path .\wsl\* -Destination \\wsl.localhost\Arch\home\user -Recurse -Force -Exclude "etc"

Tmux configuration

# Install Tmux Plugin Manager
git clone https://github.com/tmux-plugins/tpm ~/.tmux/plugins/tpm

# Start tmux and install plugins
tmux # Then press Ctrl+Space, Shift+I

Tip: edit tmux.conf to change disk in status bar

Configuration

File Structure

├── windows/                # Windows-side configs
│   ├── .wezterm.lua       # WezTerm configuration
│   └── .wslconfig         # WSL global settings
└── wsl/                   # Linux-side configs
    ├── .config/
    │   ├── fish/         # Fish shell configuration
    │   ├── tmux/         # Tmux configuration
    │   └── starship.toml # Prompt configuration
    └── etc/
        └── wsl.conf      # WSL distribution settings

Key Bindings

Tmux

Binding	Action
Ctrl + Space	Tmux prefix
Prefix + I	Install Tmux plugins
Prefix + c	Create new window
Prefix + %	Create new window vertically
Prefix + "	Create new window horizontally
Prefix + x	Kill current pane

WezTerm

Binding	Action
Ctrl + Shift + Q	Close WezTerm window
Ctrl + Shift + M	Minimize WezTerm window

Tip: use fish_add_path /some/path/bin to add directories to $PATH. See: https://fishshell.com/docs/current/cmds/fish_add_path.html

License