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.

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.
| What | Value (official sources, read 2026-11-16) |
|---|---|
| Current version | v0.1.0, released 25 October 2026 (previous release page: v0.0.48) |
| Images to pin | getmaxun/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) |
| Licence | AGPL-3.0-or-later (package.json at the tag); GitHub's detector shows AGPL-3.0 |
| Time needed | About 25 minutes (our estimate, not measured) |
| RAM and disk | Not documented. The Compose file limits the backend to 6 GB and the browser to 2 GB |
| Ports | 5173 (web app), 8080 (backend and API); browser 3001 and 3002 stay internal |
| Official docs | docs.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.
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#
| Item | Detail |
|---|---|
| OS | Linux, Windows 10/11 or macOS (Docker Desktop). The images list linux/amd64 and linux/arm64 |
| RAM | Not documented. The limits add up to 8 GB (backend plus browser); plan 8 GB free (our estimate) |
| Software | Docker Engine or Docker Desktop with Compose v2; openssl for the secrets (Linux and Mac only) |
On Linux and Mac:
docker --version docker compose version docker info openssl version
On Windows (PowerShell):
docker --version docker compose version docker info
Checklist:
- [ ] Docker running (
docker infoprints server details) - [ ] Ports 5173 and 8080 free on the machine
- [ ] A backup plan for your
.envfile (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#
mkdir -p ~/docker_volumes/maxun/{config,logs,backups}
cd ~/docker_volumes/maxun
docker pull minio/minio
Windows (PowerShell)#
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#
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:
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
.envnow. If you loseENCRYPTION_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/miniowith 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 forminio/minio, as it does for a repository that does not exist. We did not try a real pull. Ifdocker pull minio/minioin Step 1 failed, build it yourself (AGPL-3.0):git clone https://github.com/minio/minio.git, thendocker build -t myminio:minio minio, and useimage: myminio:miniobelow. This is the biggest open doubt in this guide.
Linux#
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:
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.2even though the app isv0.1.0. The browser image has its own tags (v0.0.1,v0.0.2); av0.1.0browser tag was not found.
Step 4: Start Maxun and check it#
Linux#
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)#
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:
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.
- Click Create Robot, choose Extract, and enter a page URL you are allowed to read.
- In Recorder Mode choose Capture List, Capture Text or Capture Screenshot, hover over the data and click it.
- Name the robot and save it. Run it, then open the run to see a table you can download.
- 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#
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:
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:
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:
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:
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 1fields.
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:
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.
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:
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:
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:
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.comproxying tomaxun-minio:9000) and setMINIO_PUBLIC_URL=https://storage.example.com(docs: no internal port appended). Issue #1033 reports exactly this.
Security and testing#
| Control | How |
|---|---|
| Trust boundary | Accounts are not isolated. Everyone who can log in sees all robots, runs and recordings (security policy). Keep Maxun private |
| Public sign-up | We found no switch to turn it off. Limit access with a firewall, a VPN or an access proxy |
| Ports | We 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 container | It 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 |
| Telemetry | Off 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 |
| Reporting | Security issues go to [email protected], not to public issues |
Quick tests:
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?#
| Tool | Best at | Pick it when |
|---|---|---|
| Maxun | Recording a page once, saved robots, schedules, a web UI | You want structured rows from known pages without writing a scraper |
| Firecrawl | An API that turns a URL into clean Markdown | Your language model or agent calls an API for page text |
| Crawl4AI | A Python library or Docker API for Markdown | You 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.
| Mistake | Why it happens | Do this instead |
|---|---|---|
Putting a $ in a secret | Compose reads $kLq7 as a variable. Issues #731 and #554 show The "kLq7" variable is not set | Generate secrets as in Step 2 (base64 and hex have no $), or double it as $$ |
Pinning all three images to v0.1.0, or leaving latest | The browser image has its own tags (v0.1.0 not found); the official file and upgrade page use latest | Backend and frontend v0.1.0, browser v0.0.2; change tags yourself |
| Changing only some URLs, or using a LAN address | Issue #554 shows net::ERR_CONNECTION_REFUSED on the register request; #534 changed only the public URLs to a device address | Set 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 app | Recording 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 nothing | Use the routing list in the HTTPS section |
| Screenshots missing | The browser must reach MinIO. #1033: images not shown when services have other addresses | Set MINIO_PUBLIC_URL behind a proxy |
| Publishing every port | The official file publishes PostgreSQL, MinIO, backend, frontend and browser to all interfaces | Bind to 127.0.0.1 as in Step 3 |
| Treating accounts as private from each other | The security policy says this edition is not multi-tenant | One trusted group per install |
| Updating with the docs' two lines | docker-compose pull backend frontend skips the browser, and the local-setup text says git pull origin master while the default branch is develop | Follow "Updates and backups" below |
docker compose down -v | -v deletes the named volumes with all robots and runs | Use down without -v |
| AI assistants: inventing settings | Answers 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 release | The 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
.envchange rundocker compose up -d --force-recreate; a plainrestartkeeps the old values.
Tip: Run
docker compose config --quietbefore every start. It catches YAML mistakes early without printing your secrets.
Troubleshooting#
| Problem | Solution |
|---|---|
| Register or login fails | Read 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 nothing | docker compose ps, then docker compose logs --tail=100 browser |
| AI Mode errors | Check the model name, the Step 6 test, or the provider key in Model settings |
| Robots disappeared | Check 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 fails | See the warning in Step 3 |
| Out of memory | docker 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.ADB_*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, orBROWSER_WS_HOSTis notbrowser.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. Runollama pull llama3.2on 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.
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:
#!/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:
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:
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:
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-streamwhile 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#
- Maxun v0.1.0 release, repository, docker-compose.yml, ENVEXAMPLE, generate-env.sh, nginx.conf, SECURITY.md, package.json, logo - read 2026-11-16
- Docker install, environment variables, production setup, upgrading, AI Mode, API, Cloud vs open source - read 2026-11-16
- Docker Hub tags: backend, frontend, browser; PostgreSQL and Caddy images - checked 2026-11-16
- MinIO repository README (no longer maintained) and Ollama FAQ - read 2026-11-16
- Maxun issues #306, #534, #554, #632, #707, #713, #731, #848, #919, #1033, #1238, #1268 - read 2026-11-16
Checked against the official docs on 2026-11-16.