How to run OB2 with Docker-Compose

First things first,

What is docker-compose?

From their own docs -

Docker Compose is a tool that was developed to help define and share multi-container applications . With Compose, we can create a YAML file to define the services and with a single command, can spin everything up or tear it all down.

Docker can run on almost any OS, its not a HyperVisor nor is it a VM but a container. Containers share the OS kernel with other containers, each running as isolated processes in user space. Containers take up less space than VMs, can handle more applications and require fewer VMs and Operating systems.

If I had to explain it, its an easy way to for you to run multiple containers as a single service/package. You can combine multiple dockers and easily place them on the same network so they can communicate with each other as well as automate placing their “local” data folders in the same location. e.g. benefits/security/isolation that docker provides while making it easy for them to interact with each other like a docker VPC if you will.

Getting Started

Installing Docker

You can install Docker on Mac, Windows and Linux

For Linux users It is recommended you following the guide for Linux as it will install a much newer version then whats released in the default package manager. If you install the package manager version chances are it will not support the latest docker-compose

Installing Docker-Compose

Windows/Mac users, feel free to skip to the next step as docker-compose came bundled with Docker Desktop.

Linux users - Here is the offical guide
Which pretty much breaks down into these 3 steps

sudo curl -L "$(uname -s)-$(uname -m)" -o /usr/local/bin/docker-compose

sudo chmod +x /usr/local/bin/docker-compose
docker-compose --version
`docker-compose version 1.29.2, build 1110ad01`

Downloading OB2’s docker-compose file

Make sure you only download releases from the offical Github repo.

You can download the latest docker-compose file here.

Make sure you save it in the final location you want all your OB2 data located

Tweak docker-compose.yml

It is currently set to listen on port 8069, if you want it to listen on another port or want to limit it to localhost
You can edit line 6

## Default, [Local Port]:[Docker Internal Port]
            - '8069:5000'
## Localhost only on port 8069
            - ''
## Make it accessible via port 5000
            - '5000:5000'

You can also edit where to create the UserData folder (will contain all your saved info, configs, wordlists, envioment, hits, db, etc)

This should work for everyone however I have not tested it on windows and you may need to convert it to a windows dir like it is in the comment

        # Change UserData to the location of where you want UserData folder to be placed
        # This currently assumes your on linux and want the folder in the same location as the docker-compose file
        # You can set a windows dir like 'C:/OB2/UserData/:/app/UserData/' but it will always be 'local dir:docker dir'
            - './UserData:/app/UserData/'

After your done tweaking save and move to the next step

Running OB2 from docker-compose

Linux/Mac Users

  1. Open terminal/CLI in the folder you placed docker-compose.yml
  2. Run command docker-compose up -d
    It can take a few minutes depending on your specs and download speed while it downloads the images and gets them running

If you need to stop it, type docker-compose down

Windows Users

  1. Make sure Docker is running
  2. Open Command Prompt (CTRL + R, Type CMD in the run box)
  3. Goto the folder you placed docker-compose.yml into
  4. Run command docker-compose up -d
    It can take a few minutes depending on your specs and download speed while it downloads the images and gets them running

If you need to stop it, type docker-compose down

Additional Notes

The docker-compose will be running 2 apps, 1 for OB2 and 1 for Watchtown. Watchtower will activily monitor for new updates for OB2 and will auto update when it finds them so you pretty much can run it and never have to touch it again however if you ever do need to manually update you can stop/start the docker.

I have it setup to auto restart OB2 if crashes (hopefully it doesnt) but if it ever does crash and doesnt restart please let me know as we can always add watchdog to the mix, which will auto restart unhealthy/crashed containers.