Manual

The container does not run

Containers on RouterOS need a physical confirmation, and the generated script does not start them for you.

You pasted the container part of the script and nothing happens. /container print gives an empty list, or the container is there with status stopped or error, or it looks like it runs and is reachable from nowhere.

What it is not: this is rarely a fault in the image or in the network settings. Containers on RouterOS have conditions that all have to be met before anything happens, and two of them were made awkward on purpose: a physical confirmation at the device itself, and the fact that a container has to be started explicitly after it has been created. So do not start by digging into mounts and environment variables. Walk the conditions first.

The quick checks, in order

  1. May this device run containers? /system resource print and look at architecture-name. A good answer: arm64, x86_64 or tile. If it says mipsbe, smips or arm, it ends here: there is no container package for it.
  2. Is the package installed? /system package print. A good answer: a container line, enabled. Otherwise download it from MikroTik, upload it and reboot.
  3. Is device-mode right? /system device-mode print. A good answer: container: yes. If it says no, the confirmation was never given and the whole /container menu does nothing.
  4. Does the disk exist? /disk print. A good answer: a line whose name matches exactly what is in root-dir. It is often not called disk1 but usb1-part1, and then every path in the script is wrong.
  5. What does the container say? /container print detail. A good answer: status: running. Extracting means it is still unpacking, stopped means it was never started, error means the log will tell you more.
  6. What does the log say? /log print where topics~"container". This is the most important line in this chapter. It states why the pull failed, which path did not exist or which variable was missing.
  7. Is there room? /disk print. A good answer: comfortably more free than the image is big. See No space.

The usual causes, most common first

Device-mode was never confirmed

The line /system device-mode update container=yes does not flip anything. It asks for something, and you then have five minutes to confirm it at the device: press the reset button, or power it off and on. Miss that window and the request quietly lapses, and no container line works. That is deliberate: containers can do anything, so MikroTik wants someone next to the box.

The disk name is wrong

Every path hangs on the disk name: the root-dir, the layer directory, the temporary directory for pulling and the sources of the mounts. If your stick is called something other than what was filled in, everything fails at once and with confusing messages. Look in /disk print and use that name literally.

The container was created but never started

Creating a container and starting a container are two separate acts. After creation the status is stopped. Start it with /container start [find comment="pihole"] and look at the status again.

The image could not be pulled

Pulling happens from the registry over the internet. That needs DNS, an outbound connection and room for the layers. If DNS on the router does not work, nothing arrives. Test with :put [:resolve registry-1.docker.io].

The image does not match the architecture

An image that only exists for amd64 does not run on an arm64 router. Check which platforms the image publishes.

The container starts and stops again immediately

That is nearly always the program inside the container, not RouterOS. A missing environment variable, a directory that was not mounted, or a configuration file that is not there. The container's own log tells you; make sure logging=yes is set.

What the configurator does about it

  • The Containers section only appears on devices the catalogue knows to be ARM64, x86 or Tile. On the rest the tool says containers require ARM64 or x86 and leaves it at that.
  • The section's introduction says it outright: /system/device-mode/update container=yes has to be physically confirmed within five minutes, and that line is therefore the first one in this part of the script. Above it a comment says you have to re-run the rest of the section after confirming. Pasting the script in one go does not work here; there is a manual act in the middle on purpose.
  • The script creates a containers bridge with the container network on it, a masquerade so containers can reach the internet, and sets the registry URL, the layer directory and the temporary directory on the disk you chose.
  • Per container it writes a veth with an address and gateway, a bridge port, the environment variables, the mounts and the container itself with start-on-boot=yes and logging=yes, plus a dstnat from the LAN if you fill in ports.
  • Be clear about this one: the script does not start the containers. It ends with a comment line giving you the start command and telling you where the logs are. That is deliberate, because pulling takes time and space and you want to watch it happen. Thanks to start-on-boot=yes they do start after the next reboot.
  • The Storage field defaults to disk1, with help text telling you to look in /disk print. The tool cannot check that for you.
  • System holds the advanced toggle that moves parts blocked by device-mode into a separate script that runs once at the next start. It ends with an activation window of one day: power the device off and on within a day or the change does not take effect.

Where the cause lies outside your router

  • The registry. Docker Hub limits pulls per address. On a rate-limiting error: wait, or use another registry.
  • The USB stick. Not every stick works on every model, and a stick with the wrong file system is not mounted. Format it from the router.

Read on: Containers, Recipe: AdGuard Home and Packages.

Want to try it right away? Open the configurator