Docker Collector Setup Version

Current package

Download

Already running a Docker Collector? Go to Updating an existing Collector. Your data and activation carry over.

What you need

• A host that can run Docker and Docker Compose (Linux VM, Proxmox LXC, NAS, or Mac).
• A ReefMind.ai account with a tank already added.
• A paid ReefMind.ai plan or an active trial. Without one, ReefMind refuses the Collector's heartbeat (402) and it shows Offline.
• A 6-character Collector Authorization Code (created in the next step).
• For local devices (Apex, LAN cameras): the host must sit on the same network / subnet as those devices.

Your Apex controller IP and credentials are configured once in your ReefMind tank settings and are fetched automatically by the collector. You never put controller passwords into Docker.

1. Get your authorization code

1. Sign in at ReefMind.ai.
2. Open Settings, click Add, then choose Collector Box.
3. Click Generate Collector setup code. The code appears in the Activate New Collector window.
4. Copy the 6-character Authorization Code (letters and numbers). It appears as YOUR-6-CHARACTER-CODE in the examples below.

Treat the code like a password — it links a collector to your account. If it leaks, generate a new one from the same screen and the old one stops working. Each code works once.

2. Download and unpack the package

Download

1. Download the ZIP with the button above into your Downloads folder (on a NAS, into a shared folder; see NAS).
2. Unzip it there. It unpacks into a folder named ReefMind-Docker-Collector. Do not run anything from inside the ZIP.
3. Open Docker Desktop and wait until its engine says it is running.

The package builds the Collector image locally on your computer. There is no registry sign-in, no private image download, and no ReefMind.ai credential involved in the build. Everything needed is already inside the ZIP. The expected version is .

The package is built the same way every time, so you can check you have the real file before unzipping. Compare the result with the SHA-256 under Current package. Use your ZIP's actual file name.

Mac / Linux:

shasum -a 256 

Windows PowerShell:

Get-FileHash .\ -Algorithm SHA256

If the hash does not match, delete the file and download it again. If it still does not match, or the download fails, email support@reefmind.ai.

3A. Windows Docker Desktop

1. Install and open Docker Desktop for Windows. Use the normal WSL 2 setup when Docker Desktop recommends it.
2. In Docker Desktop, open Settings → General, turn on Start Docker Desktop when you sign in to your computer, and apply the setting.
3. Turn on host networking. In Docker Desktop, open Settings → Resources → Network, turn on Enable host networking, then click Apply & Restart. The Collector needs this to reach your Apex and cameras. If you do not see the option, update Docker Desktop to the latest version first.
4. If the Docker tray menu offers Switch to Linux containers, select it. Wait for Docker Desktop to say Engine running, then confirm PowerShell shows both Client and Server sections:

docker version

5. Unzip into Downloads.
6. Open PowerShell and run the start helper from the unzipped folder:

Set-Location "$HOME\Downloads\ReefMind-Docker-Collector"
.\start-windows.bat

7. The first run creates docker-collector\.env and opens it in Notepad. Replace PASTE_CODE_HERE with your Authorization Code, save, and run .\start-windows.bat again. It builds and starts the Collector.

The first start takes several minutes while Docker builds the image. Leave the window open until it finishes.

If you prefer to type the commands yourself, run this block instead. It enters the Compose folder and creates the private configuration file without echoing the code:

Set-Location "$HOME\Downloads\ReefMind-Docker-Collector\docker-collector"
$code = Read-Host "Authorization code" -AsSecureString
$ptr = [Runtime.InteropServices.Marshal]::SecureStringToBSTR($code)
try {
  $plain = [Runtime.InteropServices.Marshal]::PtrToStringBSTR($ptr)
  if ([string]::IsNullOrWhiteSpace($plain)) { throw "Authorization code cannot be empty" }
  "REEFMIND_AUTHORIZATION_CODE=$plain" | Set-Content -Encoding ascii .env
} finally {
  [Runtime.InteropServices.Marshal]::ZeroFreeBSTR($ptr)
  Remove-Variable code,plain -ErrorAction SilentlyContinue
}
docker compose config --quiet
docker compose up -d --build

Never post the code in Discord or email.

3B. Mac Docker Desktop

1. Install and open Docker Desktop for Mac. Docker provides the correct build for Apple silicon or Intel.
2. In Docker Desktop, open Settings → General, turn on Start Docker Desktop when you sign in, and apply the setting.
3. Turn on host networking. In Docker Desktop, open Settings → Resources → Network, turn on Enable host networking, then click Apply & Restart. The Collector needs this to reach your Apex and cameras. If you do not see the option, update Docker Desktop to the latest version first.
4. Allow local network access. If macOS asks whether Docker may find devices on your local network, click Allow. If Docker is listed under the Mac's System Settings → Privacy & Security → Local Network, make sure it is turned on.
5. Unzip in Downloads.
6. Open the unzipped ReefMind-Docker-Collector folder and double-click start.command. The first run creates docker-collector/.env and opens it in TextEdit. Replace PASTE_CODE_HERE with your Authorization Code, save with Command-S, and double-click start.command again. It builds and starts the Collector.

The first start takes several minutes while Docker builds the image. Leave the Terminal window open until it finishes. If macOS will not open start.command, open Terminal in that folder and run chmod +x start.sh start.command && ./start.command.

If you prefer to type the commands yourself, open the Mac Terminal app and run this secure prompt instead. It refuses an empty code before writing .env:

cd ~/Downloads/ReefMind-Docker-Collector/docker-collector
printf 'Authorization code: '
IFS= read -r -s REEFMIND_CODE
printf '\n'
if [[ -z "$REEFMIND_CODE" ]]; then
  echo 'Authorization code cannot be empty' >&2
  unset REEFMIND_CODE
  return 1 2>/dev/null || exit 1
fi
( umask 077; printf 'REEFMIND_AUTHORIZATION_CODE=%s\n' "$REEFMIND_CODE" > .env )
unset REEFMIND_CODE
docker compose config --quiet
docker compose up -d --build

3C. Linux / Proxmox

1. Install Docker Engine and the Compose plugin for your distribution, then confirm the daemon responds:

docker version

2. Unzip into Downloads, then use the same non-echoing, non-empty secure prompt as macOS:

cd ~/Downloads/ReefMind-Docker-Collector/docker-collector
printf 'Authorization code: '
IFS= read -r -s REEFMIND_CODE
printf '\n'
if [[ -z "$REEFMIND_CODE" ]]; then
  echo 'Authorization code cannot be empty' >&2
  unset REEFMIND_CODE
  return 1 2>/dev/null || exit 1
fi
( umask 077; printf 'REEFMIND_AUTHORIZATION_CODE=%s\n' "$REEFMIND_CODE" > .env )
unset REEFMIND_CODE
docker compose config --quiet
docker compose up -d --build

The first start takes several minutes while Docker builds the image. bash start.sh from the ReefMind-Docker-Collector folder does the same steps if you prefer.

Host networking is native on Linux, so local Apex and camera discovery needs no extra configuration.

3D. NAS (QNAP, Unraid, TrueNAS, Synology)

Every NAS uses the same pattern. Put the NAS on the same home network as the Apex and cameras, and run one Collector per tank.

1. Download and unzip into a shared folder. Download with the button under Current package, copy it to a shared folder on the NAS (for example docker or appdata), and unzip it there. You get ReefMind-Docker-Collector/docker-collector.
2. Add your code. In the docker-collector folder, copy .env.example to .env and replace PASTE_CODE_HERE with your 6-character Authorization Code. The NAS file editor works, or the secure prompt from 3C over SSH.
3. Build and start. Over SSH or the NAS terminal, run bash start.sh from the ReefMind-Docker-Collector folder (Synology can use Container Manager instead, below). It builds the image, starts the Collector, and never overwrites .env or deletes the data volume.
4. Confirm Online. Refresh ReefMind.ai, open Settings → Add → Collector Box, and check the Collector shows Online. Then check that Apex readings update.

When you replace the package later, keep your docker-collector/.env and the reefmind-data volume. Never pick a “remove volumes” or “delete data” option.

The Compose file builds the image from the whole unzipped package, so keep the ReefMind-Docker-Collector folder intact and start it from there. Pasting only docker-compose.yml into a NAS app will not build.

QNAP Container Station

Install Container Station from the App Center. Turn on SSH under Control Panel → Network & File Services → Telnet / SSH, connect, change into the unzipped folder (for example cd /share/Container/ReefMind-Docker-Collector), and run bash start.sh. The reefmind-collector container then appears in Container Station.

Unraid

Unzip into /mnt/user/appdata/ReefMind-Docker-Collector. Open the Unraid Terminal (top-right toolbar), cd into that folder and run bash start.sh. The container then appears on the Docker tab.

TrueNAS SCALE

Unzip into a dataset (for example /mnt/tank/apps/ReefMind-Docker-Collector). Open System → Shell or SSH, cd into that folder and run sudo bash start.sh.

Synology Container Manager

Open Container Manager → Project → Create, set the path to the docker-collector folder, and use the existing docker-compose.yml. Build and start the project. To replace the package, update the folder, keep .env, then use Build and recreate. Confirm reefmind-data:/data stays attached.

4. Verify the Collector

Run these commands in the docker-collector subfolder of the extracted package:

docker compose ps -a
docker compose logs --tail=100 reefmind-collector
docker inspect reefmind-collector --format 'version={{index .Config.Labels "ai.reefmind.collector.version"}} health={{.State.Health.Status}} network={{.HostConfig.NetworkMode}}'
docker volume ls --filter name=reefmind-data

Successful startup shows the container as healthy, the restart policy as unless-stopped, a 200 heartbeat, and a line such as Running as persistent service. Then refresh ReefMind.ai, open Settings → Add → Collector Box, and confirm the Collector appears Online. On Mac and Windows, network=host in the output needs host networking turned on in Docker Desktop (3A, 3B).

The unless-stopped policy restarts the Collector after a crash or computer reboot. Docker Desktop must also be configured to start when the user signs in. If someone manually stops the Collector, Docker leaves it stopped until it is started again.

Environment variables

There are no APEX_IP, APEX_USER, or APEX_PASS variables, and no API key is required for a normal setup. The collector authorizes with your 6-character code and pulls controller details from your ReefMind tank settings.

Local Apex and camera access

The Docker computer must be on the same home network as the Apex and local cameras. Configure the Apex's exact local IP address in ReefMind tank settings instead of relying only on automatic discovery.

• Linux VM / NAS / Proxmox — host networking works natively and remains the most predictable LAN option.
• Docker Desktop on macOS or Windows — the Collector can activate, remain online, and send cloud heartbeats. Local-device access needs Enable host networking turned on in Docker Desktop (and, on macOS, Local Network access for Docker), and also depends on firewall/VPN settings and the home network. Confirm actual Apex readings after the first sync; an Online heartbeat alone does not prove local Apex access.

If the Collector is Online but readings do not update, do not reinstall it immediately. First verify the Apex IP in ReefMind, temporarily disconnect VPN software, allow Docker through the host firewall, and send the latest Collector logs to support.

Proxmox / VM notes

• Bridged network: give the VM/LXC a bridged adapter on the same subnet as the Apex so it works out of the box.
• Proxmox LXC: if you run Docker inside an LXC, enable nesting under Options → Features → Nesting.
• Static IP: assign a static IP to the VM/LXC so the collector stays stable.
• Resources: the collector is lightweight — a 1-core, 256 MB VM is plenty (it uses well under 128 MB of RAM).

Cameras

IP cameras on the same LAN work automatically; the collector uses ffmpeg (bundled in the image) for RTSP snapshots.

1. Add cameras in the ReefMind dashboard under Settings → Cameras.
2. Enter the camera's RTSP URL, e.g. rtsp://192.168.1.50:554/stream1.
3. The collector captures a snapshot on each sync cycle.

Supported: any camera with RTSP output, plus TP-Link Tapo, Reolink, and generic ONVIF. Tapo/Kasa cameras use their local API directly.

Wyze: Wyze Cam v4 with RTSP is supported. Choose Wyze (RTSP) as the camera type. Requirements:

• Wyze Cam v4 only. Other Wyze models are not supported.
• RTSP turned on in the Wyze app: camera → Settings (gear) → Advanced Settings → RTSP.
• A local RTSP username and password set there. This is not your Wyze account login.
• The camera and the Collector on the same home network.

Enter the camera IP (Wyze app → camera Settings → Device Info → IP Address) and the RTSP username and password. Leave the stream URL blank to use rtsps://<IP>:322/stream0, or paste the URL the Wyze app shows.

Updating an existing Collector

The current package is . When ReefMind.ai releases an update for Docker Collectors, a running Collector downloads and installs it on its own into the reefmind-data volume, with no rebuild and no new Authorization Code. If an update does not connect to ReefMind.ai within about 6 minutes or keeps crashing, the Collector goes back to the version that worked.

To update right away instead of waiting, replace the package as below.

Replacing the package

Replace the package folder and rebuild. The Collector's identity and activation are saved in the reefmind-data volume, not in the folder, so you do not need a new Authorization Code. Keep two things:

• the reefmind-data volume (never run docker compose down -v or docker volume rm), and
• your docker-collector/.env file, copied into the new folder.

If you no longer have the old .env, create an empty one in the new docker-collector folder instead (touch .env on Mac or Linux, New-Item .env in PowerShell). The saved activation in the volume is enough.

Download the current ZIP from Current package into Downloads first. It still unpacks into ReefMind-Docker-Collector.

Mac and Linux

cd ~/Downloads
mv ReefMind-Docker-Collector ReefMind-Docker-Collector-old
unzip -q 
cp ReefMind-Docker-Collector-old/docker-collector/.env ReefMind-Docker-Collector/docker-collector/.env
cd ReefMind-Docker-Collector/docker-collector
docker compose up -d --build

On Linux, install unzip first if the command is missing (for example sudo apt install unzip).

Windows PowerShell

Set-Location "$HOME\Downloads"
Rename-Item ReefMind-Docker-Collector ReefMind-Docker-Collector-old
Expand-Archive .\ -DestinationPath .
Copy-Item .\ReefMind-Docker-Collector-old\docker-collector\.env .\ReefMind-Docker-Collector\docker-collector\.env
Set-Location .\ReefMind-Docker-Collector\docker-collector
docker compose up -d --build

Keep the inner folder name docker-collector. Docker Compose names the volume after it, so the same name finds the same volume. docker compose up -d --build rebuilds the image, replaces the container and reattaches the existing volume. When the Collector shows Online in Settings → Add → Collector Box, you can delete the ReefMind-Docker-Collector-old folder.

NAS

Replace the package folder in the shared folder, keep docker-collector/.env, then build and recreate as in NAS. Confirm reefmind-data:/data remains attached and never select a volume-deletion option.

If your Collector was set up some other way (for example from a gcr.io image rather than this package), email support@reefmind.ai before updating.

Check which version is running

Run these in the docker-collector folder.

Mac / Linux:

docker inspect reefmind-collector --format '{{ index .Config.Labels "ai.reefmind.collector.version" }}'
docker compose logs reefmind-collector | grep "docker-launcher] loading"

Windows PowerShell:

docker inspect reefmind-collector --format '{{ index .Config.Labels "ai.reefmind.collector.version" }}'
docker compose logs reefmind-collector | Select-String -SimpleMatch "docker-launcher] loading"

The first command shows the version built into the image, for example 3.3.244. The last loading line shows the version that is actually running:

• loading image runtime 3.3.244 — running the image's own version.
• loading runtime 3.3.244 from /data/runtime/3.3.244 — running an update ReefMind.ai sent to it.

Collectors older than 3.3.220 print no loading line. For those, the first command is the running version.

Troubleshooting

Safe Mac/Linux commands

cd ~/Downloads/ReefMind-Docker-Collector/docker-collector
docker version
docker compose version
docker compose config --quiet
docker compose ps -a
docker compose logs --tail=100 reefmind-collector
docker inspect reefmind-collector --format 'version={{index .Config.Labels "ai.reefmind.collector.version"}} health={{.State.Health.Status}} network={{.HostConfig.NetworkMode}}'
docker volume ls --filter name=reefmind-data
curl -fsS https://www.reefmind.ai/api/status
nslookup www.reefmind.ai

Safe Windows PowerShell commands

Set-Location "$HOME\Downloads\ReefMind-Docker-Collector\docker-collector"
docker version
docker compose version
docker compose config --quiet
docker compose ps -a
docker compose logs --tail=100 reefmind-collector
docker inspect reefmind-collector --format 'version={{index .Config.Labels "ai.reefmind.collector.version"}} health={{.State.Health.Status}} network={{.HostConfig.NetworkMode}}'
docker volume ls --filter name=reefmind-data
Invoke-WebRequest -UseBasicParsing https://www.reefmind.ai/api/status | Select-Object StatusCode
Resolve-DnsName www.reefmind.ai

Windows: cannot connect to dockerDesktopLinuxEngine

Docker Desktop's Linux engine is not running. Open Docker Desktop, choose Switch to Linux containers if that option appears, wait for Engine running, and rerun docker version. Continue only when it shows both Client and Server sections.

Windows: build appears stuck at RUN npm ci --omit=dev

This step can be silent while npm downloads packages. Leave PowerShell and Docker Desktop open for 5–10 minutes. If the image eventually reports Built but no container starts, run docker compose up -d. If there is still no progress after 10 minutes, press Ctrl-C once, restart Docker Desktop, and run docker compose build --progress=plain again.

Collector stays on an older version

A Collector that took an update from ReefMind.ai on 3.3.239 or earlier can stop asking for new versions until its container restarts. Restart it once from the docker-collector folder:

docker compose restart reefmind-collector

On a NAS, use the container's Restart action in QNAP Container Station, the Unraid Docker tab, TrueNAS Apps or Synology Container Manager. The reefmind-data volume and the activation are kept. A Collector older than 3.3.220 (for example 3.3.193) cannot install updates on its own; replace the package instead.

Collector won't start / key rejected

Check the logs from the extracted package folder:

docker compose logs --tail=60 reefmind-collector

If first activation reports an invalid, expired or already-used code, generate a fresh Authorization Code in Settings → Add → Collector Box → Generate Collector setup code (each code works once), put it in .env, and run docker compose up -d. Keep reefmind-data.

Heartbeat refused with 402

The ReefMind account has no paid plan or active trial, so ReefMind does not accept its Collector data and the Collector shows Offline. Choose a plan in ReefMind; the Collector reconnects on its own within a few minutes.

Collector removed in ReefMind (401)

If the Collector was removed in ReefMind.ai, its saved key no longer works, and the key saved in the reefmind-data volume is used ahead of any new code. This is the one case where the volume must be cleared. Generate a fresh Authorization Code, write it to .env with the secure prompt, then from the docker-collector folder:

docker compose down -v
docker compose up -d --build

On a NAS, delete the container and its reefmind-data volume in the NAS UI, then create the project again with the new .env.

ReefMind API and DNS reachability

Mac/Linux:

curl -fsS https://www.reefmind.ai/api/status
nslookup www.reefmind.ai

Windows PowerShell:

Invoke-WebRequest -UseBasicParsing https://www.reefmind.ai/api/status | Select-Object StatusCode
Resolve-DnsName www.reefmind.ai

Can't reach the Apex

• Confirm the container has host networking (--network host). On Mac and Windows, check Enable host networking is on in Docker Desktop under Settings → Resources → Network; on macOS, also check Docker is allowed under System Settings → Privacy & Security → Local Network.
• From the host, check the Apex responds: curl http://192.168.1.100/cgi-bin/status.json.
• From inside the container: docker exec reefmind-collector ping -c1 192.168.1.100.

Cameras not capturing

• Verify the RTSP URL from the host: ffmpeg -i rtsp://camera-ip:554/stream1 -frames:v 1 test.jpg.
• Confirm the camera is on the same LAN as the collector host.

Collector ID keeps changing

Use the named reefmind-data volume (so the generated ID persists) or set COLLECTOR_ID explicitly.

High memory use

The collector normally stays well under 128 MB. If memory climbs, check for camera snapshot buildup in the /data volume.

Support

Email support@reefmind.ai with your ReefMind.ai account email, tank name, and the container logs (docker logs reefmind-collector). Never share your Authorization Code in a public forum.

Raspberry Pi / Collector Box

Use the separate hardware setup card in owner Settings. The Docker package and these commands perform no Pi OTA.