Playwright-Headless-Browser.../docs/Running-in-Podman-Desktop-a...

659 lines
18 KiB
Markdown

# Install WebAccess.MCP, Podman Desktop, and LM Studio on a New Windows PC
This guide is for a person starting with a Windows computer that does not yet
have Podman Desktop, LM Studio, or WebAccess.MCP installed.
PowerShell privilege labels in this guide mean:
- **PowerShell (Standard user)**: open PowerShell normally.
- **PowerShell (Admin)**: right-click PowerShell and select **Run as
administrator**.
Use standard-user PowerShell unless a step is explicitly labeled
**PowerShell (Admin)**.
For a shorter operations-only guide that assumes Podman and the repository are
already installed, see `docs\Standing-Up-the-Podman-Compose-Stack.md`.
For a focused, step-by-step LM Studio MCP configuration guide, see
`docs\Adding-WebAccess-MCP-to-LM-Studio.md`.
It creates one predictable AI workspace on a drive of your choice:
```text
<drive>:\ai\
llm\
models\ LM Studio model files
mcp\
WebAccess.MCP\ This MCP server and its deployment files
```
For example, if `D:` has enough free space:
```text
D:\ai\llm\models
D:\ai\mcp\WebAccess.MCP
```
The examples below use `D:`. Substitute another local drive everywhere if
needed. Use the same drive consistently.
> Podman Desktop and LM Studio are normal Windows applications, so their
> executables and application settings are installed in Windows-managed
> locations. Podman also stores container images and volumes inside its managed
> Linux virtual machine. The model files, MCP source, and deployment
> configuration are organized beneath `<drive>:\ai`.
## What This Installation Provides
Podman Compose runs three containers:
- `webaccess`: the .NET 10 MCP server, Playwright, and headless Chromium.
- `searxng`: the dedicated search service used by `web_search`.
- `postgres`: durable page-cache storage.
LM Studio connects to WebAccess.MCP through Streamable HTTP at:
```text
http://127.0.0.1:28081/mcp
```
SearXNG is available for local diagnostics at:
```text
http://127.0.0.1:28080/
```
Both ports bind only to the local computer, not to the LAN.
## Before You Begin
You need:
- 64-bit Windows 10 build 19043 or later, or Windows 11.
- Administrator access for enabling WSL 2.
- Hardware virtualization enabled in the computer's BIOS or UEFI.
- At least 6 GB of RAM available to the Podman machine. More RAM is strongly
recommended because LM Studio must run a model at the same time.
- Enough free disk space for Podman images and one or more LLMs. Models commonly
consume several to tens of gigabytes each.
- Internet access during installation, image building, and model download.
- A trusted copy of the WebAccess.MCP repository.
The optional integration TestRig also requires the .NET 10 SDK. It is not
required for normal use because WebAccess.MCP builds inside a container.
## 1. Choose the AI Drive and Create the Folder Layout
Choose a local drive with enough free space. Avoid a network share, removable
drive, OneDrive, or another synchronized folder.
**PowerShell (Standard user)**
```powershell
$AiDrive = "D:"
$AiRoot = Join-Path $AiDrive "ai"
New-Item -ItemType Directory -Force -Path `
(Join-Path $AiRoot "llm\models"), `
(Join-Path $AiRoot "mcp")
```
Verify the layout:
```powershell
Get-ChildItem $AiRoot -Recurse
```
Keep `$AiRoot` set in this PowerShell window while completing the installation.
In a new PowerShell window, set it again:
```powershell
$AiRoot = "D:\ai"
```
## 2. Install WSL 2
Podman uses a small Linux virtual machine on Windows. WSL 2 is the recommended
provider.
**PowerShell (Admin)**
```powershell
wsl --install --no-distribution
```
Restart Windows if prompted. After restarting, open PowerShell and verify WSL:
```powershell
wsl --status
```
If WSL installation fails, confirm that virtualization is enabled in BIOS/UEFI
and that Windows is fully updated before continuing.
## 3. Install and Configure Podman Desktop
### Install the application
Use either method below.
**Option A: Windows Package Manager**
Open PowerShell and run:
```powershell
winget install --exact --id RedHat.Podman-Desktop
```
**Option B: Windows installer**
1. Download Podman Desktop from
[podman-desktop.io/downloads](https://podman-desktop.io/downloads).
2. Run the downloaded installer.
3. Choose whether to install it for the current user or all users.
4. Complete the installer and start Podman Desktop.
### Complete Podman Desktop onboarding
In Podman Desktop:
1. Select **Start Onboarding**.
2. Allow Podman Desktop to install the Podman engine.
3. Keep **WSL 2** selected as the machine provider.
4. Create the Podman machine when prompted.
5. Install the Compose CLI when prompted.
6. Complete onboarding and open the dashboard.
If onboarding was previously skipped:
1. Open **Settings > Resources**.
2. In the **Podman** tile, select **Setup Podman**.
3. Create and start a WSL-based Podman machine.
4. In the **Compose** tile, select **Setup**.
The official Podman Desktop minimum is 6 GB of RAM for its machine. If the
computer has sufficient memory, assign more resources in Podman Desktop so
Chromium, PostgreSQL, and SearXNG can run comfortably alongside LM Studio.
Open a new PowerShell window and verify both components:
```powershell
podman info
podman compose version
```
Do not continue until both commands succeed. If `podman info` cannot connect,
open Podman Desktop and start its Podman machine.
## 4. Install LM Studio and Set Its Model Folder
1. Download LM Studio for Windows from
[lmstudio.ai/download](https://lmstudio.ai/download).
2. Run the installer and start LM Studio.
3. Complete the initial setup.
4. Open **My Models** in LM Studio.
5. Use the model-directory control to change the models directory to:
```text
D:\ai\llm\models
```
LM Studio may create organization and model subdirectories beneath this folder.
Do not manually flatten those directories.
WebAccess.MCP requires LM Studio 0.3.17 or later. Check the installed version in
LM Studio and install any offered update before configuring MCP.
## 5. Put WebAccess.MCP Under the AI Folder
The final repository location must be:
```text
D:\ai\mcp\WebAccess.MCP
```
Use one of the following methods.
### Option A: Copy a supplied folder
If WebAccess.MCP was supplied as a folder, copy the entire folder into:
```text
D:\ai\mcp\
```
Do not copy only the `deploy` directory. The container build also needs the
production source beneath `src`.
### Option B: Extract a supplied ZIP file
Extract the ZIP and move or rename the extracted repository folder so that this
file exists:
```text
D:\ai\mcp\WebAccess.MCP\deploy\compose.yml
```
Avoid an accidental double folder such as:
```text
D:\ai\mcp\WebAccess.MCP\WebAccess.MCP\deploy\compose.yml
```
### Option C: Clone with Git
If the person distributing WebAccess.MCP provides a Git repository URL, install
Git and clone it:
```powershell
winget install --exact --id Git.Git
```
Close and reopen PowerShell after Git installation, then run:
```powershell
$AiRoot = "D:\ai"
Set-Location (Join-Path $AiRoot "mcp")
git clone <repository-url> WebAccess.MCP
```
Replace `<repository-url>` with the trusted URL supplied by the project owner.
### Verify the repository
```powershell
$AiRoot = "D:\ai"
$WebAccessRoot = Join-Path $AiRoot "mcp\WebAccess.MCP"
Test-Path (Join-Path $WebAccessRoot "deploy\compose.yml")
Test-Path (Join-Path $WebAccessRoot "Containerfile")
Test-Path (Join-Path $WebAccessRoot "src\WebAccess.MCP\WebAccess.MCP.csproj")
```
All three commands must return `True`.
## 6. Create Installation Secrets
WebAccess.MCP needs a local PostgreSQL password and SearXNG secret. Generate
unique values rather than copying secrets from another computer.
Open PowerShell and run:
```powershell
$AiRoot = "D:\ai"
$DeployRoot = Join-Path $AiRoot "mcp\WebAccess.MCP\deploy"
Set-Location $DeployRoot
function New-HexSecret {
$bytes = New-Object byte[] 32
$generator = [System.Security.Cryptography.RandomNumberGenerator]::Create()
try {
$generator.GetBytes($bytes)
}
finally {
$generator.Dispose()
}
-join ($bytes | ForEach-Object { $_.ToString("x2") })
}
@"
WEBACCESS_POSTGRES_PASSWORD=$(New-HexSecret)
SEARXNG_SECRET=$(New-HexSecret)
"@ | Set-Content -Encoding Ascii .env
```
Verify that the file exists without printing its secret values:
```powershell
Test-Path .env
```
The repository ignores `deploy\.env`. Keep it private, do not send it to anyone,
and do not commit it to Git.
## 7. Build and Start WebAccess.MCP
From `D:\ai\mcp\WebAccess.MCP\deploy`, run:
```powershell
.\Start-WebAccessStack.ps1
```
The script creates `deploy\.env` with random installation secrets if needed,
verifies Podman and Compose, and runs the entire Compose stack. The first run
downloads the base images and builds WebAccess.MCP. It can take several minutes
because the Playwright image includes Chromium and its Linux dependencies.
Check the services:
```powershell
podman compose --project-name webaccess-mcp ps
```
Expected result:
- `postgres` is running and healthy.
- `searxng` is running and healthy.
- `webaccess` is running.
Compose waits for PostgreSQL and SearXNG to become healthy before starting
WebAccess.MCP.
In Podman Desktop, open **Containers**. The three services should appear in a
`webaccess-mcp (compose)` group. Expand the group to inspect status, ports, and
logs.
If a service does not start:
```powershell
podman compose --project-name webaccess-mcp logs --tail 200
```
## 8. Verify the Running Services
Verify both local ports:
```powershell
Test-NetConnection 127.0.0.1 -Port 28080
Test-NetConnection 127.0.0.1 -Port 28081
```
Both results should include:
```text
TcpTestSucceeded : True
```
Verify the dedicated SearXNG instance:
```powershell
(Invoke-RestMethod "http://127.0.0.1:28080/config").instance_name
```
The expected name is:
```text
WebAccess.MCP SearXNG
```
The `/mcp` URL is a protocol endpoint, not a normal website. Opening it in a
browser is not a complete MCP test. LM Studio will perform the MCP handshake in
a later step.
## 9. Download a Tool-Capable Model in LM Studio
WebAccess.MCP supplies tools, but the selected language model decides when and
how to call them. Choose an **instruct/chat model with tool-use or function-call
support**. A plain base model is not suitable.
In LM Studio:
1. Open **Discover** (`Ctrl+2`).
2. Search for a tool-capable instruct model appropriate for the computer.
3. Select a GGUF quantization. A 4-bit option is a practical starting point for
many computers; larger quantizations need more RAM or VRAM.
4. Download the model.
5. Confirm in **My Models** that it was stored beneath:
```text
D:\ai\llm\models
```
6. Open **Chat** and load the model.
Prefer a model with enough context for tool schemas and returned web content.
At least 16K context is a useful starting point when the model and hardware
support it. Model availability changes frequently, so this guide does not lock
the installation to one model family.
If LM Studio cannot use MCP tools reliably with the chosen model, first confirm
that the model card advertises tool/function calling. Then try a stronger
instruct model or a less aggressive quantization if the hardware permits.
## 10. Introduce WebAccess.MCP to LM Studio
LM Studio 0.3.17 and later supports remote MCP servers by URL.
1. Keep the Podman stack running.
2. In LM Studio, open the **Program** tab in the right sidebar.
3. Select **Install > Edit mcp.json**.
4. If the file is empty, enter:
```json
{
"mcpServers": {
"webaccess": {
"url": "http://127.0.0.1:28081/mcp"
}
}
}
```
If the file already contains MCP servers, add only this property inside its
existing `mcpServers` object:
```json
"webaccess": {
"url": "http://127.0.0.1:28081/mcp"
}
```
Preserve the existing entries and include commas between JSON properties.
This is a remote Streamable HTTP MCP server:
- Do not add `command` or `args`.
- Do not add authentication headers.
- Do not use `http://127.0.0.1:28080`; that is SearXNG, not MCP.
- Do not use `localhost` if local security software resolves it unexpectedly;
use the exact `127.0.0.1` URL shown above.
5. Save `mcp.json`.
6. Confirm that `webaccess` appears and is enabled in the Program tab.
7. Start or return to a chat with the tool-capable model loaded.
8. Enable the WebAccess.MCP tools for that chat if LM Studio asks.
## 11. Test LM Studio and WebAccess.MCP Together
Ask the model:
> Use `web_search` to find the official LM Studio MCP documentation. Return the
> page title and source URL.
LM Studio should display a `web_search` tool call and its result.
Then test the browser tools:
> Open the official LM Studio MCP documentation URL, report the page title, and
> list the first five links.
WebAccess.MCP has 15 tools. LM Studio should show those tools as available when
the MCP connection is healthy.
The browser context is intentionally long-lived. Navigation and interaction
state persist across tool calls even though the MCP HTTP transport is stateless.
## 12. Start and Stop the System
### Start a normal session
1. Start Podman Desktop.
2. Make sure the Podman machine is running.
3. Open PowerShell and run:
```powershell
Set-Location "D:\ai\mcp\WebAccess.MCP\deploy"
podman compose --project-name webaccess-mcp up --detach
```
4. Start LM Studio.
5. Load the desired tool-capable model.
6. Confirm that `webaccess` is enabled in the Program tab.
### Stop a normal session
Close LM Studio if desired, then run:
```powershell
Set-Location "D:\ai\mcp\WebAccess.MCP\deploy"
podman compose --project-name webaccess-mcp stop
```
This preserves the containers and PostgreSQL page cache.
### Start the stopped containers again
```powershell
Set-Location "D:\ai\mcp\WebAccess.MCP\deploy"
podman compose --project-name webaccess-mcp start
```
### Remove containers but preserve data
```powershell
Set-Location "D:\ai\mcp\WebAccess.MCP\deploy"
podman compose --project-name webaccess-mcp down
```
This removes the containers and private network but preserves the PostgreSQL
volume.
## 13. Update WebAccess.MCP
Before updating, stop the stack:
```powershell
Set-Location "D:\ai\mcp\WebAccess.MCP\deploy"
podman compose --project-name webaccess-mcp down
```
Replace the supplied repository files with the newer version, or use Git:
```powershell
Set-Location "D:\ai\mcp\WebAccess.MCP"
git pull
```
Do not overwrite or delete `deploy\.env`.
Rebuild and start:
```powershell
Set-Location "D:\ai\mcp\WebAccess.MCP\deploy"
podman compose --project-name webaccess-mcp up --detach --build
```
The LM Studio `mcp.json` entry does not need to change as long as the endpoint
remains `http://127.0.0.1:28081/mcp`.
## 14. Optional Full Integration Test
This section is for maintainers or advanced troubleshooting. Install the .NET
10 SDK, keep the stack running, and execute from the repository root:
```powershell
Set-Location "D:\ai\mcp\WebAccess.MCP"
dotnet run --project ".\src\WebAccess.MCP.TestRig\WebAccess.MCP.TestRig.csproj" -- `
--mcp-url "http://127.0.0.1:28081/mcp" `
--real-searxng `
--real-searxng-engine google `
--real-searxng-engine brave `
--real-searxng-engine duckduckgo
```
The TestRig validates the HTTP MCP transport, the 15-tool contract, browser
state and interactions, page caching, and the externally managed SearXNG
service. External providers can still rate-limit or challenge automated search
requests.
## 15. Troubleshooting
### Podman commands are not recognized
Close and reopen PowerShell after installing Podman Desktop. If the commands
remain unavailable, return to Podman Desktop onboarding or **Settings >
Resources** and install Podman and Compose.
### Podman cannot connect
Open Podman Desktop and start the Podman machine. Then retry:
```powershell
podman info
```
If the machine cannot start, verify WSL 2:
```powershell
wsl --status
```
### LM Studio cannot connect to WebAccess.MCP
1. Confirm LM Studio is version 0.3.17 or later.
2. Confirm the URL is exactly `http://127.0.0.1:28081/mcp`.
3. Confirm `webaccess` is enabled in LM Studio's Program tab.
4. Run:
```powershell
Set-Location "D:\ai\mcp\WebAccess.MCP\deploy"
podman compose --project-name webaccess-mcp ps
Test-NetConnection 127.0.0.1 -Port 28081
podman compose --project-name webaccess-mcp logs --tail 200 webaccess
```
5. Check that `mcp.json` is valid JSON.
### A host port is already in use
Identify the owning process:
```powershell
Get-NetTCPConnection -State Listen -LocalPort 28080,28081 |
Select-Object -Property LocalAddress, LocalPort, OwningProcess
```
Stop or reconfigure the conflicting application. Do not substitute port 18080;
that port belongs to an unrelated deployment.
### PostgreSQL rejects the password after `.env` was changed
PostgreSQL initializes its password only when its data volume is first created.
Restore the original `WEBACCESS_POSTGRES_PASSWORD`.
If the password is lost and deleting the WebAccess.MCP page cache is acceptable,
perform an intentional reset:
```powershell
Set-Location "D:\ai\mcp\WebAccess.MCP\deploy"
podman compose --project-name webaccess-mcp down --volumes
podman compose --project-name webaccess-mcp up --detach --build
```
`down --volumes` permanently deletes this stack's PostgreSQL data. Do not use it
for normal shutdown.
### Search fails while browser tools work
1. Open `http://127.0.0.1:28080/config`.
2. Inspect the `searxng` and `webaccess` logs in Podman Desktop.
3. Confirm the dedicated SearXNG service is healthy.
External search engines can temporarily fail, rate-limit requests, or present
anti-bot challenges. WebAccess.MCP does not bypass those restrictions.
### The Compose group is missing in Podman Desktop
Confirm Podman Desktop is connected to the same Podman machine used by
PowerShell. Starting with the exact `--project-name webaccess-mcp` command adds
the Compose labels Podman Desktop uses to display the services as one group.
### LM Studio saves models somewhere else
Return to **My Models**, change the model directory to
`D:\ai\llm\models`, and use LM Studio's own directory controls to move or
redownload models. Do not manually reorganize a model while LM Studio is
running.