Table of Contents
On this page

AlmaLinux 10 Create virtualhosts

Summary

Add your desired domains to config.yml and run the create-virtualhost.yml Ansible playbook to provision each one.

By using the *.localhost pattern for any new virtualhost, you do not need to modify the hosts file in Windows, because these are routed by default.

This assumes you've already completed Setup Packages. Apache must already be installed before virtualhosts can be created.

Move inside the directory development/wsl:

cd ~/development/wsl/

If you don't already have a config.yml file, duplicate config.yml.dist as config.yml.

Using your preferred text editor, open config.yml and, under the virtualhosts key, enter the virtualhosts that you want to create, each on its own line. Already existing virtualhosts will be skipped, their contents will not be lost, no need to comment or remove them.

Virtualhost names should be valid hostnames (lowercase letters, numbers, and hyphens) ending in .localhost, for example api.dotkernel.localhost. Avoid spaces or other special characters.

You can come back and add more virtualhosts at any time: add new lines under virtualhosts and re-run the playbook. Existing virtualhosts are left untouched.

Save and close the file.

Create the specified virtualhosts:

ansible-playbook -i hosts create-virtualhost.yml --ask-become-pass

This process will ask for your AlmaLinux 10 password, iterate over the list of configured, and output a short summary with the results. Your virtualhost should be accessible and ready to use.

You will install your project under the html directory of your project, for example /var/www/example.localhost/html.

The virtualhost's document root is set to the public directory of the above location, for example /var/www/example.localhost/html/public.

If you want to have the DocumentRoot directly in html folder, you need to modify the file /etc/httpd/sites-available/example.localhost.

A freshly created virtualhost only has an empty html directory - html/public doesn't exist yet. Visiting the virtualhost's URL in your browser will show an error until you place a project there, this is expected.

Apache logs for each virtualhost are stored separately, for example /var/www/example.localhost/log/error.log and /var/www/example.localhost/log/requests.log. Check these first if something isn't working as expected.

Good to know

  • To run your installed projects, you need to start AlmaLinux 10 first.
  • If you work with virtualhosts, your projects are created under /var/www/.
  • You can still run PHP scripts under the default Apache project directory, located at /var/www/html/.
  • If you encounter write permission issues, see this guide.
  • We install PHP 8.4 by default-if you need a different version, see this guide.
  • We install Node.js 22 by default-if you need a different version, see this guide.

FAQ

Q: What if I don't have a config.yml file yet?

A: Duplicate the provided template by running the below command inside development/wsl:

cp config.yml.dist config.yml

Then add your virtualhosts under the virtualhosts key.

Q: What happens if I list a virtualhost that already exists?

A: It will simply be skipped. Its existing files and configuration are left untouched, so there's no need to comment out or remove already-created entries from config.yml.

Q: Where should I put my project's files?

A: Under the html directory of your virtualhost, for example /var/www/example.localhost/html. The document root is set to the public subdirectory of that location, for example /var/www/example.localhost/html/public.

Q: How do I make the DocumentRoot point directly to html instead of html/public?

A: Edit the virtualhost's Apache configuration file at /etc/httpd/sites-available/example.localhost and change the DocumentRoot accordingly.

Q: How do I access my virtualhost if AlmaLinux 10 isn't running?

A: You need to start AlmaLinux 10 first. Your virtualhosts are only reachable while the distro is running.

Q: What if I hit permission errors when writing to my project's files?

A: See the permission issues guide in the FAQ.

Q: How do I delete a virtualhost I no longer need?

A: See How do I delete a virtualhost? in the FAQ.