# Stand Up the WebAccess.MCP Podman Compose Stack This runbook covers only the Podman Compose stack: configure it, build it, start it, verify it, inspect it, stop it, and rebuild it. All commands in this runbook use **PowerShell (Standard user)**. No command in this runbook requires **PowerShell (Admin)** because Podman and its machine are prerequisites. For the short clone, one-command startup, and LM Studio connection path, see `QUICKSTART.md` in the repository root. For complete first-time Windows, Podman Desktop, LM Studio, folder-layout, and model-installation instructions, see `docs\Running-in-Podman-Desktop-and-LM-Studio.md`. To build and create a clean deployment folder and ZIP for another computer, run `Export-WebAccessDeployment.ps1` from the repository root. See **Create a Deployment Bundle** below. ## The Short Answer After cloning or extracting the repository, open PowerShell in the repository root and run one command: ```powershell .\Start-WebAccessMcp.cmd ``` That command does the whole job: 1. Checks that Podman is installed and running. 2. Checks that Podman Compose is installed. 3. Creates `deploy\.env` with random secrets if it does not exist. 4. Runs Compose with `up --detach --build`. 5. Starts PostgreSQL, SearXNG, and WebAccess.MCP in dependency order. 6. Displays the status, local URLs, LM Studio JSON, and refresh instruction. It does not replace or print an existing `.env` file. The root command launches `deploy\Start-WebAccessStack.ps1` with a temporary PowerShell execution-policy bypass. It does not change the computer's permanent execution policy. The direct Compose command used underneath is: ```powershell Set-Location "D:\ai\mcp\WebAccess.MCP\deploy" podman compose --project-name webaccess-mcp up --detach --build ``` You do not start the containers separately. ### Complete clone-to-LM-Studio flow ```powershell git clone WebAccess.MCP Set-Location ".\WebAccess.MCP" .\Start-WebAccessMcp.cmd ``` Replace `` with the repository URL supplied by the project owner. After the command succeeds: 1. In LM Studio, open **Program > Install > Edit mcp.json**. 2. Add this entry inside the existing `mcpServers` object: ```json "webaccess": { "url": "http://127.0.0.1:28081/mcp" } ``` 3. Save `mcp.json`. 4. Click **Refresh** in LM Studio. That is the complete normal installation path for someone who already has Podman Desktop, LM Studio, and a tool-capable model. ## Stack Overview The Compose project starts three services: | Service | Purpose | Host access | | --- | --- | --- | | `webaccess` | WebAccess.MCP, Playwright, and Chromium | `http://127.0.0.1:28081/mcp` | | `searxng` | Dedicated search service | `http://127.0.0.1:28080/` | | `postgres` | Durable WebAccess.MCP page cache | Not published | All services share a private Compose network. WebAccess.MCP reaches SearXNG at `http://searxng:8080/` and PostgreSQL at `postgres:5432`. The host bindings use `127.0.0.1`, so WebAccess.MCP and SearXNG are available only on the computer running the stack. They are not exposed to the LAN. ## Requirements Before using this runbook: - Podman Desktop must be installed. - A Podman machine must be running. - The Compose provider must be installed. - The complete WebAccess.MCP repository must be present locally. The examples assume: ```text D:\ai\mcp\WebAccess.MCP ``` Replace `D:` consistently if the AI folder is on another local drive. Verify Podman and Compose: ```powershell podman info podman compose version ``` Both commands must succeed. ## 1. Open the Deployment Directory Open PowerShell and run: ```powershell $WebAccessRoot = "D:\ai\mcp\WebAccess.MCP" $DeployRoot = Join-Path $WebAccessRoot "deploy" Set-Location $DeployRoot ``` Verify the required deployment files: ```powershell Test-Path ".\compose.yml" Test-Path "..\Containerfile" Test-Path ".\searxng\settings.yml" ``` All three commands must return `True`. ## 2. Environment File `Start-WebAccessStack.ps1` creates this file automatically on its first run. The stack requires: - `WEBACCESS_POSTGRES_PASSWORD` - `SEARXNG_SECRET` The following manual procedure is needed only if the script cannot be used. Generate unique values for this installation: ```powershell 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 displaying its contents: ```powershell Test-Path ".env" ``` Keep `.env` private. Do not commit, publish, or send it to another person. The repository's `.gitignore` excludes `deploy\.env`. If `.env` already exists for a working installation, keep it. Do not generate a new password over an existing PostgreSQL volume. Skip this section on every normal start. ## 3. Review the Effective Compose Model Validate the Compose file: ```powershell podman compose --project-name webaccess-mcp config --quiet ``` A successful command produces no errors. Do not run `podman compose config` without `--quiet` in logs or support messages: its expanded output can contain the PostgreSQL password. ## 4. Build and Start the Stack The recommended command is: ```powershell Set-Location .. .\Start-WebAccessMcp.cmd ``` Alternatively, from the `deploy` directory run the PowerShell launcher directly: ```powershell .\Start-WebAccessStack.ps1 ``` Or run Compose directly: ```powershell podman compose --project-name webaccess-mcp up --detach --build ``` This is the single command that stands up the whole stack. Do not run separate `podman run` commands for PostgreSQL, SearXNG, or WebAccess.MCP. This command: 1. Pulls the PostgreSQL, SearXNG, .NET, and Playwright base images as needed. 2. Builds the `webaccess` image from the repository source. 3. Creates the private network and PostgreSQL volume. 4. Starts PostgreSQL and waits for it to become healthy. 5. Starts SearXNG and waits for it to become healthy. 6. Starts WebAccess.MCP. The first build can take several minutes. Later builds generally reuse cached image layers. ## 5. Check Container Status Run: ```powershell podman compose --project-name webaccess-mcp ps ``` Expected state: - `postgres`: running and healthy. - `searxng`: running and healthy. - `webaccess`: running. In Podman Desktop, open **Containers** and expand the `webaccess-mcp (compose)` group. It should contain the same three services. If `webaccess` is absent, first confirm that PostgreSQL and SearXNG reached healthy status. Compose does not start WebAccess.MCP until both dependencies are healthy. ## 6. Verify Host Connectivity Verify that SearXNG and WebAccess.MCP are listening: ```powershell Test-NetConnection 127.0.0.1 -Port 28080 Test-NetConnection 127.0.0.1 -Port 28081 ``` Both results must include: ```text TcpTestSucceeded : True ``` Verify that the correct SearXNG instance is running: ```powershell (Invoke-RestMethod "http://127.0.0.1:28080/config").instance_name ``` Expected output: ```text WebAccess.MCP SearXNG ``` The MCP endpoint is: ```text http://127.0.0.1:28081/mcp ``` It is a Streamable HTTP MCP protocol endpoint, not a normal website. A browser GET is not a complete health check or MCP handshake. ## 7. Inspect Logs Show the most recent logs from every service: ```powershell podman compose --project-name webaccess-mcp logs --tail 200 ``` Show one service: ```powershell podman compose --project-name webaccess-mcp logs --tail 200 webaccess podman compose --project-name webaccess-mcp logs --tail 200 searxng podman compose --project-name webaccess-mcp logs --tail 200 postgres ``` Follow WebAccess.MCP logs: ```powershell podman compose --project-name webaccess-mcp logs --follow webaccess ``` Press `Ctrl+C` to stop following logs. This does not stop the service. ## 8. Normal Start and Stop Commands Run all commands from: ```text D:\ai\mcp\WebAccess.MCP\deploy ``` ### Stop without removing containers ```powershell podman compose --project-name webaccess-mcp stop ``` ### Start stopped containers ```powershell podman compose --project-name webaccess-mcp start ``` ### Restart all services ```powershell podman compose --project-name webaccess-mcp restart ``` ### Restart one service ```powershell podman compose --project-name webaccess-mcp restart webaccess ``` ### Remove containers and the private network ```powershell podman compose --project-name webaccess-mcp down ``` `down` preserves the named PostgreSQL volume. The page cache remains available the next time the stack starts. ### Start after `down` ```powershell podman compose --project-name webaccess-mcp up --detach ``` ## 9. Rebuild After a Source Update After replacing the source or running `git pull`, execute: ```powershell Set-Location "D:\ai\mcp\WebAccess.MCP\deploy" podman compose --project-name webaccess-mcp up --detach --build ``` Compose rebuilds the WebAccess.MCP image and recreates services when necessary. The PostgreSQL volume and its cached page data are preserved. To force a completely fresh WebAccess.MCP image build without deleting PostgreSQL data: ```powershell podman compose --project-name webaccess-mcp build --no-cache webaccess podman compose --project-name webaccess-mcp up --detach ``` Use the no-cache build only for troubleshooting stale build layers. It is slower than a normal rebuild. ## 10. Create a Deployment Bundle Run this from the development repository root to build WebAccess.MCP and create a clean bundle that can be copied or uploaded: ```powershell Set-Location "D:\path\to\the\WebAccess.MCP-repository" .\Export-WebAccessDeployment.ps1 ``` By default, the script creates a timestamped folder and ZIP beneath `artifacts`, for example: ```text artifacts\ WebAccess.MCP-deployment-20260821-193000\ WebAccess.MCP\ .dockerignore deploy\ docs\ src\ WebAccess.MCP.zip ``` The script: 1. Builds the production container image with Podman. 2. Copies only the production source and required Compose/container files. 3. Excludes `bin`, `obj`, tests, TestRig files, IDE files, Git metadata, and `deploy\.env`. 4. Includes the startup script and operator documentation. 5. Creates a ZIP suitable for uploading or transferring. To choose the output folder: ```powershell .\Export-WebAccessDeployment.ps1 ` -DestinationPath "D:\release\WebAccess.MCP" ``` This also creates: ```text D:\release\WebAccess.MCP.zip ``` The destination and ZIP must not already exist. The script refuses to overwrite an existing release. To create the bundle without ZIP compression: ```powershell .\Export-WebAccessDeployment.ps1 ` -DestinationPath "D:\release\WebAccess.MCP" ` -NoArchive ``` To package without building the image first: ```powershell .\Export-WebAccessDeployment.ps1 -SkipBuild ``` Use `-SkipBuild` only when Podman is unavailable or the image has already been validated separately. The default behavior proves that the bundled source can build before creating the release. The bundle never contains `.env` or installation secrets. On the destination computer, extract or copy the `WebAccess.MCP` folder to: ```text :\ai\mcp\WebAccess.MCP ``` Then run: ```powershell Set-Location ":\ai\mcp\WebAccess.MCP" .\Start-WebAccessMcp.cmd ``` The startup script creates new machine-specific secrets and starts the complete Compose stack. ## 11. Intentional Data Reset The following operation removes the containers, network, and PostgreSQL volume: ```powershell podman compose --project-name webaccess-mcp down --volumes ``` This permanently deletes WebAccess.MCP's page-cache database. It does not delete the source repository or `.env`. Use it only when: - A completely clean database is explicitly required. - The PostgreSQL password was lost or intentionally changed. - The PostgreSQL volume is known to be unusable. Start a new stack afterward: ```powershell podman compose --project-name webaccess-mcp up --detach --build ``` Do not use `down --volumes` for normal shutdown or routine updates. ## 12. Troubleshooting ### Podman cannot connect Open Podman Desktop and start its Podman machine, then run: ```powershell podman info ``` ### The Compose provider is unavailable In Podman Desktop, open **Settings > Resources**. In the **Compose** tile, select **Setup**, then verify: ```powershell podman compose version ``` ### Compose says a required variable is missing Confirm that PowerShell is in the `deploy` directory and that `.env` exists: ```powershell Get-Location Test-Path ".env" ``` The file must define both `WEBACCESS_POSTGRES_PASSWORD` and `SEARXNG_SECRET`. Do not print secret values into shared terminal logs. ### A service exits during startup Inspect status and logs: ```powershell podman compose --project-name webaccess-mcp ps --all podman compose --project-name webaccess-mcp logs --tail 200 ``` Resolve the first unhealthy or failed dependency before troubleshooting downstream services. ### Port 28080 or 28081 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 switch SearXNG to port 18080; that port belongs to an unrelated deployment. ### PostgreSQL rejects the password If the PostgreSQL volume already exists, it retains the password used when it was created. Restore the original value in `.env`. If the original password is unavailable and losing cached pages is acceptable, use the intentional `down --volumes` reset described above. ### SearXNG is unhealthy Inspect its logs: ```powershell podman compose --project-name webaccess-mcp logs --tail 200 searxng ``` Confirm that `deploy\searxng\settings.yml` exists and that port 28080 is not occupied. ### WebAccess.MCP is not listening Inspect its logs and dependencies: ```powershell podman compose --project-name webaccess-mcp ps podman compose --project-name webaccess-mcp logs --tail 200 webaccess ``` PostgreSQL and SearXNG must be healthy. The host port test must succeed: ```powershell Test-NetConnection 127.0.0.1 -Port 28081 ``` ### Search providers return errors First verify the local SearXNG service and review logs: ```powershell Invoke-RestMethod "http://127.0.0.1:28080/config" | Out-Null podman compose --project-name webaccess-mcp logs --tail 200 searxng webaccess ``` Google, Brave, or DuckDuckGo can temporarily rate-limit requests or present anti-bot challenges. The stack does not bypass provider restrictions. ## Command Summary Run from `D:\ai\mcp\WebAccess.MCP\deploy`: ```powershell # Validate podman compose --project-name webaccess-mcp config --quiet # First build or rebuild podman compose --project-name webaccess-mcp up --detach --build # Status podman compose --project-name webaccess-mcp ps # Logs podman compose --project-name webaccess-mcp logs --tail 200 # Stop and start without removing containers podman compose --project-name webaccess-mcp stop podman compose --project-name webaccess-mcp start # Remove containers while preserving PostgreSQL data podman compose --project-name webaccess-mcp down # Destructive reset, including PostgreSQL data podman compose --project-name webaccess-mcp down --volumes ```