Docker Installation

This page will help you create an Oauth.Us provider with Docker. This is a great option if you need a simple way to manage and authenticate users but don’t want to rely on an external service. On this documentation page, we will cover:

  • Setting up Docker on your machine
  • Downloading and using the Oauth.Us Docker image
  • Adding applications and users


Before we get started, you will need to have Docker installed on your machine. Docker is currently supported on a wide variety of platforms, including:

  • OS X
  • Linux (Ubuntu, Redhat)
  • Microsoft Windows

Each platform has different installation procedures. If you’ve never installed Docker before, you should check out our tutorial. The tutorial covers Docker basics including installation and running some basic containers. You’ll want to be comfortable with these topics before continuing.


Once you have Docker installed on your target machine, you’ll need to download the official Oauth.Us image along with a MongoDB and Redis image. The easiest way to do this is via docker-compose. docker-compose should have been included in the Docker installation. If can’t find the command on your system, go ahead and install it now. Instructions can be found here.

Let’s create a new composition file called docker-compose.yml.

  image: oauthus/oauthus
   - "8080:8080"
   - "8081:8081"
   - "8082:8082"
   - "8083:8083"
   - "9998:9998"
   - "9999:9999"
   - WEB_IP=
   - API_IP=
   - USER_WEB_PORT=9998
   - USER_APP_PORT=8082
   - OAUTH_PORT=8080
   - redis
   - mongo
  image: redis
  image: mongo

If you don’t feel like typing all this in, you can also download these files from our GitHub repo.

$ git clone

You’ll notice that Oauth.Us requires that you provide several environment variables. You should be able to ignore most of those for now, but you may need to modify the WEB_IP and API_IP values before we get started.

If you’re using Kitematic on OS X or Windows, press the DOCKER CLI button on the lower-left. This will take you to the command-line. Then type the following:

$ docker-machine ip default

Copy the IP address that was printed out into the WEB_IP and API_IP fields.

Otherwise, if you’re running Docker manually on Linux, you can find the host IP via:

$ ifconfig eth0 | grep 'inet addr:' | cut -d: -f2 | awk '{print $1}'

Starting a Provider

You should now be ready to start up a new provider. In the same directory that has your docker-compose.yml file, type the following:

$ docker-compose up

If this is the first time you’ve done this, Docker will automatically download all the images specified by the compose file. On subsequent invocations, the entire stack should only take about 10 seconds to start up.

Congratulations! You now have a functioning Oauth.Us provider. Navigate to to view the Admin dashboard. Please note that the application uses a self-signed SSL certificate. You can include your own official certificate, but let’s ignore that for now. After you proceed, you should see the login screen:


In order to login to the dashboard, use the following credentials:

username: admin
password __admin__init__

If this is the first time you’ve created a provider, you’ll need to register with your email address. This will be used to inform you of any upcoming software updates and issues. After registering, you will be taken to the dashboard, where you’ll be able to add users, create new applications, and register new API endpoints.

Advanced Configuration

Now that you have your provider set up, you may want to consider modifying some default values to make the user experience a bit smoother for yourself and your users.

First, you’ll probably want to include your registration email the next time you start a new provider. Doing so will let you skip the registration page. Modify the Compose file in the following way:

   - REGISTRATION_EMAIL=bobby@acme.corp

We can also add organization specific information. These values are shown in email confirmations.

   - ORG_NAME=Acme
   - ORG_URL=http://acme.corp
   - ORG_HELP=help@acme.corp

Also, if you prefer to use another default username and password for the initial admin user, change the following:

   - ADMIN_ID=superuser
   - ADMIN_PASSWORD=__super__duper__

Production Configuration

There are a few changes you want to make to your Compose file in a production environment. First, you should replace the SSL certificates so that you don’t get any more security warnings from the browser. Oauth.Us assumes that the certificate and key files are named certificate.crt and certificate.key.

   - ./keys:/keys

You also want to make sure that MongoDB saves state across reboots. To enable this, you can use an external data volume.

    - ./mongo:/data/db