Running locally via Docker Pub

Running via docker is easy - after installing Docker (on Mac) and starting it, follow these steps.

Note that /Users/raz is an example - use your own home or any other folder...

# first time, create a local db folder somewhere in your home. (if you are reinstalling it, just remove all its contents)
# cd /Users/raz
# mkdir -p diesel/docker/db
# first time - pull the image locally (image name is raz-diesel):
# docker pull razie/raz-diesel
# then just run the container:
# docker run -p -v/Users/raz/diesel/docker/db:/data/db -it razie/raz-diesel
# and point the browser to localhost:9000

If you need to see the logs / debug custom plugins, then you can run it with a console:

# to run just the container and debug it:
# docker run -p -v/Users/raz/diesel/docker/db:/data/db -it --entrypoint=/bin/bash razie/raz-diesel

Mounting the database volume

The embedded MongoDB uses /data/db for storage. In a normal deployment, you will likely want to mount this to a persistent and backed up volume, so see above the mounting to the local docker/db. This ensures that when upgrading the container image, the database will not be wiped out as well. You can also back it up and recover it separate from the docker container.

This database contains all the data of your local instance, including topics, specs, stories, wikis, runtime data, cron jobs, user accounts etc.

When you start it the first time, it will ask you to login to the central server and clone a reactor - use one of your reactors or a default one like "specs". So whenever you see this screen, it means the /data/db folder was empty. Sometimes this indicates a failure to mount it to a volume.


To update to a new version, just pull and run the new version. Before reinstalling from scratch, make sure to sync your changes.



  • port mapping: we're assuming you have no conflicts on port 9000. If you do have conflicts, you can map any other local port, like 9003
    • if you change the default port mapping, it's easier if you also change the one inside the docker container.

Local configuration

You can access the local configuration by starting the docker server in console mode and changing the configuration file: rk/dist/conf/application.conf.

Using docker-compose

You can run this even easier via docker-compose quite nicely.

  1. Setup the docker-compose file, like this:
version: "2.1"
    image: razie/raz-diesel:latest
      - 9003:9000
    restart: unless-stopped
      - dieseldb:/data/db
        THREADS: 2

      context: ./dieseldocker/config
      dockerfile: ./Dockerfile
    command: ./
    working_dir: /dieseldocker
      - ./dieseldocker:/dieseldocker
      - diesel
      - diesel


The first container is a diesel container, the second one is an optional bootstrap container, which will download the remote cloud configuration on the first startup. This is very useful when embedding diesel into another product.

  1. setup an automated user and password on
  2. update the file with your MYPROJECT, MYEMAIL and MYPASSWORD
  3. bring it up with docker-compose -f diesel-compose.yml up

Configuration options

There are several configuration options when you run diesel locally.

exclude global specs

Ability to exclude certain specifications at the deployment level, i.e. “-deprecated” etc.


Configure http headers

Allow specific diesel installations to configure additional custom headers.

Via ENV variables, for instance:


these would apply to all requests

Building embedded containers

You can also build your own version of the configuration into the docker image, by doing the import above as part of the build and then freezing the container with the database containing the configuration. An issue with that is that this will also overwrite users and running crons etc, so ask support for ideas, if that's a problem.

Was this useful?    

By: Razie | 2018-06-28 .. 2022-04-27 | Tags: academy , reference

Viewed 267 times ( | History | Print ) this page.

You need to log in to post a comment!

© Copyright DieselApps, 2012-2022, all rights reserved.