Infinito Nexus — WSL2 Windows Setup Guide

Development Windows
1

This guide documents every step needed to run Infinito Nexus locally on a Windows machine using WSL2 (Ubuntu 24.04 Noble) + Docker Desktop.

Prerequisites

  • Windows 10/11 with WSL2 enabled

  • Ubuntu 24.04 (Noble) WSL2 distro

  • Docker Desktop with WSL2 integration enabled for the Ubuntu distro

  • The infinito-nexus repository cloned into the WSL2 environment

Step 1 — WSL2: Enable systemd

Edit /etc/wsl.conf (create if missing):

Ini, TOML

[boot] systemd=true

Then restart WSL from PowerShell:

PowerShell

wsl --shutdown

Reopen the Ubuntu terminal.

Step 2 — WSL2: AppArmor wrapper

AppArmor is not loaded in the WSL2 kernel, causing make bootstrap to fail. Create a wrapper that silences the error:

Bash

sudo tee /usr/local/sbin/aa-teardown > /dev/null << 'EOF' #!/usr/bin/env bash /usr/sbin/aa-teardown "$@" exit 0 EOF sudo chmod +x /usr/local/sbin/aa-teardown

Step 3 — WSL2: dnsmasq for *.infinito.example DNS

3a. Disable systemd-resolved stub listener (frees port 53)

Bash

sudo mkdir -p /etc/systemd/resolved.conf.d sudo tee /etc/systemd/resolved.conf.d/disable-stub.conf > /dev/null << 'EOF' [Resolve] DNSStubListener=no EOF sudo systemctl restart systemd-resolved

3b. Create dnsmasq config

Bash

sudo tee /etc/dnsmasq.conf > /dev/null << 'EOF' bind-interfaces listen-address=127.0.0.1 conf-dir=/etc/dnsmasq.d EOF

3c. Create dnsmasq systemd service unit

Bash

`sudo tee /etc/systemd/system/dnsmasq.service > /dev/null << ‘EOF’ [Unit] Description=dnsmasq - A lightweight DHCP and caching DNS server After=network.target Before=network-online.target nss-lookup.target Wants=nss-lookup.target

[Service] Type=forking PIDFile=/run/dnsmasq/dnsmasq.pid ExecStartPre=/usr/sbin/dnsmasq --test ExecStart=/usr/sbin/dnsmasq -x /run/dnsmasq/dnsmasq.pid ExecReload=/bin/kill -HUP $MAINPID Restart=on-failure RuntimeDirectory=dnsmasq

[Install] WantedBy=multi-user.target EOF sudo systemctl daemon-reload sudo systemctl enable dnsmasq --now`

Step 4 — WSL2: Fix broken docker-buildx

Bash

`file ~/.docker/cli-plugins/docker-buildx 2>/dev/null

If it says “ASCII text” instead of “ELF”, it is corrupted:

rm ~/.docker/cli-plugins/docker-buildx`

Step 5 — Bootstrap the project

Bash

make bootstrap make dev-environment-bootstrap

Step 6 — Run the app test

Bash

make test-local-app APP=web-app-nextcloud

Step 7 — Trust the CA in Windows

7a. Extract the CA from WSL2

Bash

cp /etc/infinito.nexus/ca/root-ca.crt /mnt/c/Users/<YOUR_WINDOWS_USER>/Downloads/infinito-root-ca.crt

7b. Import into Windows Certificate Store

PowerShell

Import-Certificate -FilePath "$env:USERPROFILE\\Downloads\\infinito-root-ca.crt" -CertStoreLocation Cert:\\LocalMachine\\Root

Step 8 — Add DNS entries to Windows hosts file

PowerShell

$entries = @" 127.0.0.1 auth.infinito.example 127.0.0.1 dashboard.infinito.example 127.0.0.1 infinito.example 127.0.0.1 next.cloud.infinito.example "@ Add-Content -Path "C:\\Windows\\System32\\drivers\\etc\\hosts" -Value $entries

Accessing the apps

App URL
Nextcloud https://next.cloud.infinito.example
Auth / Keycloak https://auth.infinito.example
1 Like
2

I created here an work item in the product backlog to prevent this manual setup for developers on Windows Systems in the future :hugs:

1 Like