Quick Start Guide (Native & Docker)

Choose your installation method below.

Option A is for native Linux/Raspberry Pi users.
Option B is for Docker users (Linux, Raspberry Pi, Mac, Windows).

Option A: Native Installation (Linux / Raspberry Pi)

Best for: Raspberry Pi OS, Ubuntu, Debian, or any Linux server.

1. Download & Install

Download either from this Website BmuS and unzip OR via GitHub:
git clone https://github.com/back-me-up-scotty/bmus.git
cd bmus/
chmod +x install_dependencies.sh
sudo bash install_dependencies.sh
Configure bmus_credentials
Configure bmus.conf
Give proper rights (install_dependencies.sh does that for you)

2. Run

Start the backup or system check:

Bash

# System Check (Recommended for first run)
sudo bash ./bmus.sh -n

# Start Backup
sudo bash ./bmus.sh

Automated Backups

You don’t have to start BmuS manually. You can also set it to start at times you specify. Please read this document.

Option B: Docker Installation

Best for: Linux, Raspberry Pi, Synology NAS, UGREEN, Unraid, macOS, Windows, or keeping your host clean.

The following video guides you through the complete installation of BmuS on a Synology NAS, whose backup destination is a UGREEN NAS.

Step 1: Preparation (All OS)

Docker install on Linux/Raspberry Pi

First, update the system to the latest version to avoid conflicts.

sudo apt update && sudo apt full-upgrade -y

Download the script from the official Docker website and run it directly.

curl -fsSL https://get.docker.com -o get-docker.sh

Start installation.

sudo sh get-docker.sh

By default, only the root user (administrator) is allowed to execute Docker commands. This means you would have to write sudo before every command. That’s annoying. We’ll change that by adding your user (usually pi or your own name) to the Docker group.

sudo usermod -aG docker $USER

You need to log out and log back in. The easiest way to do this is to restart your computer or use this command, which reloads the group membership.

newgrp docker

Let’s test if everything is working by running the famous “Hello World” image. Docker will download the image, create a container from it, say “Hello,” and then shut down again. If you see a message that starts with “Hello from Docker!”: Congratulations, Docker is running!

docker run hello-world

Optional: Most modern projects use Docker Compose to easily start complex applications (consisting of multiple containers). Previously, you had to install it separately, but in modern Docker it is included as a plugin.

docker compose version

The video example shows the Docker installation on a Raspberry Pi, as well as the subsequent installation of BmuS. These steps are explained again below.

Optional: Portainer installation

Portainer is a graphical user interface for Docker. It allows you to conveniently manage your containers in your web browser instead of having to type everything into the console. This is extremely helpful for beginners.

Create a “memory” for Portainer

Docker containers are forgetful by nature. When you delete them, the data is gone. To ensure that Portainer retains your settings and passwords, we create a so-called volume (a permanent storage space).

Enter this command in the terminal:

docker volume create portainer_data

Start the Portainer container

Now we download Portainer and start it. The command looks long, but it is logically structured. Just copy it completely:

docker run -d -p 8000:8000 -p 9443:9443 --name portainer --restart=always -v /var/run/docker.sock:/var/run/docker.sock -v portainer_data:/data portainer/portainer-ce:latest

-d: Starts in the background (“detached”).
-p 9443:9443: Opens access via the web browser (HTTPS).
–restart=always: Automatically restarts Portainer when the Raspberry Pi restarts.
-v /var/run/docker.sock…: This is the most important part. It allows Portainer to “talk” to the Docker daemon on your machine to control other containers.

Open and set up Portainer

Open your web browser and enter: https://<Your-IP>:9443
IMPORTANT: Your browser will likely display a warning (“Connection not secure” or “Security risk”). This is normal because Portainer uses a self-signed certificate.
Click on “Advanced” and then on “Continue to…” or “Accept risk.”
Create admin account: You will now see the setup screen.
Enter a username (usually admin) and a strong password (at least 12 characters).
Click Create user.
Select environment: Portainer should automatically detect your local Docker installation. Simply click Get Started (or select “Local” if prompted).

The dashboard

You will now be taken to the dashboard. If you click on the field with the little whale (“local”), you will see an overview:

Containers: Here you can see your running programs (currently only Portainer itself and the “Hello World” from earlier).
Images: This is where the downloaded files are stored.
App Templates: (on the left in the bar) This is great for beginners. Here you can install well-known software such as WordPress, Nginx, or Node.js with a single click.

Docker install on a Mac or Windows

Install Docker Desktop for Mac or Windows.
Mac: https://docs.docker.com/desktop/setup/install/mac-install/
Windows: https://docs.docker.com/desktop/setup/install/windows-install/

Step 2: Download & configure BmuS

Download Bmus-Docker.zip from this Website and unzip OR from GitHub. If you are on a Linux or Mac you can download and unzip via console with this command.

wget -O Bmus-Docker.zip https://github.com/back-me-up-scotty/bmus/raw/main/Bmus-Docker.zip && unzip Bmus-Docker.zip && rm Bmus-Docker.zip

After downloading and unzipping:

cd bmus-docker/config
Open & configure .bmus_credentials (Users & Passwords for NAS & MySQL DB)
Open & configure bmus.conf (Settings, Paths for BmuS)
Open & configure msmtp.conf (User & Password for smtp server of your provider)
Open & configure bmus_geocryptfs (Password for encryption)

Notes on configuring bmus.conf and backup paths

IMPORTANT FOR WINDOWS

The most important difference is how you mount the drives. Windows uses drive letters (C:), Linux does not. Linux runs in the container. This means that you cannot use C:\ paths or backslashes \ in your configuration. You must specify the paths as they appear in the container.

Incorrect (Windows thinking):

BACKUP_SOURCES=(“C:\Users\YourName\Documents”)

Correct (Linux/Docker thinking):

BACKUP_SOURCES=(“/host_root/YourName/Documents”)

IMPORTANT FOR MAC

The backup path under BACKUP_SOURCES under Mac always starts with /host_root

Incorrect

BACKUP_SOURCES=("/Users/YourName/Documents")

Correct (Linux/Docker thinking):

BACKUP_SOURCES=(“/host_root/Users/YourName/Documents”)

Step 3: Download and install Docker image

Linux / Raspberry Pi

cd bmus-docker/

In the following steps for Windows and Mac, you have to edit the .yaml file and adjust the paths there. You don’t have to do this on Linux/Raspberry. Just type:

docker compose up -d

MacOS (Apple Silicon & Intel)

Important:

Go to System Settings > Privacy & Security > Full Disk Access.
Add Docker to the list (otherwise BmuS cannot see your files).
Open .yaml from the ZIP file and replace the content of the file with the following:

YAML

services:
  bmus:
    image: backmeupscotty/bmus:latest
    container_name: bmus_backup
    restart: unless-stopped
    privileged: true  # Essential for macOS mounting!
    cap_add:
      - SYS_ADMIN
      - DAC_READ_SEARCH
    environment:
      - TZ=Europe/Berlin # change to your time zone
    volumes:
      - ./config:/config
      # MAP YOUR MAC FOLDERS HERE:
      - /Users/YourName:/host_root/Users/YourName:ro
      # External Drives (usually under /Volumes):
      #- /Volumes/MySSD:/host_root/ExternalDrive:ro

Start the Container: Open a terminal in the Bmus-Docker folder and run:

docker compose up -d

Once the image has loaded and appears in Docker Desktop, you are ready to proceed.

Windows

Important:

Open .yaml from the ZIP file and replace the content of the file with the following:

YAML

services:
  bmus:
    image: backmeupscotty/bmus:latest
    container_name: bmus_backup
    restart: unless-stopped
    privileged: true
    cap_add:
      - SYS_ADMIN
      - DAC_READ_SEARCH
    environment:
      - TZ=Europe/Berlin # change to your time zone
    volumes:
      - ./config:/config
      # MAP YOUR WINDOWS DRIVES HERE:
      # Format: Drive:/Path:/host_root/Path
      - C:/Users/YourName:/host_root/YourName:ro
      # External Drive D:
      #- D:/Photos:/host_root/D/Photos:ro

Start the Container: Open a terminal in the Bmus-Docker folder and run:

docker compose up -d

Once the image has loaded and appears in Docker Desktop, you are ready to proceed.

Step 4: Create a Shortcut (Alias) for Docker

Mac/Linux/Raspberry Pi

To use BmuS commands on your host, use the wrapper bmus in the ZIP-File. The wrapper sends your commands (including flags) to the docker container. Without the wrapper, sending commands to the container is much more complicated. You would always have to use a construct such as docker exec -it bmus_backup /app/bmus.sh

This is what the wrapper code looks like:

#!/bin/bash

# Container is running?
if [ ! "$(sudo docker ps -q -f name=bmus_backup)" ]; then
    echo "Error: BmuS container is not running!"
    echo "Please start it first: sudo docker compose up -d"
    exit 1
fi

# Pass the command to the container
# “$@” passes all arguments (such as --restore --list) 1:1
sudo docker exec -it -e CONFIG_FILE=/config/bmus.conf bmus_backup /app/bmus.sh "$@"

Make it executable: sudo chmod +x /path/to/Bmus-Docker/bmus

Windows

Open Notepad, copy the following code and save it to the root folder of Bmus-Docker as bmus.bat:

@echo off
REM ==========================================
REM BmuS wrapper for Windows
REM Forward commands to the Docker container
REM ==========================================

docker exec -it bmus_backup env CONFIG_FILE="/config/bmus.conf" /app/bmus.sh %*

Run a Backup

Windows

Open terminal, change to Bmus-Docker directory (or were bmus.bat is) and type:

bmus.bat

or send the command into the container, if you don’t want to use the wrapper.

docker exec -it bmus_backup env CONFIG_FILE="/config/bmus.conf" /app/bmus.sh

Optional for Windows

If you want to call BmuS from anywhere (without always having to navigate to the folder first), you must add the folder containing the .bat file to the Windows PATH variable.

Press the Windows key + R, type sysdm.cpl, and press Enter.
Go to the Advanced tab -> Environment Variables.
In the lower section (“System variables”), find the line Path and click Edit.
Click New and paste the path to your folder (e.g., C:\Users\YourName\Bmus-Docker).
Confirm everything with OK.

If you then restart your terminal, you can simply type bmus wherever you are, and Windows will find the script automatically.

Mac/Linux/Pi

Open terminal, change to Bmus-Docker directory (or were bmus is) and type:

sudo bash bmus

or, if you don’t use the wrapper, send the command into the container:

sudo docker exec -it -e CONFIG_FILE=/config/bmus.conf bmus_backup /app/bmus.sh

Flags

You can run BmuS with flags.

Automated Backups

You don’t have to start BmuS manually. You can also set it to start at times you specify. Please read this document.

Flowchart

Here you can see how BmuS works in a container. In this example the folder Bmus-Docker is on a UGREEN-NAS and an external HD is mounted to the UGREEN NAS.

Option A: Native Installation (Linux / Raspberry Pi)

1. Download & Install

2. Run

Automated Backups

Option B: Docker Installation

Step 1: Preparation (All OS)

Docker install on Linux/Raspberry Pi

Optional: Portainer installation

Create a “memory” for Portainer

Start the Portainer container

Open and set up Portainer

The dashboard

Docker install on a Mac or Windows

Step 2: Download & configure BmuS

Notes on configuring bmus.conf and backup paths

Step 3: Download and install Docker image

Windows

Start the Container: Open a terminal in the Bmus-Docker folder and run:

Step 4: Create a Shortcut (Alias) for Docker

Run a Backup

Windows

Mac/Linux/Pi

Flags

Automated Backups

Flowchart

Next

Searching in