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

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:

  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:

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:

  1. In LM Studio, open Program > Install > Edit mcp.json.

  2. Add this entry inside the existing mcpServers object:

    "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:

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_PASSWORD
  • SEARXNG_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:

  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:

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:

  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:

.\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