MiroFish Docker Deployment Guide 2026: Compose, .env Keys & Remote Access

This MiroFish Docker deployment guide walks from zero to a running UI on ports 3000 and 5001 using the official 666ghj/MiroFish Compose file. If the UI loads but API calls fail remotely, use our MiroFish Network Error & VITE_API_BASE_URL fix—this article focuses on install, .env keys, and first-project smoke tests. Related: SSH remote access, short-term node selection, OpenClaw deployment on Mac mini M4.

Disclosure: VpsGona is the Mac rental provider mentioned for optional cloud Mac hosting. MiroFish is an independent open-source project; steps follow the official GitHub repository.

What MiroFish runs in Docker

Quotable: One Compose service (ghcr.io/666ghj/mirofish:latest) bundles frontend + backend, reads env_file: .env, publishes 3000:3000 and 5001:5001, and mounts ./backend/uploads for persistence.

Prerequisites

• Docker Engine 24+ and Compose v2 (docker compose version)
• 4 GB+ RAM for LLM + graph workloads on small VPS
• Outbound HTTPS to your LLM endpoint and Zep Cloud (free tier covers light tests)
• For mainland China pulls: optional mirror image comment in docker-compose.yml (NJU ghcr mirror in upstream repo)

Step 1 — Clone repo and configure .env

git clone https://github.com/666ghj/MiroFish.git
cd MiroFish
cp .env.example .env

Edit .env with required keys from the example file—typically LLM_API_KEY, LLM_BASE_URL, LLM_MODEL_NAME, and ZEP_API_KEY. OpenAI-compatible providers work when LLM_BASE_URL points to their v1 endpoint.

Step 2 — Start with Docker Compose

docker compose up -d
docker compose logs -f --tail=80

Default upstream mapping (verify in your checkout):

ports:
  - "3000:3000"
  - "5001:5001"

Open http://SERVER_IP:3000 from a browser on your laptop. Local-only tests on the same machine may omit VITE_API_BASE_URL; remote access cannot.

Step 3 — Remote access: set VITE_API_BASE_URL first

Before docker compose up on a VPS, add to .env:

VITE_API_BASE_URL=http://YOUR_PUBLIC_IP:5001

Then rebuild so Vite bakes the value: docker compose down && docker compose up --build -d. Full troubleshooting: MiroFish Network Error & VITE_API_BASE_URL fix.

Step 4 — Firewall and health checks

1. Cloud security group: allow TCP 3000 and 5001
2. curl -sS -o /dev/null -w "%{http_code}" http://PUBLIC_IP:5001/ — connection refused = Docker/firewall, not LLM keys
3. DevTools → failed XHR must target PUBLIC_IP, never localhost

Step 5 — First project smoke test

1. Upload a small UTF-8 .txt (issues #57 used plain text successfully)
2. Create a project and run ontology generation
3. If you see Network Error with a loaded UI → revisit MiroFish Network Error & VITE_API_BASE_URL fix, not Zep keys first

Optional: deploy on a VpsGona cloud Mac

Rent Mac mini M4 from $20.7/day when Docker Desktop + SSH beats maintaining a Linux VPS for a 2–5 day pilot. Use SSH vs VNC and node selection (HK/JP/KR/SG/US East).

Frequently asked questions

Docker vs npm run dev?

Docker matches production-like ports; npm run dev uses Vite proxy on localhost only—fine for same-machine dev, not remote VPS without VITE_API_BASE_URL.

Which LLM providers work?

Any OpenAI-compatible API: set LLM_BASE_URL, LLM_MODEL_NAME, and LLM_API_KEY per .env.example.

Do I need to rebuild after .env changes?

Yes for VITE_* vars—they are baked at image build. Run docker compose up --build -d.

Is Zep mandatory?

Zep API key is required in upstream .env.example for graph memory features; sign up at Zep Cloud free tier for tests.

UI works but ontology fails?

Usually wrong API host—see the network error guide, not LLM quota first.