Using FusionAuth on Docker

Docker Compose

All of the FusionAuth Docker images may be found on Docker Hub.

If you’re looking for a complete configuration to get up and running quickly, use our Docker Compose example. The reference docker-compose.yml will install FusionAuth without the enhanced search capability that Elasticsearch provides. If you would like to install FusionAuth including Elasticsearch for improved search capability, include the reference docker-compose.override.yml in the install steps below.

The following are examples and may not be the most recent version. Refer to the following link in GitHub to find the latest version of our reference configuration.

curl -o docker-compose.yml https://raw.githubusercontent.com/FusionAuth/fusionauth-containers/master/docker/fusionauth/docker-compose.yml
curl -o .env https://raw.githubusercontent.com/FusionAuth/fusionauth-containers/master/docker/fusionauth/.env
docker-compose up

curl -o docker-compose.yml https://raw.githubusercontent.com/FusionAuth/fusionauth-containers/master/docker/fusionauth/docker-compose.yml
curl -o docker-compose.override.yml https://raw.githubusercontent.com/FusionAuth/fusionauth-containers/master/docker/fusionauth/docker-compose.override.yml
curl -o .env https://raw.githubusercontent.com/FusionAuth/fusionauth-containers/master/docker/fusionauth/.env
docker-compose up

POSTGRES_USER=postgres
POSTGRES_PASSWORD=postgres
# Prior to version 1.19.0, using DATABASE_USER
DATABASE_USER=fusionauth
# >= 1.19.0, using DATABASE_USERNAME
DATABASE_USERNAME=fusionauth
DATABASE_PASSWORD=hkaLBM3RVnyYeYeqE3WI1w2e4Avpy0Wd5O3s3

ES_JAVA_OPTS="-Xms512m -Xmx512m"

# Prior to version 1.19.0, using FUSIONAUTH_MEMORY
FUSIONAUTH_MEMORY=512M
# >= 1.19.0, using FUSIONAUTH_APP_MEMORY
FUSIONAUTH_APP_MEMORY=512M

version: '3'

services:
  db:
    image: postgres:12.9
    environment:
      PGDATA: /var/lib/postgresql/data/pgdata
      POSTGRES_USER: ${POSTGRES_USER}
      POSTGRES_PASSWORD: ${POSTGRES_PASSWORD}
    # Un-comment to access the db service directly
#   ports:
#     - 5432:5432
    networks:
      - db
    restart: unless-stopped
    volumes:
      - db_data:/var/lib/postgresql/data

  fusionauth:
    image: fusionauth/fusionauth-app:latest
    depends_on:
      - db
    environment:
      DATABASE_URL: jdbc:postgresql://db:5432/fusionauth
      # Prior to version 1.19.0, use this deprecated name
      # DATABASE_ROOT_USER: ${POSTGRES_USER}
      DATABASE_ROOT_USERNAME: ${POSTGRES_USER}
      DATABASE_ROOT_PASSWORD: ${POSTGRES_PASSWORD}
      # Prior to version 1.19.0, use this deprecated name
      # DATABASE_USER: ${DATABASE_USER}
      DATABASE_USERNAME: ${DATABASE_USERNAME}
      DATABASE_PASSWORD: ${DATABASE_PASSWORD}
      # Prior to version 1.19.0, use this deprecated names
      # FUSIONAUTH_MEMORY: ${FUSIONAUTH_MEMORY}
      # FUSIONAUTH_SEARCH_ENGINE_TYPE: database
      # FUSIONAUTH_URL: http://fusionauth:9011
      # FUSIONAUTH_RUNTIME_MODE: development
      FUSIONAUTH_APP_MEMORY: ${FUSIONAUTH_APP_MEMORY}
      FUSIONAUTH_APP_RUNTIME_MODE: development
      FUSIONAUTH_APP_URL: http://fusionauth:9011
      SEARCH_TYPE: database


    networks:
     - db
    restart: unless-stopped
    ports:
      - 9011:9011
    volumes:
      - fa_config:/usr/local/fusionauth/config

networks:
  db:
    driver: bridge

volumes:
  db_data:
  fa_config:

version: '3'

services:

  search:
    image: docker.elastic.co/elasticsearch/elasticsearch:7.17.0
    environment:
      cluster.name: fusionauth
      bootstrap.memory_lock: "true"
      discovery.type: single-node
      ES_JAVA_OPTS: ${ES_JAVA_OPTS}
    # Un-comment to access the search service directly
    # ports:
    #  - 9200:9200
    #  - 9300:9300
    networks:
      - search
    restart: unless-stopped
    ulimits:
      memlock:
        soft: -1
        hard: -1
    volumes:
      - es_data:/usr/share/elasticsearch/data

  fusionauth:
    depends_on:
      - search
    environment:
      # Prior to version 1.19.0, use these deprecated variables
      # FUSIONAUTH_SEARCH_ENGINE_TYPE: elasticsearch
      # FUSIONAUTH_SEARCH_SERVERS: http://search:9200
      SEARCH_SERVERS: http://search:9200
      SEARCH_TYPE: elasticsearch
    networks:
      - search

networks:
  search:
    driver: bridge

volumes:
  es_data:

Configuration

Review the Configuration - Environment Variables documentation to customize your deployment.

Docker Services

In the above example configurations you will find a database, search and FusionAuth service. Read below to better understand how each service is configured.

Production Deployment

Elasticsearch has a few runtime requirements that may not be met by default on your host platform. Please review the Elasticsearch Docker production mode guide for more information.

• https://www.elastic.co/guide/en/elasticsearch/reference/7.6/docker.html#docker-cli-run-prod-mode

For example if startup is failing and you see the following in the logs, you will need to increase vm.max_map_count on your host VM.

2018-11-22T12:32:06.779828954Z Nov 22, 2018 12:32:06.779 PM ERROR c.inversoft.maintenance.search.ElasticsearchSilentConfigurationWorkflowTask
  - Silent configuration was unable to complete search configuration. Entering maintenance mode. State [SERVER_DOWN]

2018-11-22T13:00:05.346558595Z ERROR: [2] bootstrap checks failed
2018-11-22T13:00:05.346600195Z [1]: memory locking requested for elasticsearch process but memory is not locked
2018-11-22T13:00:05.346606495Z [2]: max virtual memory areas vm.max_map_count [65530] is too low, increase to at least [262144]

Upgrading

To upgrade FusionAuth when running with docker-compose:

Docker Images

If you want to build your own image starting with our base image, the following Docker image is available.

docker pull fusionauth/fusionauth-app

Kickstart

Using Docker with Kickstart is a powerful combination. Using these technologies together lets you:

• Configure and share development environments

• Create replicable bug reports

• Spin up auth instances with a well known, versioned set of data for continuous integration and testing

All the normal limitations of Kickstart apply (the Kickstart will not run if the database has already been set up with an API key, for example).

It’s easy to get started with Kickstart, but you’ll need to tweak your Docker Compose files a bit. Before you begin, you’ll need a valid kickstart.json file. Note that this file could be called anything, kickstart.json is simply a convention. Check out the Kickstart documentation for more information on writing one.

Once you have a valid kickstart.json file, create a subdirectory in the location of your docker-compose.yml file. It can be named anything; this documentation will use a directory called kickstart. Next, you’ll mount this directory and set the FUSIONAUTH_APP_KICKSTART_FILE variable in the docker-compose.yml file.

Here are the steps to do so:

• In the volumes: section of the fusionauth service, add - ./kickstart:/usr/local/fusionauth/kickstart.

• Modify .env and add the Kickstart configuration variable: FUSIONAUTH_APP_KICKSTART_FILE=/usr/local/fusionauth/kickstart/kickstart.json. This path should be what the docker container expects, not the path on the host.

• Configure docker-compose.yml to pass the environment variable set by .env to the container. Do this by adding FUSIONAUTH_APP_KICKSTART_FILE: ${FUSIONAUTH_APP_KICKSTART_FILE} to the environment section of the fusionauth service.

The following is an example docker-compose.yml file configuring FusionAuth to run the commands in a kickstart.json at startup.

version: '3'

services:
  db:
    image: postgres:12.9
    environment:
      PGDATA: /var/lib/postgresql/data/pgdata
      POSTGRES_USER: ${POSTGRES_USER}
      POSTGRES_PASSWORD: ${POSTGRES_PASSWORD}
# Un-comment to access the db service directly
#    ports:
#      - 5432:5432
    networks:
      - db
    restart: unless-stopped
    volumes:
      - db_data:/var/lib/postgresql/data

  fusionauth:
    image: fusionauth/fusionauth-app:latest
    depends_on:
      - db
    environment:
      DATABASE_URL: jdbc:postgresql://db:5432/fusionauth
      DATABASE_ROOT_USERNAME: ${POSTGRES_USER}
      DATABASE_ROOT_PASSWORD: ${POSTGRES_PASSWORD}
      DATABASE_USERNAME: ${DATABASE_USERNAME}
      DATABASE_PASSWORD: ${DATABASE_PASSWORD}
      FUSIONAUTH_APP_MEMORY: ${FUSIONAUTH_MEMORY}
      FUSIONAUTH_APP_RUNTIME_MODE: development
      FUSIONAUTH_APP_URL: http://fusionauth:9011
      SEARCH_TYPE: database
      FUSIONAUTH_APP_KICKSTART_FILE: ${FUSIONAUTH_APP_KICKSTART_FILE}
    networks:
     - db
    restart: unless-stopped
    ports:
      - 9011:9011
    volumes:
      - fa_config:/usr/local/fusionauth/config
      - ./kickstart:/usr/local/fusionauth/kickstart

networks:
  db:
    driver: bridge

volumes:
  db_data:
  fa_config:

After running docker-compose up you should see a line like this in the output:

io.fusionauth.api.service.system.kickstart.KickstartRunner - Summary

This indicates that Kickstart completed and provides a summary of the configuration changes made by it.

You may also want to check out the Isolated Docker Setups if you want the ability to rapidly stand up different versions and configurations of FusionAuth.

Plugins

You can mount a directory containing a plugin to your Docker container.

Here are the steps to do so:

• In the volumes: section of the fusionauth service, add - ./plugins:/usr/local/fusionauth/plugins.

• Copy your plugin jar file, created by following the instructions, to your local plugins directory.

• Start your Docker file

The following is an example docker-compose.yml file configuring FusionAuth to scan for plugins at startup.

version: '3'

services:
  db:
    image: postgres:12.9
    environment:
      PGDATA: /var/lib/postgresql/data/pgdata
      POSTGRES_USER: ${POSTGRES_USER}
      POSTGRES_PASSWORD: ${POSTGRES_PASSWORD}
# Un-comment to access the db service directly
#    ports:
#      - 5432:5432
    networks:
      - db
    restart: unless-stopped
    volumes:
      - db_data:/var/lib/postgresql/data

  fusionauth:
    image: fusionauth/fusionauth-app:latest
    depends_on:
      - db
    environment:
      DATABASE_URL: jdbc:postgresql://db:5432/fusionauth
      DATABASE_ROOT_USERNAME: ${POSTGRES_USER}
      DATABASE_ROOT_PASSWORD: ${POSTGRES_PASSWORD}
      DATABASE_USERNAME: ${DATABASE_USERNAME}
      DATABASE_PASSWORD: ${DATABASE_PASSWORD}
      FUSIONAUTH_APP_MEMORY: ${FUSIONAUTH_MEMORY}
      FUSIONAUTH_APP_RUNTIME_MODE: development
      FUSIONAUTH_APP_URL: http://fusionauth:9011
      SEARCH_TYPE: database
    networks:
     - db
    restart: unless-stopped
    ports:
      - 9011:9011
    volumes:
      - fa_config:/usr/local/fusionauth/config
      - ./plugins:/usr/local/fusionauth/plugins

networks:
  db:
    driver: bridge

volumes:
  db_data:
  fa_config:

After running docker-compose up you should see a line like this in the output:

INFO  io.fusionauth.api.plugin.guice.PluginModule - Installing plugin [com.mycompany.fusionauth.plugins.guice.MyExampleFusionAuthPluginModule]
INFO  io.fusionauth.api.plugin.guice.PluginModule - Plugin successfully installed

This indicates that the plugin has been installed and can be used.

Accessing the Host Machine

The default FusionAuth docker configuration sets up the network using the bridge configuration. This means that all the hosts defined by docker-compose can access each other. However, it means that any applications running on your host machine cannot be accessed by FusionAuth using localhost.

This is typically only an issue when FusionAuth is accessing resources outside of the Docker network to, for example, send email or request a webhook. If a Rails application is running locally on a Mac and you want FusionAuth, running in Docker, to send a webhook payload to it, localhost won’t work.

In this situation, do one of the following:

• Use host.docker.internal as the hostname; this works on macOS and Windows hosts

• Run a container with your application in Docker

• Install FusionAuth on the host machine, using FastPath or another method

Modifying FusionAuth to use other Docker networking schemes such as host may work, but isn’t fully tested or supported.