15 KiB
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:
.\Start-WebAccessMcp.cmd
That command does the whole job:
- Checks that Podman is installed and running.
- Checks that Podman Compose is installed.
- Creates
deploy\.envwith random secrets if it does not exist. - Runs Compose with
up --detach --build. - Starts PostgreSQL, SearXNG, and WebAccess.MCP in dependency order.
- 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:
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
git clone <repository-url> WebAccess.MCP
Set-Location ".\WebAccess.MCP"
.\Start-WebAccessMcp.cmd
Replace <repository-url> with the repository URL supplied by the project
owner.
After the command succeeds:
-
In LM Studio, open Program > Install > Edit mcp.json.
-
Add this entry inside the existing
mcpServersobject:"webaccess": { "url": "http://127.0.0.1:28081/mcp" } -
Save
mcp.json. -
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:
D:\ai\mcp\WebAccess.MCP
Replace D: consistently if the AI folder is on another local drive.
Verify Podman and Compose:
podman info
podman compose version
Both commands must succeed.
1. Open the Deployment Directory
Open PowerShell and run:
$WebAccessRoot = "D:\ai\mcp\WebAccess.MCP"
$DeployRoot = Join-Path $WebAccessRoot "deploy"
Set-Location $DeployRoot
Verify the required deployment files:
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_PASSWORDSEARXNG_SECRET
The following manual procedure is needed only if the script cannot be used. Generate unique values for this installation:
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:
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:
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:
Set-Location ..
.\Start-WebAccessMcp.cmd
Alternatively, from the deploy directory run the PowerShell launcher directly:
.\Start-WebAccessStack.ps1
Or run Compose directly:
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:
- Pulls the PostgreSQL, SearXNG, .NET, and Playwright base images as needed.
- Builds the
webaccessimage from the repository source. - Creates the private network and PostgreSQL volume.
- Starts PostgreSQL and waits for it to become healthy.
- Starts SearXNG and waits for it to become healthy.
- Starts WebAccess.MCP.
The first build can take several minutes. Later builds generally reuse cached image layers.
5. Check Container Status
Run:
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:
Test-NetConnection 127.0.0.1 -Port 28080
Test-NetConnection 127.0.0.1 -Port 28081
Both results must include:
TcpTestSucceeded : True
Verify that the correct SearXNG instance is running:
(Invoke-RestMethod "http://127.0.0.1:28080/config").instance_name
Expected output:
WebAccess.MCP SearXNG
The MCP endpoint is:
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:
podman compose --project-name webaccess-mcp logs --tail 200
Show one service:
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:
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:
D:\ai\mcp\WebAccess.MCP\deploy
Stop without removing containers
podman compose --project-name webaccess-mcp stop
Start stopped containers
podman compose --project-name webaccess-mcp start
Restart all services
podman compose --project-name webaccess-mcp restart
Restart one service
podman compose --project-name webaccess-mcp restart webaccess
Remove containers and the private network
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
podman compose --project-name webaccess-mcp up --detach
9. Rebuild After a Source Update
After replacing the source or running git pull, execute:
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:
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:
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:
artifacts\
WebAccess.MCP-deployment-20260821-193000\
WebAccess.MCP\
.dockerignore
deploy\
docs\
src\
WebAccess.MCP.zip
The script:
- Builds the production container image with Podman.
- Copies only the production source and required Compose/container files.
- Excludes
bin,obj, tests, TestRig files, IDE files, Git metadata, anddeploy\.env. - Includes the startup script and operator documentation.
- Creates a ZIP suitable for uploading or transferring.
To choose the output folder:
.\Export-WebAccessDeployment.ps1 `
-DestinationPath "D:\release\WebAccess.MCP"
This also creates:
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:
.\Export-WebAccessDeployment.ps1 `
-DestinationPath "D:\release\WebAccess.MCP" `
-NoArchive
To package without building the image first:
.\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:
<drive>:\ai\mcp\WebAccess.MCP
Then run:
Set-Location "<drive>:\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:
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:
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:
podman info
The Compose provider is unavailable
In Podman Desktop, open Settings > Resources. In the Compose tile, select Setup, then verify:
podman compose version
Compose says a required variable is missing
Confirm that PowerShell is in the deploy directory and that .env exists:
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:
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:
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:
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:
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:
Test-NetConnection 127.0.0.1 -Port 28081
Search providers return errors
First verify the local SearXNG service and review logs:
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:
# 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