DockerSelf-HostingAI

Maxun with Docker: No-Code Web Data Extraction You Host Yourself (Linux, Windows, Mac)

Before you start

  • 22 min read

Boxes marked Run in terminal are what you type; plain text explains why. Check what you need first

What you get in one minute#

Maxun is an open-source web data platform: you record what you do on a web page once, and it saves that as a reusable "robot" that extracts the same data again on demand, on a schedule or through an API. You can also describe the data in plain words (AI Mode) and let a language model build the robot.

Maxun official logo

Logo: the official Maxun project (github.com/getmaxun/maxun)

It suits price lists, job boards, article details, or a page you want to watch for changes. Nothing here needs a cloud account. The project also sells a Cloud edition; this guide covers the free self-hosted one.

WhatValue (official sources, read 2026-11-16)
Current versionv0.1.0, released 25 October 2026 (previous release page: v0.0.48)
Images to pingetmaxun/maxun-backend:v0.1.0, getmaxun/maxun-frontend:v0.1.0, getmaxun/maxun-browser:v0.0.2 (the browser image has its own version numbers)
LicenceAGPL-3.0-or-later (package.json at the tag); GitHub's detector shows AGPL-3.0
Time neededAbout 25 minutes (our estimate, not measured)
RAM and diskNot documented. The Compose file limits the backend to 6 GB and the browser to 2 GB
Ports5173 (web app), 8080 (backend and API); browser 3001 and 3002 stay internal
Official docsdocs.maxun.dev and github.com/getmaxun/maxun

At a glance:

  • Five containers: PostgreSQL, MinIO (file storage), backend, frontend and a Chromium browser container. No Redis container, no model server.
  • Robot styles: Recorder Mode (you click), AI Mode (you describe), plus scrape and crawl robots.
  • Built for trusted use: the security policy says this edition does not separate users from each other.
  • Open-core: Cloud adds Deep Extraction, anti-bot proxies, captcha bypass and teams.
  • One risk to know first: the official file uses a MinIO image that may no longer be pullable (Step 3).

How it fits together#

You use the web app; the backend stores robots and runs in PostgreSQL, keeps screenshots in MinIO, and drives a separate Chromium container that loads the target site.

Diagram: your browser reaches Caddy or Traefik over HTTPS (optional) and then the Maxun frontend on port 5173; the frontend calls the backend on port 8080; the backend stores robots and runs in PostgreSQL, files in MinIO, and controls the browser container that loads the target website; an optional Ollama or cloud model builds AI Mode robots

Drawn for this guide from the official Compose file and docs. The release has no Redis container, although some docs pages still mention Redis.

Before you start#

ItemDetail
OSLinux, Windows 10/11 or macOS (Docker Desktop). The images list linux/amd64 and linux/arm64
RAMNot documented. The limits add up to 8 GB (backend plus browser); plan 8 GB free (our estimate)
SoftwareDocker Engine or Docker Desktop with Compose v2; openssl for the secrets (Linux and Mac only)

On Linux and Mac:

Run in terminalbash
docker --version
docker compose version
docker info
openssl version

On Windows (PowerShell):

Run in terminalpowershell
docker --version
docker compose version
docker info

Checklist:

  • [ ] Docker running (docker info prints server details)
  • [ ] Ports 5173 and 8080 free on the machine
  • [ ] A backup plan for your .env file (it holds the encryption key)
  • [ ] For the HTTPS section only: a domain with DNS and ports 80 and 443

Tested by DIY Lab Hub: not yet. Commands come from the official Compose file, docs and source read on 2026-11-16; we did not run them.

Tip: A laptop that sleeps pauses your schedules. Pick an always-on machine with spare RAM for Chromium.

Use it responsibly#

Maxun loads pages like a person does, yet automatic reading can still break a site's terms, ignore its robots.txt or overload it. The docs we read do not say that Maxun checks robots.txt, so you do. Read the terms, keep runs few and slow, prefer an official API or export when one exists, and never collect personal data you have no right to hold.

Step 1: Create the project folder#

Everything lives in ~/docker_volumes/maxun: the Compose file, .env and backups. PostgreSQL and MinIO keep their data in Docker named volumes, as the official file does, because PostgreSQL on a Windows drive commonly fails with permission errors.

Linux#

Run in terminalbash
mkdir -p ~/docker_volumes/maxun/{config,logs,backups}
cd ~/docker_volumes/maxun
docker pull minio/minio

Windows (PowerShell)#

Codepowershell
New-Item -ItemType Directory -Force "$HOME\docker_volumes\maxun\config", "$HOME\docker_volumes\maxun\logs", "$HOME\docker_volumes\maxun\backups" | Out-Null
Set-Location "$HOME\docker_volumes\maxun"
docker pull minio/minio

Mac (Terminal)#

Same commands as Linux.

Check it worked. The folder exists. The docker pull minio/minio line tests the one image the official file leaves unpinned; see the warning in Step 3 if it fails.

Step 2: Create the .env file with fresh secrets#

The release ships an example file (ENVEXAMPLE) and a Bash generator. We create the same settings ourselves. The docs ask for unique random values for JWT_SECRET, SESSION_SECRET and ENCRYPTION_KEY (64 hex characters). Never use a $ in a value: Compose treats it as a variable and silently drops it.

Linux#

Run in terminalbash
cd ~/docker_volumes/maxun
cat > .env <<EOF
NODE_ENV=production
JWT_SECRET=$(openssl rand -base64 48)
SESSION_SECRET=$(openssl rand -base64 48)
ENCRYPTION_KEY=$(openssl rand -hex 32)
DB_NAME=maxun
DB_USER=postgres
DB_PASSWORD=$(openssl rand -base64 24)
DB_HOST=postgres
DB_PORT=5432
MINIO_ENDPOINT=minio
MINIO_PORT=9000
MINIO_CONSOLE_PORT=9001
MINIO_ACCESS_KEY=minio
MINIO_SECRET_KEY=$(openssl rand -base64 24)
REDIS_HOST=maxun-redis
REDIS_PORT=6379
REDIS_PASSWORD=
BACKEND_PORT=8080
FRONTEND_PORT=5173
BACKEND_URL=http://localhost:8080
PUBLIC_URL=http://localhost:5173
VITE_BACKEND_URL=http://localhost:8080
VITE_PUBLIC_URL=http://localhost:5173
BROWSER_WS_HOST=browser
BROWSER_WS_PORT=3001
BROWSER_HEALTH_PORT=3002
MAXUN_TELEMETRY=false
EOF
chmod 600 .env

Windows (PowerShell)#

The official generator is a Bash script; the docs point Windows users to WSL or Git Bash. This PowerShell version is our own, not from Maxun:

Codepowershell
Set-Location "$HOME\docker_volumes\maxun"
function New-Secret([int]$Bytes, [string]$Kind) {
  $b = New-Object byte[] $Bytes
  [System.Security.Cryptography.RandomNumberGenerator]::Create().GetBytes($b)
  if ($Kind -eq 'hex') { ([BitConverter]::ToString($b) -replace '-', '').ToLower() } else { [Convert]::ToBase64String($b) }
}
$text = @"
NODE_ENV=production
JWT_SECRET=$(New-Secret 48 'b64')
SESSION_SECRET=$(New-Secret 48 'b64')
ENCRYPTION_KEY=$(New-Secret 32 'hex')
DB_NAME=maxun
DB_USER=postgres
DB_PASSWORD=$(New-Secret 24 'b64')
DB_HOST=postgres
DB_PORT=5432
MINIO_ENDPOINT=minio
MINIO_PORT=9000
MINIO_CONSOLE_PORT=9001
MINIO_ACCESS_KEY=minio
MINIO_SECRET_KEY=$(New-Secret 24 'b64')
REDIS_HOST=maxun-redis
REDIS_PORT=6379
REDIS_PASSWORD=
BACKEND_PORT=8080
FRONTEND_PORT=5173
BACKEND_URL=http://localhost:8080
PUBLIC_URL=http://localhost:5173
VITE_BACKEND_URL=http://localhost:8080
VITE_PUBLIC_URL=http://localhost:5173
BROWSER_WS_HOST=browser
BROWSER_WS_PORT=3001
BROWSER_HEALTH_PORT=3002
MAXUN_TELEMETRY=false
"@
[System.IO.File]::WriteAllText("$PWD\.env", (($text + "`n") -replace "`r`n", "`n"), (New-Object System.Text.UTF8Encoding $false))

Mac (Terminal)#

Same commands as Linux (macOS openssl supports rand -base64 and rand -hex).

Check it worked. Only one line may end with =, the empty REDIS_PASSWORD. Linux and Mac: grep -c '=$' .env prints 1. Windows: (Select-String -Path .env -Pattern '=$').Count prints 1. Do not print the file on a shared screen.

The REDIS_* lines come from the official generator; the release has no Redis container, so they are unused.

Tip: Back up .env now. If you lose ENCRYPTION_KEY, the data Maxun encrypted (saved passwords and proxies, per the example file) cannot be read again.

Step 3: Write the Compose file#

This is the official docker-compose.yml from the v0.1.0 tag with our changes: Maxun's three images pinned (the official file says latest), PostgreSQL 17 as in the official production guide (the main file's 13 stopped getting fixes in November 2025), the web app, backend and MinIO bound to 127.0.0.1, no published ports for PostgreSQL and the browser, and container_name lines for the proxy examples.

Warning: The official file uses minio/minio with no tag. MinIO's repository now says "THIS REPOSITORY IS NO LONGER MAINTAINED" and its README says to build the image from source. On 2026-11-16 Docker Hub's public API answered 404 for minio/minio, as it does for a repository that does not exist. We did not try a real pull. If docker pull minio/minio in Step 1 failed, build it yourself (AGPL-3.0): git clone https://github.com/minio/minio.git, then docker build -t myminio:minio minio, and use image: myminio:minio below. This is the biggest open doubt in this guide.

Linux#

Run in terminalbash
cd ~/docker_volumes/maxun
cat > docker-compose.yml <<'EOF'
name: maxun

services:
  postgres:
    image: postgres:17
    container_name: maxun-postgres
    restart: unless-stopped
    environment:
      POSTGRES_USER: ${DB_USER}
      POSTGRES_PASSWORD: ${DB_PASSWORD}
      POSTGRES_DB: ${DB_NAME}
    volumes:
      - postgres_data:/var/lib/postgresql/data
    healthcheck:
      test: ["CMD-SHELL", "pg_isready -U postgres"]
      interval: 10s
      timeout: 5s
      retries: 5

  minio:
    image: minio/minio
    container_name: maxun-minio
    restart: unless-stopped
    environment:
      MINIO_ROOT_USER: ${MINIO_ACCESS_KEY}
      MINIO_ROOT_PASSWORD: ${MINIO_SECRET_KEY}
    command: server /data --console-address :${MINIO_CONSOLE_PORT:-9001}
    ports:
      - "127.0.0.1:${MINIO_PORT:-9000}:${MINIO_PORT:-9000}"
    volumes:
      - minio_data:/data

  backend:
    image: getmaxun/maxun-backend:v0.1.0
    container_name: maxun-backend
    restart: unless-stopped
    ports:
      - "127.0.0.1:${BACKEND_PORT:-8080}:${BACKEND_PORT:-8080}"
    env_file: .env
    environment:
      BACKEND_URL: ${BACKEND_URL}
      PLAYWRIGHT_BROWSERS_PATH: /ms-playwright
      PLAYWRIGHT_SKIP_BROWSER_DOWNLOAD: 0
      CI: "true"
      CONTAINER: "true"
      CHROMIUM_FLAGS: '--disable-gpu --no-sandbox --headless=new'
      OLLAMA_BASE_URL: ${OLLAMA_BASE_URL:-http://host.docker.internal:11434}
    extra_hosts:
      - "host.docker.internal:host-gateway"
    security_opt:
      - seccomp=unconfined
    shm_size: '2gb'
    mem_limit: 6g
    depends_on:
      - postgres
      - minio
    volumes:
      - /var/run/dbus:/var/run/dbus

  frontend:
    image: getmaxun/maxun-frontend:v0.1.0
    container_name: maxun-frontend
    restart: unless-stopped
    ports:
      - "127.0.0.1:${FRONTEND_PORT:-5173}:${FRONTEND_PORT:-5173}"
    env_file: .env
    environment:
      PUBLIC_URL: ${PUBLIC_URL}
      BACKEND_URL: ${BACKEND_URL}
    depends_on:
      - backend

  browser:
    image: getmaxun/maxun-browser:v0.0.2
    container_name: maxun-browser
    restart: unless-stopped
    environment:
      - NODE_ENV=production
      - DEBUG=pw:browser*
      - BROWSER_WS_PORT=${BROWSER_WS_PORT:-3001}
      - BROWSER_HEALTH_PORT=${BROWSER_HEALTH_PORT:-3002}
      - BROWSER_WS_HOST=${BROWSER_WS_HOST:-browser}
      - PLAYWRIGHT_BROWSERS_PATH=/ms-playwright
    healthcheck:
      test: ["CMD", "curl", "-f", "http://localhost:${BROWSER_HEALTH_PORT:-3002}/health"]
      interval: 10s
      timeout: 5s
      retries: 3
      start_period: 10s
    deploy:
      resources:
        limits:
          memory: 2G
          cpus: '1.5'
        reservations:
          memory: 1G
          cpus: '1.0'
    security_opt:
      - seccomp:unconfined
    shm_size: 2gb
    cap_add:
      - SYS_ADMIN

volumes:
  postgres_data:
  minio_data:
EOF
docker compose config --quiet && echo "compose file OK"

Windows (PowerShell)#

Save the same YAML as docker-compose.yml in $HOME\docker_volumes\maxun (for example notepad docker-compose.yml, paste, save as UTF-8). Then check it:

Run in terminalpowershell
docker compose config --quiet
if ($?) { "compose file OK" }

The /var/run/dbus line is a Linux host path, and we found no tested Windows route for it. If Docker Desktop refuses to start the backend because of it, delete that mount (the volumes: block under backend).

Mac (Terminal)#

Same file and commands as Linux. The D-Bus note applies here too; we did not test a Mac.

Check it worked. docker compose config --quiet prints nothing and compose file OK appears. That proves the YAML is valid, not that the stack runs. Never paste plain docker compose config output anywhere: it contains your secrets.

Tip: Keep the browser image on v0.0.2 even though the app is v0.1.0. The browser image has its own tags (v0.0.1, v0.0.2); a v0.1.0 browser tag was not found.

Step 4: Start Maxun and check it#

Linux#

Run in terminalbash
cd ~/docker_volumes/maxun
docker compose pull
docker compose up -d
docker compose ps
curl --fail http://localhost:8080/
docker compose exec browser curl -f http://localhost:3002/health

Windows (PowerShell)#

Codepowershell
Set-Location "$HOME\docker_volumes\maxun"
docker compose pull
docker compose up -d
docker compose ps
curl.exe --fail http://localhost:8080/
docker compose exec browser curl -f http://localhost:3002/health

Mac (Terminal)#

Same commands as Linux.

Check it worked. Wait about 30 seconds (the official production guide says so). docker compose ps shows five containers, and the browser reports healthy. From the source (expected, not captured by us): the backend root route answers Maxun server started, the browser /health returns JSON with "status":"healthy" and a changing WebSocket address, and the backend log shows Database connected successfully and Server listening on port 8080:

Run in terminalbash
docker compose logs --tail=50 backend

Step 5: Create your account and your first robot#

Open http://localhost:5173. We found no default admin account or setup wizard: register with an email and a password of at least 6 characters, then log in.

  1. Click Create Robot, choose Extract, and enter a page URL you are allowed to read.
  2. In Recorder Mode choose Capture List, Capture Text or Capture Screenshot, hover over the data and click it.
  3. Name the robot and save it. Run it, then open the run to see a table you can download.
  4. Add a schedule (see the Schedule page in the docs), or create an API key in the dashboard to run it from code.

The open-source API base is your backend URL plus /api, and the header is x-api-key. Per the docs a call without a key returns 401 and a wrong key returns 403. The backend also serves an interactive reference at http://localhost:8080/api-docs.

Linux#

Run in terminalbash
curl -H "x-api-key: <YOUR_API_KEY>" http://localhost:8080/api/robots

Windows (PowerShell)#

The UI steps are the same in any browser. For the API call use curl.exe:

Run in terminalpowershell
curl.exe -H "x-api-key: <YOUR_API_KEY>" http://localhost:8080/api/robots

Mac (Terminal)#

Same command as Linux.

Check it worked. The run shows rows of data and no error. A recorded click that does nothing is the first sign of the proxy or browser problems in Troubleshooting.

Tip: Start with a plain static page. Logins, cookie banners and endless scrolling are harder, and the self-hosted edition has no anti-bot help.

Step 6 (optional): AI Mode with a local Ollama#

AI Mode turns a URL and a sentence ("the first 20 product names and prices") into a saved robot. The model is needed only to build the robot; later runs reuse it, per the docs. Providers are Anthropic, OpenAI (or an OpenAI-compatible server, with a base URL) and Ollama. Setting OLLAMA_BASE_URL to https://ollama.com uses Ollama's cloud, so that is not local.

Linux#

Install Ollama from ollama.com and pull the model the docs use:

Run in terminalbash
ollama pull llama3.2

Inside the backend container localhost is the container itself, so the Compose file maps host.docker.internal to the host. Ollama listens on 127.0.0.1 by default, so on Linux set OLLAMA_HOST as the Ollama FAQ describes: systemctl edit ollama.service, add Environment="OLLAMA_HOST=0.0.0.0:11434", then systemctl daemon-reload and systemctl restart ollama. Ollama has no login, so firewall port 11434 from the rest of your network. Add the settings, recreate the backend and test:

Run in terminalbash
echo 'OLLAMA_BASE_URL=http://host.docker.internal:11434' >> .env
echo 'OLLAMA_MODEL=llama3.2' >> .env
docker compose up -d --force-recreate backend
docker compose exec backend node -e "fetch('http://host.docker.internal:11434/api/tags').then(r=>console.log(r.status))"

Windows (PowerShell)#

Install the Ollama app, run ollama pull llama3.2, then:

Codepowershell
Add-Content .env "OLLAMA_BASE_URL=http://host.docker.internal:11434"
Add-Content .env "OLLAMA_MODEL=llama3.2"
docker compose up -d --force-recreate backend
docker compose exec backend node -e "fetch('http://host.docker.internal:11434/api/tags').then(r=>console.log(r.status))"

If refused, set the user variable OLLAMA_HOST as the Ollama FAQ describes for Windows and restart Ollama. Not tested.

Mac (Terminal)#

Same .env and test commands as Linux, with the Ollama app. If refused, the FAQ's Mac route is launchctl setenv OLLAMA_HOST "0.0.0.0:11434" and an Ollama restart. Not tested.

Then open Create Robot, Extract, switch to AI Mode, open Model settings, and pick Ollama and your model.

Check it worked. The test prints 200, and AI Mode creates a robot with real field names.

Tip: Name a model yourself in Model settings. With a hosted provider and the model left blank, an open issue reports HTTP 400 errors and generic Label 1 fields.

Put it behind HTTPS (with or without Traefik)#

This is for a server with a domain; local-only users can skip it. Both routes use one hostname. The backend gets these paths (with WebSockets) and the web app gets everything else: /auth, /storage, /record, /workflow, /robot, /proxy, /api-docs, /api, /webhook, /socket.io (from the official nginx.conf). A proxy that sends everything to port 5173 shows the login page but breaks recording.

Set all four URLs in .env to the same HTTPS address, and recreate the stack after the proxy is in place:

File contenttext
BACKEND_URL=https://maxun.<your-domain>
VITE_BACKEND_URL=https://maxun.<your-domain>
PUBLIC_URL=https://maxun.<your-domain>
VITE_PUBLIC_URL=https://maxun.<your-domain>

Create the shared network once with docker network create proxy. Sub-path hosting (/maxun/) is not covered by the official routes. Related: Caddy reverse proxy.

With Traefik#

For a server that already runs Traefik v3 with the Docker provider and an https entrypoint. Save this as docker-compose.override.yml next to the main file (Compose merges it automatically). Inside labels, $ must be doubled.

File contentyaml
services:
  frontend:
    networks: [default, proxy]
    labels:
      - "traefik.enable=true"
      - "traefik.docker.network=proxy"
      - "traefik.http.routers.maxun-ui.rule=Host(`maxun.<your-domain>`)"
      - "traefik.http.routers.maxun-ui.entrypoints=https"
      - "traefik.http.routers.maxun-ui.tls=true"
      - "traefik.http.services.maxun-ui.loadbalancer.server.port=5173"
  backend:
    networks: [default, proxy]
    labels:
      - "traefik.enable=true"
      - "traefik.docker.network=proxy"
      - "traefik.http.routers.maxun-api.rule=Host(`maxun.<your-domain>`) && PathRegexp(`^/(auth|storage|record|workflow|robot|proxy|api-docs|api|webhook|socket.io)(/|$$)`)"
      - "traefik.http.routers.maxun-api.priority=100"
      - "traefik.http.routers.maxun-api.entrypoints=https"
      - "traefik.http.routers.maxun-api.tls=true"
      - "traefik.http.services.maxun-api.loadbalancer.server.port=8080"

networks:
  proxy:
    external: true

Run docker compose up -d. A community Traefik walkthrough exists (issue #919); we found no official labels, so these follow the official routing list and are not tested.

Check it worked. curl -I https://maxun.<your-domain>/ returns an HTTP status over HTTPS.

Without Traefik: Caddy#

Caddy gets and renews Let's Encrypt certificates for a public domain by itself. First attach Maxun to the shared network with this docker-compose.override.yml:

File contentyaml
services:
  frontend:
    networks: [default, proxy]
  backend:
    networks: [default, proxy]

networks:
  proxy:
    external: true

Then create the Caddy folder (we mount the conf folder, not one file) and its Compose file:

Run in terminalbash
mkdir -p ~/docker_volumes/caddy/{conf,data,config}
cd ~/docker_volumes/caddy
cat > docker-compose.yml <<'EOF'
services:
  caddy:
    image: caddy:2.11.9
    container_name: caddy
    restart: unless-stopped
    ports:
      - "80:80/tcp"
      - "443:443/tcp"
      - "443:443/udp"
    volumes:
      - ./conf:/etc/caddy:ro
      - ./data:/data
      - ./config:/config
    networks:
      - proxy

networks:
  proxy:
    external: true
EOF

Caddy 2.11.9 is the latest release we read, and the caddy:2.11.9 image exists on Docker Hub. Save this as ~/docker_volumes/caddy/conf/Caddyfile for a public domain:

File contenttext
maxun.example.com {
    @backend path_regexp ^/(auth|storage|record|workflow|robot|proxy|api-docs|api|webhook|socket\.io)(/|$)
    handle @backend {
        reverse_proxy maxun-backend:8080
    }
    handle {
        reverse_proxy maxun-frontend:5173
    }
}

At home with no public domain, add tls internal inside the block and use a local name such as maxun.home.arpa. Caddy then signs with its own root, which each device must trust; the steps are in our wg-easy guide. A local certificate is enough; no tunnel service is needed. Start both stacks with docker compose up -d in each folder. This works the same with Docker Desktop on Windows or Mac, but Let's Encrypt needs a public domain pointing at that machine.

Check it worked. curl -I https://maxun.example.com/ returns an HTTP status line over HTTPS.

Tip: Screenshots are served from MinIO, and behind a proxy they may not show. Add a second host (for example storage.example.com proxying to maxun-minio:9000) and set MINIO_PUBLIC_URL=https://storage.example.com (docs: no internal port appended). Issue #1033 reports exactly this.

Security and testing#

ControlHow
Trust boundaryAccounts are not isolated. Everyone who can log in sees all robots, runs and recordings (security policy). Keep Maxun private
Public sign-upWe found no switch to turn it off. Limit access with a firewall, a VPN or an access proxy
PortsWe bound the web app, backend and MinIO to 127.0.0.1. Never publish 5432, 3001, 3002 or 9001. The browser health reply reveals the browser's WebSocket address
Browser containerIt runs with SYS_ADMIN and unconfined seccomp, and Chromium without its sandbox. Treat every page it opens as untrusted
Secrets.env is chmod 600; never commit it
TelemetryOff in our file. With MAXUN_TELEMETRY=true the source sends events to PostHog (us.i.posthog.com) that include your email on registration and login
ReportingSecurity issues go to [email protected], not to public issues

Quick tests:

Run in terminalbash
docker compose ps
docker compose logs --tail=100 backend
docker compose exec browser curl -f http://localhost:3002/health

An open issue (#1268, October 2026) reports that the published browser image ships an older Node.js that lacks a fix released on 21 October 2026. We could not check the image. Keep the browser container off the open internet.

Maxun, Firecrawl or Crawl4AI?#

ToolBest atPick it when
MaxunRecording a page once, saved robots, schedules, a web UIYou want structured rows from known pages without writing a scraper
FirecrawlAn API that turns a URL into clean MarkdownYour language model or agent calls an API for page text
Crawl4AIA Python library or Docker API for MarkdownYou code in Python and want control of the crawl

Maxun also has scrape and crawl robots that return Markdown, so the lines blur. We did not benchmark them.

Common mistakes#

These come from the official files, Maxun's issue tracker and assistant answers. Old issues are not always bugs in v0.1.0.

MistakeWhy it happensDo this instead
Putting a $ in a secretCompose reads $kLq7 as a variable. Issues #731 and #554 show The "kLq7" variable is not setGenerate secrets as in Step 2 (base64 and hex have no $), or double it as $$
Pinning all three images to v0.1.0, or leaving latestThe browser image has its own tags (v0.1.0 not found); the official file and upgrade page use latestBackend and frontend v0.1.0, browser v0.0.2; change tags yourself
Changing only some URLs, or using a LAN addressIssue #554 shows net::ERR_CONNECTION_REFUSED on the register request; #534 changed only the public URLs to a device addressSet all four URLs to the address your browser really uses, and keep the default ports
Moving DB_PORT#306 and #554 hit busy or changed database ports. The official file maps one number on both sides, yet PostgreSQL listens on 5432 inside (our reading)Do not publish PostgreSQL; keep DB_PORT=5432
Proxying only the web appRecording needs the backend paths and WebSockets. #707 (backend on a sub-path behind a proxy) shows No browser found for user: 1; #632 shows capture buttons doing nothingUse the routing list in the HTTPS section
Screenshots missingThe browser must reach MinIO. #1033: images not shown when services have other addressesSet MINIO_PUBLIC_URL behind a proxy
Publishing every portThe official file publishes PostgreSQL, MinIO, backend, frontend and browser to all interfacesBind to 127.0.0.1 as in Step 3
Treating accounts as private from each otherThe security policy says this edition is not multi-tenantOne trusted group per install
Updating with the docs' two linesdocker-compose pull backend frontend skips the browser, and the local-setup text says git pull origin master while the default branch is developFollow "Updates and backups" below
docker compose down -v-v deletes the named volumes with all robots and runsUse down without -v
AI assistants: inventing settingsAnswers mention one getmaxun/maxun:latest image, .env.example, port 3000, ADMIN_PASSWORD, DISABLE_SIGNUP, an OPENAI_BASE_URL setting, a Redis container or API base /api/v1. We found none of these for this releaseThe file is ENVEXAMPLE, the ports are 5173 and 8080, the API base is BACKEND_URL plus /api, and there is no Redis container

Tip: After any .env change run docker compose up -d --force-recreate; a plain restart keeps the old values.

Tip: Run docker compose config --quiet before every start. It catches YAML mistakes early without printing your secrets.

Troubleshooting#

ProblemSolution
Register or login failsRead the request URL in the browser's network tab and match it to BACKEND_URL; then docker compose logs --tail=100 backend
Recorder opens, then nothingdocker compose ps, then docker compose logs --tail=100 browser
AI Mode errorsCheck the model name, the Step 6 test, or the provider key in Model settings
Robots disappearedCheck the project name is maxun with docker volume ls. Issue #848 reports this without a confirmed cause. Restore from a backup
Pull of the MinIO image failsSee the warning in Step 3
Out of memorydocker inspect maxun-backend --format '{{.State.OOMKilled}}', then lower WORKER_CONCURRENCY (source default 10)

Exact messages and what they mean:

  • The "kLq7" variable is not set. Defaulting to a blank string. A $ in .env (issues #731, #554). Regenerate the secrets.
  • One or more required environment variables are missing. A DB_* variable is missing or empty. Compare with Step 2.
  • Browser service is not accessible at http://browser:3002/health. Make sure the browser service is running (docker-compose up browser). The browser container is down, or BROWSER_WS_HOST is not browser.
  • Health check did not return a valid wsEndpoint. The browser answered but was not healthy yet. Wait and read its log.
  • Could not launch local browser. The backend's fallback after the error above. Fix the browser service; do not install Chromium in the backend.
  • model 'llama3.2' not found. Run ollama pull llama3.2 on the server Maxun points to.

Known bugs#

  • #1238 (open): AI Mode with the model left blank. A later comment says the Anthropic problem is fixed in v0.1.0, while the OpenAI default model still returns HTTP 400. Choose the model by hand.
  • #1268 (open): the browser image's Node.js version, see Security.
  • #713 and #848 (open): backend crashes during runs, and vanishing robots. No fix found.

Diagnostics: docker compose ps -a, docker compose logs --tail=200 backend, docker compose exec browser node --version.

Updates and backups#

The docs' upgrade page assumes latest tags. With pinned tags the order is: back up, read the release notes, edit the three tags, pull, recreate, test. We found no wave of breakage reports for v0.1.0. The previous release page is v0.0.48, but image tags do not match release numbers (the backend jumps from v0.0.64 to v0.1.0), so we name no rollback pin. Write down your old tags and roll back with the backup.

Run in terminalbash
cd ~/docker_volumes/maxun
./backup.sh
docker compose pull
docker compose up -d
docker compose logs --tail=100 backend

v0.1.0 changed saved-data JSON field names to snake_case and rebuilt AI Mode, so test your API consumers after upgrading. Never switch an existing PostgreSQL volume from 13 to 17 by only changing the tag; a major-version change needs a dump and restore.

Save this as ~/docker_volumes/maxun/backup.sh and run chmod +x backup.sh:

File contentbash
#!/usr/bin/env bash
set -euo pipefail
cd ~/docker_volumes/maxun
D=backups/$(date +%F)
mkdir -p "$D"
docker compose exec -T postgres sh -c 'pg_dump -U "$POSTGRES_USER" -d "$POSTGRES_DB" -Fc -f /tmp/maxun.dump'
docker compose cp postgres:/tmp/maxun.dump "$D/maxun.dump"
docker compose stop minio
docker compose cp minio:/data "$D/minio-data"
docker compose start minio
cp .env docker-compose.yml "$D/"
chmod -R go-rwx "$D"

These are standard PostgreSQL and Docker commands; the Maxun docs give no backup procedure. On Linux or Mac, schedule it with crontab -e and 0 3 * * * ~/docker_volumes/maxun/backup.sh. Copy backups/ to another machine too.

Windows (PowerShell)#

Save this as $HOME\docker_volumes\maxun\backup.ps1:

Codepowershell
Set-Location "$HOME\docker_volumes\maxun"
$d = "backups\" + (Get-Date -Format yyyy-MM-dd)
New-Item -ItemType Directory -Force $d | Out-Null
docker compose exec -T postgres sh -c 'pg_dump -U "$POSTGRES_USER" -d "$POSTGRES_DB" -Fc -f /tmp/maxun.dump'
docker compose cp postgres:/tmp/maxun.dump "$d\maxun.dump"
docker compose stop minio
docker compose cp minio:/data "$d\minio-data"
docker compose start minio
Copy-Item .env, docker-compose.yml $d

Run this once to schedule it for 03:00 every day with Task Scheduler:

Run in terminalpowershell
schtasks /Create /SC DAILY /ST 03:00 /TN "Maxun backup" /TR "powershell -File $HOME\docker_volumes\maxun\backup.ps1"

Mac (Terminal)#

Same script and crontab line as Linux (macOS may ask for permission to run cron jobs).

Restore test. Restore the newest dump into a throwaway database, never over the live one:

Run in terminalbash
docker compose cp backups/<date>/maxun.dump postgres:/tmp/restore.dump
docker compose exec -T postgres sh -c 'createdb -U "$POSTGRES_USER" restore_test && pg_restore -U "$POSTGRES_USER" -d restore_test --no-owner /tmp/restore.dump && psql -U "$POSTGRES_USER" -d restore_test -c "\dt"'
docker compose exec -T postgres sh -c 'dropdb -U "$POSTGRES_USER" restore_test'

The table list should show Maxun's tables. A real recovery also needs the MinIO copy and your .env.

Performance and resources#

The docs publish no RAM or CPU figures. The Compose limits are: backend 6 GB, browser 2 GB (1 GB reserved, 1.5 CPUs), and 2 GB shared memory each. They are limits, not measured use. The v0.1.0 notes report the project's own benchmarks (scraping 2.5 s down to 0.63 s, crawling 411 s down to 96 s), not your hardware.

  • Measure yourself: run docker stats --no-stream while one robot runs, then while two run.
  • Concurrency: WORKER_CONCURRENCY (default 10, at least 1) comes from the source, not the docs. Lower it on a small host.
  • Logs: the browser container runs with DEBUG=pw:browser*, which is chatty.

FAQ#

Is Maxun free? The self-hosted edition is free under AGPL-3.0-or-later. If you change it and offer it to others over a network, you must share your changes. Cloud adds paid features such as Deep Extraction and managed proxies.

Does it need a GPU or a cloud model? No GPU. Recorder Mode needs no model. AI Mode needs one you configure.

Can I run it on a Raspberry Pi? The images list arm64, but we found no tested Pi guide, and the memory limits suggest a small board is tight.

Can I turn off public sign-up? We found no setting. Keep Maxun on a private network, or behind a proxy that limits who reaches it.

Is it safe to expose to the internet? The project says it is for trusted environments. If you must, use HTTPS plus a network-level gate, not just a password.

Sources#

Checked against the official docs on 2026-11-16.