AlmaLinux development, one playbook away on WSL2
Dotkernel's local environment runs AlmaLinux 10 - inside WSL 2 on Windows, or on bare
metal with no WSL at all. One Ansible playbook installs PHP, Apache, MariaDB, Composer, Node.js and
phpMyAdmin, and every project gets its own *.localhost virtualhost without touching a hosts file.
The same OS family your servers run
AlmaLinux is a RHEL-compatible distribution, so the packages, package manager and service
conventions you use locally - dnf, systemd and the rest - are the ones you will see again in
staging and production. WSL 2 puts that distro on a Windows machine without a second computer or a
Windows-native rebuild of every tool.
Everything here also runs the same way without WSL, directly on a bare AlmaLinux 10 host - the Ansible playbooks do not know or care which one they are provisioning.
RHEL-compatible, matches production
One playbook, the whole stack
Virtualhosts without touching hosts file
Aliases for switching PHP & Node versions
Three steps to a running shell
Each step runs in a different place - Windows Terminal for the first two, the AlmaLinux 10 shell for the third. The full walkthrough, prompts and all, is in the docs.
1 . Terminal & requirements
Install Windows Terminal, then confirm WSL 2 is enabled - Hyper-V, Virtual Machine Platform and Windows Subsystem for Linux, all turned on in Windows features.
wsl -v
2 . Install AlmaLinux 10
Stop any other running distro, then install AlmaLinux 10 and create your Unix username and password when prompted.
wsl --install -d AlmaLinux-10
3 . Setup packages
Clone dotkernel/development, fill in config.yml with your Git identity and MariaDB
root password, and let Ansible provision the rest.
ansible-playbook -i hosts install.yml --ask-become-pass
Not using WSL? Skip straight to Setup Packages on a bare AlmaLinux 10 host - the same playbook runs there unchanged.
What one playbook installs
install.yml reads config.yml once and provisions every one of these - safe to re-run if a
step fails partway through.
| Component | What you get |
|---|---|
| Web server | Apache, with virtualhosts routed automatically under *.localhost. |
| Database | MariaDB 11.4 LTS, plus phpMyAdmin for browsing it. |
| PHP | 8.4 by default via the Remi repository; php81 … php85 aliases switch
versions. |
| Node.js | 22 by default via NodeSource; node18 … node24 aliases switch versions. |
| Git & Composer | Your Git identity from config.yml, and the latest Composer, kept current with
composer self-update. |
| Ansible | community.general and community.mysql collections - the same tool that just
installed itself. |
Every project, its own subdomain
api.dotkernel.localhost and frontend.dotkernel.localhost can point at two different
projects on the same machine, and Apache routes both without a single edit to the Windows hosts
file - any *.localhost domain is routed automatically.
List the domains you want under config.yml's virtualhosts key and run the playbook.
Existing entries are left untouched, so you keep adding to the same file as your project grows.
One playbook, every domain
In development/wsl/config.yml, under virtualhosts:
api.dotkernel.localhost
Then provision it:
ansible-playbook -i hosts create-virtualhost.yml --ask-become-pass
Files go under /var/www/api.dotkernel.localhost/html, with the document root at
html/public.
Common questions
The short version of the full FAQ - see the docs for the rest.
How do I switch PHP versions? +
Run sudo dnf module switch-to php:remi-{major}.{minor} -y, or use one of the
predefined aliases: php81, php82, php83, php84 or
php85.
How do I switch Node.js versions? +
Use one of the predefined aliases - node18, node20, node22 or
node24 - which reinstall Node.js from NodeSource at that major version.
How do I fix permission issues? +
Local development only: chmod -R 777 data, log or
public/uploads, whichever directory the error names.
Where are the error logs? +
Apache: /var/log/httpd/error_log. PHP-FPM: /var/log/php-fpm/error.log and
www-error.log.
How do I update Composer? +
sudo /usr/local/bin/composer self-update, then confirm with
composer --version.
How do I create command aliases? +
Add alias name="command" to .bash_profile in your home directory, then run
it like any other command.
How do I delete a virtualhost? +
Remove its folder under /var/www/, its Apache config and enabled-site symlink, then
sudo systemctl restart httpd.
Can I run this without WSL? +
Yes - every instruction here works the same way on a bare AlmaLinux 10 host.
Provision once, match production everywhere.
The WSL 2 + AlmaLinux 10 setup is maintained by the same team behind the rest of the Headless Platform, so the local environment stays in step with what actually runs in production - not a Docker approximation of it.