From 7d455c4ac539049944cb2757fbfd7fa1856c712b Mon Sep 17 00:00:00 2001 From: bidi Date: Thu, 24 Sep 2026 18:23:53 +0300 Subject: [PATCH] Fix virtualhost flow accuracy and clarify the two-step setup process - Drop redundant "AlmaLinux 10 " title prefixes. - Fix wrong virtualhost config path: the file Ansible actually writes is example.localhost.conf, not example.localhost. - Fix missing noun ("...list of configured, and output..." -> "...list of configured virtualhosts, and output..."). - Fix hyphen-flattened em dashes, and phrase the PHP default version by pointing at wsl/roles/php/tasks/main.yml instead of hardcoding a number that will drift again. - Fix absolute docs.dotkernel.org cross-links to relative paths. - Clarify that provisioning is two independent, repeatable steps: install.yml sets up the server-wide stack once; creating a virtualhost per project is separate and can be repeated any time. Reworded create-virtualhost.md's summary and setup-packages.md's config.virtualhosts field + "Next step" section accordingly. - Add a short security-framing note to setup-packages.md: this stack is local-development-only, with a plaintext MariaDB root password and root-login phpMyAdmin exposed at a predictable path. --- docs/book/v2/setup/setup-packages.md | 8 +++++--- .../v2/virtualhosts/create-virtualhost.md | 20 ++++++++++--------- docs/book/v2/virtualhosts/overview.md | 2 +- 3 files changed, 17 insertions(+), 13 deletions(-) diff --git a/docs/book/v2/setup/setup-packages.md b/docs/book/v2/setup/setup-packages.md index 9748bee..7fdbe4a 100644 --- a/docs/book/v2/setup/setup-packages.md +++ b/docs/book/v2/setup/setup-packages.md @@ -1,4 +1,4 @@ -# AlmaLinux 10 Setup +# Setup ## Summary @@ -88,7 +88,9 @@ Using your preferred text editor, open `config.yml` and fill in the empty fields * `config.git.config."user.name"` / `"user.email"`: the identity Git will use for your commits inside AlmaLinux 10. * `config.mariadb.root_password`: the password to set for MariaDB's `root` user (you'll use this to log into phpMyAdmin later). * `config.system.username`: defaults to your current AlmaLinux 10 username automatically, usually no change needed. -* `config.virtualhosts`: a list of local domains to create virtualhosts for (see [Virtualhosts](../virtualhosts/overview.md)); the default entry `example.localhost` can be removed or left as-is. +* `config.virtualhosts`: an optional starter list of local domains to create a virtualhost for during this same run; the default entry `example.localhost` can be removed or left as-is. You do not need to list every project here — see [Create a virtualhost](../virtualhosts/create-virtualhost.md) to add one at any time after setup, without re-running this step. + +> This environment is intended for **local development only**, not production or network-exposed use — security is relaxed or effectively nonexistent by default. `config.mariadb.root_password` is stored in plaintext in this gitignored, local-only `config.yml`, and phpMyAdmin is exposed at `/phpmyadmin` with root login. That's acceptable for a local dev box, but this stack should never be exposed to a network. Save and close the file. @@ -115,7 +117,7 @@ The installation is complete, your **AlmaLinux 10** development environment is r ## Next step -Your environment is now provisioned. Continue to [Running on WSL 2](../running.md) to learn how to (re)connect to your **AlmaLinux 10** distro, or jump straight to [Virtualhosts](../virtualhosts/overview.md) to host your first project. +`install.yml` provisions the server-wide stack (Apache, PHP, MariaDB, phpMyAdmin, Composer, Node.js) — a one-time step you don't need to repeat. Creating a virtualhost for a project is a separate, repeatable step: continue to [Running on WSL 2](../running.md) to learn how to (re)connect to your **AlmaLinux 10** distro, or jump straight to [Create a virtualhost](../virtualhosts/create-virtualhost.md) whenever you're ready to host a project — you can come back and repeat that step for every new project. ## FAQ diff --git a/docs/book/v2/virtualhosts/create-virtualhost.md b/docs/book/v2/virtualhosts/create-virtualhost.md index fd461f5..27a7748 100644 --- a/docs/book/v2/virtualhosts/create-virtualhost.md +++ b/docs/book/v2/virtualhosts/create-virtualhost.md @@ -1,7 +1,9 @@ -# AlmaLinux 10 Create virtualhosts +# Create virtualhosts ## Summary +Provisioning your **AlmaLinux 10** environment is a two-step process: `install.yml` sets up the server-wide stack once (Apache, PHP, MariaDB, phpMyAdmin, Composer, Node.js); creating a virtualhost for each project is a separate, repeatable step that you run as needed, any time after that — this page covers that second step. + 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. @@ -34,14 +36,14 @@ 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. +This process will ask for your **AlmaLinux 10** password, iterate over the list of configured virtualhosts, 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`. +> If you want to have the DocumentRoot directly in `html` folder, you need to modify the file `/etc/httpd/sites-available/example.localhost.conf`. > 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. @@ -54,9 +56,9 @@ You will install your project under the `html` directory of your project, for ex * 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](https://docs.dotkernel.org/development/v2/faq/#how-do-i-fix-common-permission-issues). -* We install PHP 8.4 by default-if you need a different version, see [this guide](https://docs.dotkernel.org/development/v2/faq/#how-do-i-switch-to-a-different-version-of-php). -* We install Node.js 22 by default-if you need a different version, see [this guide](https://docs.dotkernel.org/development/v2/faq/#how-do-i-switch-to-a-different-version-of-nodejs). +* If you encounter write permission issues, see [this guide](../faq.md#how-do-i-fix-common-permission-issues). +* We install the PHP version pinned in `wsl/roles/php/tasks/main.yml` (currently 8.5) by default — if you need a different version, see [this guide](../faq.md#how-do-i-switch-to-a-different-version-of-php). +* We install Node.js 22 by default — if you need a different version, see [this guide](../faq.md#how-do-i-switch-to-a-different-version-of-nodejs). ## FAQ @@ -82,7 +84,7 @@ The document root is set to the `public` subdirectory of that location, for exam **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. +A: Edit the virtualhost's Apache configuration file at `/etc/httpd/sites-available/example.localhost.conf` and change the `DocumentRoot` accordingly. **Q: How do I access my virtualhost if AlmaLinux 10 isn't running?** @@ -91,8 +93,8 @@ 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](https://docs.dotkernel.org/development/v2/faq/#how-do-i-fix-common-permission-issues) in the FAQ. +A: See the [permission issues guide](../faq.md#how-do-i-fix-common-permission-issues) in the FAQ. **Q: How do I delete a virtualhost I no longer need?** -A: See [How do I delete a virtualhost?](https://docs.dotkernel.org/development/v2/faq/#how-do-i-delete-a-virtualhost) in the FAQ. +A: See [How do I delete a virtualhost?](../faq.md#how-do-i-delete-a-virtualhost) in the FAQ. diff --git a/docs/book/v2/virtualhosts/overview.md b/docs/book/v2/virtualhosts/overview.md index 0e3e7f5..dd75d22 100644 --- a/docs/book/v2/virtualhosts/overview.md +++ b/docs/book/v2/virtualhosts/overview.md @@ -1,4 +1,4 @@ -# AlmaLinux 10 Overview +# Overview ## Summary