Skip to content

Commit 247b3a6

Browse files
bidi47bidi47
committed
synched wsl2 page - twig from md
Signed-off-by: bidi47 <bidi@apidemia.com>
1 parent 5fd7d12 commit 247b3a6

2 files changed

Lines changed: 90 additions & 39 deletions

File tree

‎src/App/templates/layout/default.html.twig‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -53,6 +53,7 @@
5353
<li><a class="dropdown-item" href="{{ url('page::dotboost') }}">Dotboost</a></li>
5454
<li><a class="dropdown-item" href="{{ url('page::light') }}">Light</a></li>
5555
<li><a class="dropdown-item" href="{{ url('page::frontend') }}">Frontend</a></li>
56+
<li><a class="dropdown-item" href="{{ url('page::wsl2') }}">WSL2 Dev Stack</a></li>
5657
</ul>
5758
</li>
5859
<li class="nav-item"><a class="nav-link" href="{{ url('page::architecture') }}">Architecture</a></li>

‎src/Page/templates/page/wsl2.html.twig‎

Lines changed: 89 additions & 39 deletions
Original file line numberDiff line numberDiff line change
@@ -4,7 +4,7 @@
44
{% set meta = {
55
title: 'Development Environment | AlmaLinux 10 on WSL 2',
66
description: 'AlmaLinux 10 on WSL 2 for a RHEL-compatible local stack. One Ansible playbook installs PHP, Apache, '
7-
~ 'MariaDB, Composer, Node.js and phpMyAdmin, and provisions a virtualhost for every project you add.',
7+
~ 'MariaDB, Composer, Node.js and phpMyAdmin, and a second provisions a virtualhost for every project you add.',
88
openGraphImage: '/opengraph/pages/twitter-card-wsl2.png',
99
} %}
1010

@@ -24,6 +24,7 @@
2424
.spec-table td { color: var(--text); }
2525
.spec-note { margin-top: 14px; font-size: 13.5px; color: var(--text-dim); }
2626
.step-cmd { display: block; margin-top: 12px; font-family: var(--mono); font-size: 12.5px; color: var(--teal); overflow-x: auto; }
27+
pre.step-cmd { margin-bottom: 0; white-space: pre; }
2728
2829
/* Windows/AlmaLinux boundary diagram in the hero - scoped to this page. */
2930
.ws-flow { display: block; width: 100%; height: auto; margin-top: 6px; }
@@ -48,7 +49,7 @@
4849
<div class="wrap hero-grid">
4950
<div>
5051
<span class="eyebrow">Development environment . AlmaLinux 10 . WSL2</span>
51-
<h1>AlmaLinux development, one playbook away on WSL2</h1>
52+
<h1>Development Environment</h1>
5253
<p class="sub">
5354
Dotkernel's local environment runs <strong>AlmaLinux 10</strong> - inside <strong>WSL 2</strong> on Windows, or on bare
5455
metal with no WSL at all. One <strong>Ansible</strong> playbook installs PHP, Apache, MariaDB, Composer, Node.js and
@@ -75,7 +76,7 @@
7576
<div class="hero-visual">
7677
<div class="pipeline">
7778
<div class="pipeline-label"><span>Windows host, Linux environment</span></div>
78-
<svg class="ws-flow" viewBox="0 0 400 200" role="img" aria-label="Two panels, Windows on the left with Terminal and IDE boxes, and AlmaLinux 10 on the right listing the components one playbook installs - web server, database, PHP, Node.js, Git and Composer, and Ansible - separated by a WSL 2 boundary">
79+
<svg class="ws-flow" viewBox="0 0 400 200" role="img" aria-label="Two panels, Windows on the left with Terminal and IDE boxes, and AlmaLinux 10 on the right listing the components one playbook installs - web server, database, PHP, Node.js, and Git and Composer - separated by a WSL 2 boundary">
7980
<defs>
8081
<marker id="ws-arrowhead" viewBox="0 0 10 10" refX="9" refY="5" markerWidth="6" markerHeight="6" orient="auto-start-reverse">
8182
<path d="M0,0 L10,5 L0,10 Z" class="ws-arrow"/>
@@ -113,9 +114,6 @@
113114

114115
<rect class="ws-comp" x="230" y="142" width="120" height="20" rx="5"/>
115116
<text class="ws-comp-label" x="290" y="156">Git &amp; Composer</text>
116-
117-
<rect class="ws-comp" x="230" y="166" width="120" height="20" rx="5"/>
118-
<text class="ws-comp-label" x="290" y="180">Ansible</text>
119117
</svg>
120118
</div>
121119
</div>
@@ -134,8 +132,9 @@
134132
Windows-native rebuild of every tool.
135133
</p>
136134
<p class="lede">
137-
Everything here also runs the same way without WSL, directly on a bare AlmaLinux 10 host - the
138-
Ansible playbooks do not know or care which one they are provisioning.
135+
Everything from Setup Packages onwards also runs on a bare AlmaLinux 10 host without WSL - the
136+
Ansible playbooks do not know or care which one they are provisioning. Connect over SSH, and use
137+
the server's IP address instead of <code>localhost</code> when you test it.
139138
</p>
140139
</div>
141140
<div class="traits">
@@ -167,34 +166,50 @@
167166
<div class="section-head">
168167
<span class="eyebrow">Setup</span>
169168
<h2>Three steps to a running shell</h2>
170-
<p>Each step runs in a different place - Windows Terminal for the first two, the AlmaLinux 10 shell for
171-
the third. The full walkthrough, prompts and all, is in the docs.</p>
169+
<p>Steps 1 and 2 run in Windows Terminal and step 3 in the AlmaLinux 10 shell; step 2 ends inside the
170+
new distro with a quick systemd check. The full walkthrough, prompts and all, is in the docs.</p>
172171
</div>
173172

174173
<div class="standards-grid">
175174
<div class="standard">
176175
<h4>1 . Terminal &amp; requirements</h4>
177-
<p>Install Windows Terminal, then confirm WSL 2 is enabled - Hyper-V, Virtual Machine Platform and
178-
Windows Subsystem for Linux, all turned on in Windows features.</p>
179-
<code class="step-cmd">wsl -v</code>
176+
<p>On Windows 11, install Windows Terminal, then check for a modern WSL 2 install. If
177+
<code>wsl --version</code> isn't recognized, install WSL 2 with
178+
<code>wsl --install --no-distribution</code> and restart when prompted.</p>
179+
<code class="step-cmd">wsl --version</code>
180180
</div>
181181
<div class="standard">
182182
<h4>2 . Install AlmaLinux 10</h4>
183183
<p>Stop any other running distro, then install AlmaLinux 10 and create your Unix username and
184184
password when prompted.</p>
185185
<code class="step-cmd">wsl --install -d AlmaLinux-10</code>
186+
<p>Before moving on, confirm systemd is active inside AlmaLinux 10 - the playbook needs it. If the
187+
check below prints an error instead of a status, add <code>systemd=true</code> under
188+
<code>[boot]</code> in <code>/etc/wsl.conf</code>, run <code>wsl --shutdown</code> from Windows
189+
Terminal and reopen the distro.</p>
190+
<code class="step-cmd">systemctl is-system-running</code>
186191
</div>
187192
<div class="standard">
188193
<h4>3 . Setup packages</h4>
189-
<p>Clone <code>dotkernel/development</code>, fill in <code>config.yml</code> with your Git identity and MariaDB
190-
root password, and let Ansible provision the rest.</p>
194+
<p>Inside AlmaLinux 10, update the system, add the EPEL and Remi repositories, and install
195+
<code>ansible-core</code> with the <code>community.general</code> and <code>community.mysql</code>
196+
collections. Then clone the <code>alma-linux-10</code> branch of <code>dotkernel/development</code>,
197+
copy <code>wsl/config.yml.dist</code> to <code>config.yml</code>, fill in your Git identity and
198+
MariaDB root password, and run the playbook from <code>development/wsl</code>.</p>
191199
<code class="step-cmd">ansible-playbook -i hosts install.yml --ask-become-pass</code>
192200
</div>
193201
</div>
194202

195203
<p class="spec-note">
196204
Not using WSL? Skip straight to Setup Packages on a bare AlmaLinux 10 host - the same playbook runs
197-
there unchanged.
205+
there unchanged; test it with the server's IP address instead of <code>localhost</code>.
206+
</p>
207+
<p class="spec-note">
208+
After setup,
209+
<a href="https://docs.dotkernel.org/development/v2/editor-integration/" target="_blank" rel="noopener">Editor Integration</a>
210+
connects VS Code or PhpStorm, and
211+
<a href="https://docs.dotkernel.org/development/v2/wsl-configuration/" target="_blank" rel="noopener">WSL Configuration</a>
212+
covers where to keep projects and how to cap WSL's memory and CPU.
198213
</p>
199214
</div>
200215
</section>
@@ -223,11 +238,11 @@
223238
</tr>
224239
<tr>
225240
<th scope="row">Database</th>
226-
<td>MariaDB 11.4 LTS, plus phpMyAdmin for browsing it.</td>
241+
<td>MariaDB 12.3 from the MariaDB repository, plus phpMyAdmin for browsing it.</td>
227242
</tr>
228243
<tr>
229244
<th scope="row">PHP</th>
230-
<td>8.4 by default via the Remi repository; <code>php81</code> … <code>php85</code> aliases switch
245+
<td>8.5 by default via the Remi repository; <code>php81</code> … <code>php85</code> aliases switch
231246
versions.</td>
232247
</tr>
233248
<tr>
@@ -236,13 +251,8 @@
236251
</tr>
237252
<tr>
238253
<th scope="row">Git &amp; Composer</th>
239-
<td>Your Git identity from <code>config.yml</code>, and the latest Composer, kept current with
240-
<code>composer self-update</code>.</td>
241-
</tr>
242-
<tr>
243-
<th scope="row">Ansible</th>
244-
<td><code>community.general</code> and <code>community.mysql</code> collections - the same tool that just
245-
installed itself.</td>
254+
<td>Your Git identity from <code>config.yml</code>, and the latest Composer at install time; update
255+
it later with <code>composer self-update</code>.</td>
246256
</tr>
247257
</tbody>
248258
</table>
@@ -261,7 +271,9 @@
261271
file - any <code>*.localhost</code> domain is routed automatically.
262272
</p>
263273
<p class="lede">
264-
List the domains you want under <code>config.yml</code>'s <code>virtualhosts</code> key and run the playbook.
274+
List the domains you want under <code>config.yml</code>'s <code>virtualhosts</code> key and run
275+
<code>create-virtualhost.yml</code> - a separate playbook you re-run for every new project, without
276+
repeating <code>install.yml</code>.
265277
Existing entries are left untouched, so you keep adding to the same file as your project grows.
266278
</p>
267279
<div class="hero-ctas">
@@ -270,13 +282,23 @@
270282
</div>
271283
<div class="callout">
272284
<h4>One playbook, every domain</h4>
273-
<p>In <code>development/wsl/config.yml</code>, under <code>virtualhosts</code>:</p>
274-
<code class="step-cmd">api.dotkernel.localhost</code>
285+
<p>In <code>development/wsl/config.yml</code>, under <code>config.virtualhosts</code>:</p>
286+
<pre class="step-cmd">config:
287+
virtualhosts:
288+
- "api.dotkernel.localhost"</pre>
289+
<p>
290+
<code>api.dotkernel.localhost</code> is only an example - use any name your project needs, such as
291+
<code>laravel.localhost</code> or <code>shop.localhost</code>, as long as it ends in
292+
<code>.localhost</code> and uses only lowercase letters, numbers and hyphens. Add one list item per
293+
project.
294+
</p>
275295
<p>Then provision it:</p>
276296
<code class="step-cmd">ansible-playbook -i hosts create-virtualhost.yml --ask-become-pass</code>
277297
<p>
278-
Files go under <code>/var/www/api.dotkernel.localhost/html</code>, with the document root at
279-
<code>html/public</code>.
298+
Files go under <code>/var/www/&lt;your-domain&gt;/html</code> - for example
299+
<code>/var/www/api.dotkernel.localhost/html</code> - with the document root at
300+
<code>html/public</code>. <code>html/public</code> doesn't exist until you place a project there,
301+
so the URL shows an error until then.
280302
</p>
281303
</div>
282304
</div>
@@ -310,18 +332,18 @@
310332
<summary>How do I fix permission issues? <span class="chev">+</span></summary>
311333
<div class="acc-body">
312334
<p>Local development only: <code>chmod -R 777 data</code>, <code>log</code> or
313-
<code>public/uploads</code>, whichever directory the error names.</p>
335+
<code>public/uploads</code>, whichever directory the error names. Don't carry this into
336+
staging or production.</p>
314337
</div>
315338
</details>
316339
<details class="acc">
317340
<summary>Where are the error logs? <span class="chev">+</span></summary>
318341
<div class="acc-body">
319-
<p>Apache: <code>/var/log/httpd/error_log</code>. PHP-FPM: <code>/var/log/php-fpm/error.log</code> and
320-
<code>www-error.log</code>.</p>
342+
<p>Apache: <code>/var/log/httpd/error_log</code>, plus
343+
<code>/var/www/&lt;virtualhost&gt;/log/error.log</code> for each virtualhost. PHP-FPM:
344+
<code>/var/log/php-fpm/error.log</code> and <code>www-error.log</code>.</p>
321345
</div>
322346
</details>
323-
</div>
324-
<div>
325347
<details class="acc">
326348
<summary>How do I update Composer? <span class="chev">+</span></summary>
327349
<div class="acc-body">
@@ -336,17 +358,44 @@
336358
it like any other command.</p>
337359
</div>
338360
</details>
361+
</div>
362+
<div>
339363
<details class="acc">
340364
<summary>How do I delete a virtualhost? <span class="chev">+</span></summary>
341365
<div class="acc-body">
342366
<p>Remove its folder under <code>/var/www/</code>, its Apache config and enabled-site symlink, then
343367
<code>sudo systemctl restart httpd</code>.</p>
344368
</div>
345369
</details>
370+
<details class="acc">
371+
<summary>Why does the playbook fail with a systemd error? <span class="chev">+</span></summary>
372+
<div class="acc-body">
373+
<p>systemd isn't active in the distro yet. Add <code>systemd=true</code> under <code>[boot]</code> in
374+
<code>/etc/wsl.conf</code>, run <code>wsl --shutdown</code> from Windows Terminal, reopen
375+
AlmaLinux 10 and re-run <code>install.yml</code>.</p>
376+
</div>
377+
</details>
378+
<details class="acc">
379+
<summary>What if port 80 is already in use? <span class="chev">+</span></summary>
380+
<div class="acc-body">
381+
<p>Find the Windows service holding it with <code>netstat -ano | findstr :80</code> and stop it, or
382+
change Apache's <code>Listen</code> port in <code>/etc/httpd/conf/httpd.conf</code> and restart
383+
httpd.</p>
384+
</div>
385+
</details>
386+
<details class="acc">
387+
<summary>Is this environment safe to expose beyond localhost? <span class="chev">+</span></summary>
388+
<div class="acc-body">
389+
<p>No. It is for local development only: the MariaDB root password is stored in plaintext,
390+
phpMyAdmin allows root login and the firewall is off by default.</p>
391+
</div>
392+
</details>
346393
<details class="acc">
347394
<summary>Can I run this without WSL? <span class="chev">+</span></summary>
348395
<div class="acc-body">
349-
<p>Yes - every instruction here works the same way on a bare AlmaLinux 10 host.</p>
396+
<p>Yes - from Setup Packages onwards the steps are the same on a bare AlmaLinux 10 host. Skip the
397+
WSL steps, connect over SSH, and use the server's IP address instead of
398+
<code>localhost</code>.</p>
350399
</div>
351400
</details>
352401
</div>
@@ -358,13 +407,14 @@
358407
<div class="wrap about-inner">
359408
<div>
360409
<span class="eyebrow">Built for how the platform ships</span>
361-
<h2>Provision once, match production everywhere.</h2>
410+
<h2>Provision once, match your production OS</h2>
362411
</div>
363412
<div>
364413
<p class="about-text">
365414
The WSL 2 + AlmaLinux 10 setup is maintained by the same team behind the rest of the Headless
366-
Platform, so the local environment stays in step with what actually runs in production - not a
367-
Docker approximation of it.
415+
Platform, so the local environment stays on the same OS family as production - not a Docker
416+
approximation of it. It is a local development environment only: security is relaxed by default,
417+
so never expose it to a network.
368418
</p>
369419
<div class="about-cta">
370420
<a class="btn btn-ghost" href="{{ url('page::contact') }}">Talk to us -></a>

0 commit comments

Comments
 (0)