webaccess-mcp/docs/Standing-Up-the-Podman-Comp...

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
```