625 lines
15 KiB
Markdown
625 lines
15 KiB
Markdown
# 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 <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:
|
|
|
|
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
|
|
<drive>:\ai\mcp\WebAccess.MCP
|
|
```
|
|
|
|
Then run:
|
|
|
|
```powershell
|
|
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:
|
|
|
|
```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
|
|
```
|