Skip to content

Commit 3c66265

Browse files
sanityclaude
andcommitted
Add Docker install instructions and WSL2 troubleshooting
- Add Docker section to quickstart with basic run command - Document Windows WSL2 networking configuration needed for UDP - Include Hyper-V firewall fix for peer-to-peer connections Thanks to fluffomat for diagnosing and documenting the WSL2 fix. Co-Authored-By: Claude <noreply@anthropic.com>
1 parent c413bec commit 3c66265

File tree

1 file changed

+43
-0
lines changed

1 file changed

+43
-0
lines changed

hugo-site/content/quickstart/_index.md

Lines changed: 43 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -36,6 +36,16 @@ cargo install freenet
3636

3737
Then start Freenet with `freenet network`.
3838

39+
### Docker
40+
41+
Freenet provides official Docker images. Pull and run with:
42+
43+
```bash
44+
docker run -p 50509:50509 -p 56208:56208/udp freenetorg/freenet:latest
45+
```
46+
47+
**Windows (WSL2) users:** Docker Desktop on Windows requires additional configuration for UDP networking. See the [Windows WSL2 Setup](#windows-wsl2-docker-setup) section in Troubleshooting below.
48+
3949
## Step 2: Join Freenet Official
4050

4151
Get an invite to our community chat. You can request up to 5 invites per day.
@@ -50,6 +60,39 @@ If you run into problems, join our [Matrix chat](https://matrix.to/#/#freenet-lo
5060

5161
**Network requirements:** Freenet uses UDP hole punching for peer-to-peer connections. Most home routers support this without configuration. Strict corporate firewalls may block connections.
5262

63+
### Windows WSL2 Docker Setup
64+
65+
Docker Desktop on Windows uses WSL2, which has networking layers that can block Freenet's UDP peer-to-peer connections. If River won't load or gets stuck at "Subscribing to room", follow these steps:
66+
67+
**1. Configure WSL2 networking**
68+
69+
Create or edit `%USERPROFILE%\.wslconfig` with:
70+
71+
```ini
72+
[wsl2]
73+
networkingMode=Mirrored
74+
firewall=false
75+
76+
[experimental]
77+
hostAddressLoopback=true
78+
```
79+
80+
**2. Allow UDP through the Hyper-V firewall**
81+
82+
Open PowerShell as Administrator and run:
83+
84+
```powershell
85+
Set-NetFirewallHyperVVMSetting -Name '{40E0AC32-46A5-438A-A0B2-2B479E8F2E90}' -DefaultInboundAction Allow
86+
```
87+
88+
**3. Restart WSL**
89+
90+
```powershell
91+
wsl --shutdown
92+
```
93+
94+
Then restart Docker Desktop.
95+
5396
## What's Next?
5497

5598
- [Live Network Dashboard](http://nova.locut.us:3133/) - Watch real-time activity on the network

0 commit comments

Comments
 (0)