hossein3piol/mikrotik-routeros repository overview

⁠MikroTik RouterOS on Docker

⁠Overview

This project packages MikroTik RouterOS (Cloud Hosted Router) inside a Docker container using QEMU for full x86_64 virtualization. It is designed for infrastructure engineers who need a reproducible, version-controlled MikroTik environment on any Linux server — with complete persistence, host file sharing, and safe port routing.

Because QEMU handles the x86_64 emulation layer, the Docker image itself is built for multiple CPU architectures. Whether your host is an AMD64 server, an ARM64 Raspberry Pi, or any other supported platform, you can pull and run the same image without any modifications.

⁠Features

⁠Prerequisites

• Linux host with Docker Engine installed
• Docker Compose v2+
• KVM support recommended (/dev/kvm available) for acceptable performance

⁠Supported Architectures

Docker will automatically pull the correct variant for your host platform.

⁠Quick Start

⁠1. Clone the repository

git clone https://github.com/im-ecorp/mikrotik-routeros.git
cd mikrotik-routeros

⁠2. Configure environment variables

Copy the example and set your desired RouterOS version:

cp .env.example .env
# Edit .env and set ROUTEROS_VERSION and optionally TZ

.env example:

ROUTEROS_VERSION=7.22.2
TZ=Asia/Tehran

If .env is omitted, the latest tag and Asia/Tehran timezone are used by default.

⁠3. Start the container

docker compose up -d

⁠4. Connect to MikroTik

Default credentials: admin / (no password — set one immediately)

⁠Architecture

⁠How It Works

┌──────────────────────────────────────────────────────┐
│  Docker Container (Alpine Linux)                     │
│                                                      │
│   ┌────────────────────────────────────┐             │
│   │  QEMU (x86_64 system emulation)    │             │
│   │                                    │             │
│   │   MikroTik RouterOS CHR            │             │
│   │   ├── chr.vdi  (persistent disk)   │             │
│   │   └── FAT drive (./shared)         │             │
│   └────────────────┬───────────────────┘             │
│                    │ TAP / bridge (qemubr0)           │
└────────────────────┼─────────────────────────────────┘
                     │
              Docker bridge network
              172.24.0.0/16

Regardless of the host CPU architecture, QEMU always emulates an x86_64 machine for MikroTik — this is why the image runs identically on ARM and AMD64 hosts.

⁠Directory Structure

.
├── bin/
│   ├── entrypoint.sh          # Container entrypoint & QEMU launcher
│   ├── generate-dhcpd-conf.py # Dynamic DHCP config generator
│   ├── qemu-ifup              # TAP interface bring-up script
│   └── qemu-ifdown            # TAP interface teardown script
├── data/                      # Auto-created — stores chr.vdi (persistent)
├── shared/                    # Auto-created — shared with MikroTik File Manager
├── .github/
│   └── workflows/
│       └── docker-image.yml   # CI/CD pipeline for building & publishing images
├── Dockerfile
├── docker-compose.yml
└── .env.example

⁠Volumes

⁠Port Reference

⁠Configuration

⁠Changing the RouterOS Version

Update ROUTEROS_VERSION in your .env file, then recreate the container:

docker compose down
docker compose up -d

⁠Changing the Timezone

TZ=Europe/Berlin

⁠Stopping the Container

docker compose down

Your configuration is safely stored in ./data and will persist for the next startup.

⁠CI/CD: Building and Publishing Images

A GitHub Actions workflow is included at .github/workflows/docker-image.yml. It builds a multi-architecture image and pushes it to both Docker Hub and GitHub Container Registry (GHCR).

⁠Required Secrets

Configure these under Settings → Secrets and variables → Actions:

⁠Triggering a Build

1. Go to Actions → Build and Push MikroTik Image
2. Click Run workflow
3. Fill in the inputs:

⁠Published Tags

Each build produces the following tags (both with and without the v prefix for maximum compatibility):

hossein3piol/mikrotik-routeros:7.22.2
hossein3piol/mikrotik-routeros:v7.22.2
ghcr.io/im-ecorp/mikrotik-routeros:7.22.2
ghcr.io/im-ecorp/mikrotik-routeros:v7.22.2

# If "tag_latest" was checked:
hossein3piol/mikrotik-routeros:latest
ghcr.io/im-ecorp/mikrotik-routeros:latest

⁠Building Manually on Your Server

docker build \
  --build-arg ROUTEROS_VERSION=7.22.2 \
  -t hossein3piol/mikrotik-routeros:v7.22.2 \
  -t hossein3piol/mikrotik-routeros:7.22.2 \
  .

docker push hossein3piol/mikrotik-routeros:v7.22.2
docker push hossein3piol/mikrotik-routeros:7.22.2

⁠Advanced: OpenVPN Configuration

⁠Troubleshooting

Container exits immediately

• Verify KVM is available: ls -la /dev/kvm
• Check logs: docker compose logs -f
• If KVM is unavailable, the container will fall back to software emulation automatically

Cannot connect via Winbox

• Confirm the container is running: docker compose ps
• The healthcheck polls port 8291 — wait until status shows healthy

MikroTik lost its configuration after restart

• Ensure ./data directory exists and is writable by the container
• Never use docker compose down -v

SSH connection refused

• MikroTik SSH is on port 2222, not 22
• Connect with: ssh admin@<server-ip> -p 2222

Bridge already exists error on restart

• The entrypoint checks for an existing bridge before creating one — this is handled automatically

⁠Acknowledgments

• lordbasex⁠ — original inspiration for the QEMU-in-Docker approach

⁠Support

If this project saves you time in your infrastructure work, consider supporting its development:

• USDT (TRC20): TH1iDsFr2wjgpptghFBn6h7DVt88pp5WoH