by Marcus Zou | 15 November 2025
Intro
- Current version of Alpine Linux is: 3.22.2.
- Typical GUI edition is the Standard or Extended, while the terminal edition can be installed through NetBoot or Virtual or even the WSL edition (that's the Mini RootFS edition).
1A) Install and try with Virtual Machine
Just download the Standard edition and launch the VMware Workstation 17.
- Mount the Alpine Linux ISO image you downloaded to the virtual optical drive.
- Start the VM. It will boot from the ISO and you will be prompted to log in as
rootwith no password. - Run the command
setup-alpine. - Follow the on-screen instructions to configure your system, including setting a hostname, time zone, networking, and, most importantly, selecting the "sys" mode to install to the virtual hard disk.
- Reboot the VM after the installation is complete.
1B) Install and try with WSL
Also very simple.
## Download
wget https://dl-cdn.alpinelinux.org/alpine/latest-stable/releases/x86_64/alpine-minirootfs-3.22.2-x86_64.tar.gz
## Install via WSL
wsl --import alpine E:\vmbox\wsl-arena\alpine .\alpine-minirootfs-3.22.2-x86_64.tar.gz
Then close the terminal and restart it, switch to alpine. obviously the initial terminal is at root user.
Then add a user by:
## Change the password for root
passwd root
## Add a local user
adduser zenusr
## You will set the password for the user
## Add zenusr to sudoer group
NEWUSER='zenusr'
addgroup $NEWUSER wheel
mkdir -p /etc/sudoers.d
echo "$NEWUSER ALL=(ALL) ALL" > /etc/sudoers.d/$NEWUSER && chmod 0440 /etc/sudoers.d/$NEWUSER
## Install basic packages:
apk add sudo nano
## test the local user
su - zenusr
## run the following commands:
sudo apk update
## By default, the openrc is not installed in minirootfs Alpine, Please add such:
apk add openrc
## If no error above, then create /etc/wsl.conf to start up with zenusr, instead of root
nano /etc/wsl.conf
Here is the basic settings of the file:
[boot]
command="openrc default"
[user]
default=zenusr
Then reboot the WSL of alpine.
Please skip the step of 2) Setup Desktop below since we are on WSL env.
1C) Time Changes when dual booting between Linux and Windows
Your time changes when dual-booting because Windows assumes the hardware clock is in local time, while Linux (and most Linux distributions) assumes it's in Coordinated Universal Time (UTC). When you switch operating systems, the other OS reads the time incorrectly from the hardware clock, causing a discrepancy that you see as a time change. The fix is to either tell Linux to use local time or to tell Windows to use UTC.
Fix by changing Linux to use local time (Recommended)
This is generally the easier method and is recommended for most users.
- Open a terminal in Linux.
- Run the following command to set the hardware clock to local time:
timedatectl set-local-rtc 1 --adjust-system-clock. - Verify the change by running
timedatectl. The output should say "RTC in local TZ: yes".
Fix by changing Windows to use UTC
This method makes Windows conform to the international standard that Linux uses by default.
- Open Command Prompt as an administrator. Search for "cmd" in the Start Menu, right-click, and select "Run as administrator".
- Run the following command to modify the Windows registry:
reg add HKLM\SYSTEM\CurrentControlSet\Control\TimeZoneInformation /v RealTimeIsUniversal /t REG_DWORD /d 1 /f. - Restart your computer for the change to take effect.
2) Setup Desktop
Once it boots up, you will be presented with a terminal. Please login as root and then we can install a GUI for it.
- Run the script:
setup-desktop. - When prompted, choose a desktop environment from the list (e.g.,
xfce,plasma,lxqt, orgnome). - The script will install the chosen desktop and necessary packages, and configure the system.
- Then reboot into a graphical login screen:
reboot.
Manual installation will be a little more handy works, please follow these steps for XFCE:
Enable the display manager and:
reboot
Install a display manager, such as ightDM, which integrates well with XFCE:
apk add lightdm-gtk-greeter
Install XFCE and the XFCE terminal:
apk add xfce4
apk add xfce4-terminal
Update the package list:
apk update
Install the base Xorg server and drivers:
setup-xorg-base
apk add xf86-video-vesa
apk add xf86-input-mouse
apk add xf86-input-keyboard
3) Basic Installs
## List installed packages
cat /etc/apk/world
## You probably have login as your user, then switch to `root` to install sudo
su -
## Enter password for root
## Install sudo package
apk add sudo nano
## Add zenusr to sudoer group
NEWUSER='zenusr'
addgroup $NEWUSER wheel
echo "$NEWUSER ALL=(ALL) ALL" > /etc/sudoers.d/$NEWUSER && chmod 0440 /etc/sudoers.d/$NEWUSER
## Check the version of Alpine Linux
cat /etc/os-release ## 3.22.2
## Check the shell
echo $SHELL
# check the IP address
ip a
# Update the system of Rocky/Alma/RHEL
apk update ## refresh the package index only, then do the next
apk upgrade ## This is the real update/upgrade
## Preinstall some apps with root
apk add bash curl git nano openssl rsync tar unzip wget zip ntfs-3g
apk add python3 ## A big chuck of disk space needed
python3 --version ## 3.12.12
which python3 ## /usr/bin/python3
# ffmpeg and mpv, gparted, htop
apk add ffmpeg mpv gparted htop
# Check SSH Service Status
service sshd status
## exit su to local user
exit
## Instll uv - the package manager
sudo curl -LsSf https://astral.sh/uv/install.sh | sh
source $HOME/.local/bin/env ## if sh, bash, zsh
source $HOME/.local/bin.env.fish ## if fish
4) Install/Upgrade Node.js to the version you like
# install progamming bases
su -
apk add nodejs-lts npm
node --version ## 22.16.0
npm --version ## 11.3.0
What if I need to have NodeJS 24?
# necessary dependencies of Node.js 24
apk add curl bash
curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.7/install.sh | bash
bash install.sh
5) Install Java JDK 21
We'll go to OpenJDK21: .
## Install OpenJDK21
sudo apk add openjdk21
## version
java --version
6) Install Docker Engine only
Installation
1- very simple process
sudo apk add docker
Docker as root
2- To start the Docker daemon at boot, see OpenRC.
## No systemd, but openrc in Alpine
sudo rc-update add docker default
sudo service docker start
docker --version ## Docker version 28.3.3
3- Connecting to the Docker daemon through its socket requires you to add yourself to the docker group.
sudo addgroup $USER docker
[!WARNING]
Adding users to this group is equivalent to granting them full root access on the host. See upstream documentation.
Docker rootless (optional)
Docker rootless allows unprivileged users to run the docker daemon and docker containers in user namespaces.
1- This requires the docker-rootless-extras package (available in community):
sudo apk add docker-rootless-extras
2- And enabling cgroups v2: run and edit
sudo nano /etc/rc.conf
and set:
rc_cgroup_mode="unified"
3- Then start the service on boot:
rc-update add cgroups
Additionally, the /etc/subuid and /etc/subgid files need to be set up as explained in the official documentation.
Now docker can be start from an unprivileged user with
dockerd-rootless
Docker Compose
4- Install Docker Compose
docker-cli-compose is in the community repository starting with Alpine Linux 3.15.
sudo apk add docker-cli-compose
docker compose version ## Docker Compose version v2.36.2
[!WARNING]
for WSL2 Alpine only:
There will be quite a few problems: "networking not started", or "network is unreachable".
"network is unreachable" - meaning network is configured and running well, but cannot reach out due to DNS issue: then have to add the following into "/etc/wsl.conf":
[network]
generateResolvConf=false
Also update the DNS record /etc/resolv.conf as below:
nameserver 8.8.8.8
nameserver 1.1.1.1
"network not started" - need to configure the interfaces manually: Then need to configure the interfaces as below
sudo nano /etc/network/interfaces
ensure the following contents in place:
auto lo
iface lo inet loopback
auto eth0
iface eth0 inet dhcp
reboot and it shall be okay.
5- Test out
## check id of the local user: if it has "docker" group
id
## Pull the hello-world app
docker run hello-world
## Remove the test junks
docker ps -a
docker stop $(docker ps -aq)
docker rm $(docker ps -aq)
docker images
docker image rm $(docker images -aq)
6- Optionally Uninstall Docker Engine:
## Uninstall the Docker Engine, CLI, containerd, and Docker Compose packages:
sudo apk del docker docker-cli-compose
7) Open-VM-Tools and shared folder
When installing Alpine Linux on an ESXi or VSphere system you definitely want to enable the hypervisor tools. The good news is that Alpine has this package ready to go! Open-VM-Tools provides the VMWare hypervisor info from Alpine and other Linux.
Changes
Since Alpine 3.12 the open-vm-tools version 11 was split into 5 packages:
guestinfo is required for IP Discovery to work.
deploypk provides support for Guest OS Customization
Installation
Enable the community repository by editing /etc/apk/repositories and uncommenting the community repository, and then run apk update.
## Switch to root mode or use `sudo` mode
su -
nano /etc/apk/repositories
## Uncomment the line of community repository
apk update
Then install open-vm-tools:
## Still in root mode
apk add open-vm-tools open-vm-tools-guestinfo open-vm-tools-deploypkg open-vm-tools-hgfs
Start once
rc-service open-vm-tools start
Add to boot
rc-update add open-vm-tools boot
Verify
It's working!
Shared folders from the host to the guest on Alpine Linux 3.22
1- Install packages prior to take-off:
sudo apk add ntfs-3g fuse fuse-dev
In order to confirm if your local selected folder was really shared, run the below command and check if your folder will be listed.
## It shall read out something like: `shared` (the shared folder name on the Host).
vmware-hgfsclient
2- Create mount folder of /mnt/hgfs and test it out:
sudo mkdir -p /mnt/hgfs
# probing the folder manually
sudo modprobe fuse
sudo vmhgfs-fuse -o allow_other .host:/ /mnt/hgfs
## There must be some exported shared folders, assuming you have shared folder on the host
ls /mnt/hgfs
3- Ensure loading fuse module at boot:
Method 1 (Recommended per AI agents): Using modprobe.d configuration file: To make sure the fuse module is loaded automatically on subsequent boots, add it to /etc/modprobe.d/fuse.conf. If the file doesn't exist, create it:
sudo touch /etc/modprobe.d/fuse.conf
echo "fuse" | sudo tee -a /etc/modprobe.d/fuse.conf
## fuse
Note: This method of module loading doesn't work. It's a AI delusion, lol.
Method 2: using rc.local: basically create a script to be run at boot. So edit or create /etc/local.d/fuse.start:
sudo nano /etc/local.d/fuse.start
Add the following content:
#!/bin/sh
modprobe fuse
vmhgfs-fuse -o allow_other .host:/ /mnt/hgfs
Ensure the script has execute permissions:
sudo chmod +x /etc/local.d/fuse.start
Enable the local OpenRC service:
sudo rc-update add local default
Verify and Reboot:
sudo rc-service local restart -v ## -v: verbose mode
sudo reboot
Note: This method works wells.
4- Enforce auto-mounting with /etc/fstab: that's for loading up the Shared folder at start-up of the computer:
sudo nano /etc/fstab
Add the below into the last row of the file:
vmhgfs-fuse /mnt/hgfs fuse defaults,allow_other,_netdev 0 0
and then reboot the Alpine Linux machine.
8) Install Chrome browser
Actually we can install that directly:
sudo apk update && sudo apk add chromium
9) Install Code Editors
Installing VS Code cannot be done directly, You have to go through Docker. but there are a few options out there:
| Editor | Difficulty | Best For |
|---|---|---|
| 🟢 Nano | Easy | Beginners |
| 🔵 Vim | Hard | Advanced users |
| 🟡 Emacs | Medium | Power users |
| 🟠 Micro | Easy | Modern feel |
Here is the installing for those:
sudo apk update
sudo apk add nano vim emacs micro
Quick guide to use them:
1- nano - Very Easy Editor
nano myfile.txt
Nano shortcuts: ⌨️
Ctrl + O= Save fileCtrl + X= Exit nanoCtrl + K= Cut line
2- Vim - Powerful Editor
vim myfile.txt
Vim basic commands: ⌨️
- Press
i= Start typing - Press
Esc= Stop typing - Type
:w= Save file - Type
:q= Exit vim
3- Emacs - Feature-Rich Editor
emacs myfile.txt
Emacs shortcuts: ⌨️
Ctrl + S= Save fileCtrl + X, Ctrl + C= Exit emacs
4- Micro - Modern and Simple
micro myfile.txt
Micro shortcuts: ⌨️
Ctrl + S= Save fileCtrl + Q= Exit micro
