FusionAuth developer image
FusionAuth developer logo
  • Back to site
  • Expert Advice
  • Blog
  • Developers
  • Downloads
  • Account
  • Contact sales
Navigate to...
  • Welcome
  • Getting Started
  • 5-Minute Setup Guide
  • Release Notes
  • Core Concepts
    • Overview
    • Users
    • Roles
    • Groups
    • Entity Management
    • Registrations
    • Applications
    • Tenants
    • Identity Providers
    • Key Master
    • SCIM
    • Search
    • Authentication and Authorization
    • Integration Points
    • Localization and Internationalization
    • Editions and Features
    • Roadmap
  • Installation Guide
    • Overview
    • System Requirements
    • Server Layout
    • Cloud
    • Cluster
    • Docker
    • Fast Path
    • Kubernetes
      • Overview
      • Deployment Guide
      • Minikube Setup
      • Amazon EKS Setup
      • Google GKE Setup
      • Microsoft AKS Setup
    • Kickstart™
    • Homebrew
    • Packages
    • Database
    • FusionAuth App
    • FusionAuth Search
    • Common Configuration
  • Admin Guide
    • Overview
    • Config Management
    • Licensing
    • Monitoring
    • Proxy Setup
    • Securing
    • Technical Support
    • Troubleshooting
    • Upgrading
  • Migration Guide
    • Overview
    • General
    • Auth0
    • Keycloak
    • Amazon Cognito
    • Tutorial
  • APIs
    • Overview
    • Authentication
    • Errors
    • Actioning Users
    • API Keys
    • Applications
    • Audit Logs
    • Connectors
      • Overview
      • Generic
      • LDAP
    • Consents
    • Emails
    • Entity Management
      • Overview
      • Entities
      • Entity Types
      • Grants
    • Event Logs
    • Families
    • Forms
    • Form Fields
    • Groups
    • Identity Providers
      • Overview
      • Links
      • Apple
      • External JWT
      • Epic Games
      • Facebook
      • Google
      • HYPR
      • LinkedIn
      • Nintendo
      • OpenID Connect
      • SAML v2
      • SAML v2 IdP Initiated
      • Sony PlayStation Network
      • Steam
      • Twitch
      • Twitter
      • Xbox
    • Integrations
    • IP Access Control Lists
    • JWT
    • Keys
    • Lambdas
    • Login
    • Message Templates
    • Messengers
      • Overview
      • Generic
      • Kafka
      • Twilio
    • Multi-Factor/Two Factor
    • Passwordless
    • Reactor
    • Registrations
    • Reports
    • SCIM
      • Overview
      • SCIM EnterpriseUser
      • SCIM Group
      • SCIM Service Provider Config.
      • SCIM User
    • System
    • Tenants
    • Themes
    • Users
    • User Actions
    • User Action Reasons
    • User Comments
    • Webhooks
  • Client Libraries
    • Overview
    • Dart
    • Go
    • Java
    • JavaScript
    • .NET Core
    • Node
    • OpenAPI
    • PHP
    • Python
    • Ruby
    • Typescript
  • Themes
    • Overview
    • Examples
    • Helpers
    • Localization
    • Template Variables
  • Email & Templates
    • Overview
    • Configure Email
    • Email Templates
    • Email Variables
    • Message Templates
  • Events & Webhooks
    • Overview
    • Writing a Webhook
    • Securing Webhooks
    • Events
      • Overview
      • Audit Log Create
      • Event Log Create
      • JWT Public Key Update
      • JWT Refresh
      • JWT Refresh Token Revoke
      • Kickstart Success
      • User Action
      • User Bulk Create
      • User Create
      • User Create Complete
      • User Deactivate
      • User Delete
      • User Delete Complete
      • User Email Update
      • User Email Verified
      • User IdP Link
      • User IdP Unlink
      • User Login Failed
      • User Login Id Duplicate Create
      • User Login Id Duplicate Update
      • User Login New Device
      • User Login Success
      • User Login Suspicious
      • User Password Breach
      • User Password Reset Send
      • User Password Reset Start
      • User Password Reset Success
      • User Password Update
      • User Reactivate
      • User Registration Create
      • User Registration Create Complete
      • User Registration Delete
      • User Registration Delete Complete
      • User Registration Update
      • User Registration Update Complete
      • User Registration Verified
      • User Two Factor Method Add
      • User Two Factor Method Remove
      • User Update
      • User Update Complete
  • Example Apps
    • Overview
    • Dart
    • Go
    • Java
    • JavaScript
    • .NET Core
    • PHP
    • Python
    • Ruby
  • Lambdas
    • Overview
    • Apple Reconcile
    • Client Cred. JWT Populate
    • Epic Games Reconcile
    • External JWT Reconcile
    • Facebook Reconcile
    • Google Reconcile
    • HYPR Reconcile
    • JWT Populate
    • LDAP Connector Reconcile
    • LinkedIn Reconcile
    • Nintendo Reconcile
    • OpenID Connect Reconcile
    • SAML v2 Populate
    • SAML v2 Reconcile
    • SCIM Group Req. Converter
    • SCIM Group Resp. Converter
    • SCIM User Req. Converter
    • SCIM User Resp. Converter
    • Sony PSN Reconcile
    • Steam Reconcile
    • Twitch Reconcile
    • Twitter Reconcile
    • Xbox Reconcile
  • Identity Providers
    • Overview
    • Apple
    • Epic Games
    • External JWT
      • Overview
      • Example
    • Facebook
    • Google
    • HYPR
    • LinkedIn
    • Nintendo
    • OpenID Connect
      • Overview
      • Azure AD
      • Discord
      • Github
    • Sony PlayStation Network
    • Steam
    • Twitch
    • Twitter
    • SAML v2
      • Overview
      • ADFS
    • SAML v2 IdP Initiated
      • Overview
      • Okta
    • Xbox
  • Messengers
    • Overview
    • Generic Messenger
    • Kafka Messenger
    • Twilio Messenger
  • Connectors
    • Overview
    • Generic Connector
    • LDAP Connector
    • FusionAuth Connector
  • Self Service Account Mgmt
    • Overview
    • Updating User Data & Password
    • Add Two-Factor Authenticator
    • Add Two-Factor Email
    • Add Two-Factor SMS
    • Customizing
    • Troubleshooting
  • Advanced Threat Detection
    • Overview
  • Integrations
    • Overview
    • CleanSpeak
    • Kafka
    • Twilio
  • OpenID Connect & OAuth 2.0
    • Overview
    • Endpoints
    • Tokens
  • SAML v2 IdP
    • Overview
    • Google
    • Zendesk
  • Plugins
    • Plugins
    • Writing a Plugin
    • Custom Password Hashing
  • Guides
    • Overview
    • Advanced Registration Forms
    • Breached Password Detection
    • Multi-Factor Authentication
    • Multi-Tenant
    • Passwordless
    • Securing Your APIs
    • Silent Mode
    • Single Sign-on
  • Tutorials
    • Overview
    • User Control & Gating
      • Gate Unverified Users
      • Gate Unverified Registrations
      • User Account Lockout
    • Setup Wizard & First Login
    • Register/Login a User
    • Start and Stop FusionAuth
    • Authentication Tokens
    • Key Rotation
    • JSON Web Tokens
    • Prometheus Setup
    • Switch Search Engines
    • Two Factor (pre 1.26)
  • Reference
    • CORS
    • Configuration
    • Data Types
    • Known Limitations
    • Password Hashes

    Using FusionAuth on Docker

    FusionAuth Docker containers can be used with Docker Compose, Kubernetes, Helm or OpenShift.

    The following example is using Docker Compose but you may find links and examples for kubernetes, Helm and OpenShift in the FusionAuth Containers GitHub repo.

    • Docker Compose

    • Configuration

    • Docker Services

    • Production Deployment

    • Upgrading

    • Docker Images

    • Kickstart

    • Plugins

    • Accessing the Host Machine

    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.

    FusionAuth

    In this example, we will download the docker-compose.yml and the .env files and then start up the configured containers.

    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

    FusionAuth with Elasticsearch

    In this example, we will download the docker-compose.yml, docker-compose.override.yml and the .env files and then start up the configured containers.

    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

    The stock .env file will contain the following values, you will want to modify the DATABASE_PASSWORD and ensure the POSTGRES_USER and POSTGRES_PASSWORD values are correct. You may also override any of these values using environment variables.

    The .env file
    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

    Docker Compose Examples

    FusionAuth

    The following is an example docker-compose.yml file configuring FusionAuth without the Elasticsearch engine. For the most recent version of this example find this file on GitHub.

    docker-compose.yml
    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:

    FusionAuth with Elasticsearch

    The following is an example docker-compose-override.yml which may be included in your working directory next to the above docker-compose.yml to install and configure Elasticsearch. For the most recent version of this example find this file on GitHub.

    docker-compose-overrride.yml
    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.

    Database Service

    At a minimum, you will need to either set the POSTGRES_PASSWORD environment variable in the db service section, or more ideally set the value in the host environment and leave it out of the docker-compose.yml file. Ensure the other properties fit your requirements. Refer to the System Requirements for database version support.

    Search Service

    We currently support Elasticsearch versions 6.3.x - 7.6.x. Later versions may work as well, but may not have been tested for compatibility. Please let us know if you have a requirement for a different version of Elasticsearch. The remainder of the properties can be changed to whatever you need.

    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:

    1. Stop the instance: docker-compose down.

    2. Modify the docker-compose.yml file (or the docker-compose.override.yml file, if applicable) to point to the version of FusionAuth you want. You can see available tags.

    3. Start it up: docker-compose up.

    4. Login to the administrative UI.

    Migrations

    If there were database migrations required, what happens on an upgrade depends on two settings: the runtime mode and the silent mode.

    Prior to version 1.19, migration behavior was different. See below for more.

    If silent mode is set to true, then database migrations will automatically be performed.

    If silent mode is false and the runtime mode is set to development, then the maintenance mode screen will pop up and you will be prompted to complete the migrations there.

    In all other cases the migrations will not be applied, and you’ll have to perform them yourself. If you want to manage your own database upgrades, performing the SQL migrations out of band with another tool or process is a good option.

    Table 1. When Are Database Migrations Applied
    Runtime Mode Silent Mode Migration Behavior

    development

    true

    Migration applied automatically

    development

    false

    Maintenance mode UI displayed, user prompted to run migrations

    production

    true

    Migration applied automatically

    production

    false

    Migration never applied by FusionAuth, must be applied out of band

    See the configuration reference or the silent mode guide for more information. To apply the database migrations out of band see the database upgrade documentation.

    Prior to 1.19

    If the installation is in production mode, apply the migrations out of band.

    When running in development runtime mode, silent mode was enabled based upon the presence of environment variables, such as the database user, and could not explicitly be enabled or disabled.

    Docker tags

    The docker compose file references the latest tag, but that tag is not dynamic, it is only the latest at a point in time. To get the most recently released image, you have a couple of options.

    • You can edit the docker compose file with an explicit tag version. This is a good idea for a production deployment.

    • You can remove the old image first, as otherwise the latest image won’t be used: docker rmi <old image id>. This command may prompt you to remove containers using that image. Since all state is stored in the database, you can safely remove the containers.

    • You can pull the latest image with this command: docker pull fusionauth/fusionauth-app:latest.

    Docker Images

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

    FusionAuth App

    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.

    Feedback

    How helpful was this page?

    See a problem?

    File an issue in our docs repo

    © 2021 FusionAuth
    Subscribe for developer updates