Breached password detection is a critical component of secure applications.    Read the white paper

FusionAuth logo
FusionAuth logo
  • Features
    FusionAuth Reactor

    FusionAuth Reactor is a powerful suite of features developed to extend FusionAuth's core functionality.

    • Flexible Architecture   Flexible Architecture
    • Auth the Way You Want It   Auth the Way You Want It
    • Security & Compliance   Security & Compliance
    • Ultimate Password Control   Ultimate Password Control
    • Customizable User Experience   Customizable User Experience
    • Advanced Registration Forms   Advanced Registration Forms
    • Built for Devs   Built for Devs
    • User Management & Reporting   User Management & Reporting
    • Scalability   Scalability
    • Breached Password Detection   Breached Password Detection
    • Connectors   Connectors
    • FusionAuth Reactor   FusionAuth Reactor
  • Pricing
  • Docs
  • Downloads
  • Resources
    FusionAuth Resources
    • Upgrade from SaaS
    • Upgrade from Open Source
    • Upgrade from Home Grown
    • Blog   Blog
    • Forum   Forum
    • Community & Support   Community & Support
    • Customer & Partners   Customers & Partners
    • Video & Podcasts   Videos & Podcasts
    • Tech Guides   Getting Started
  • Expert Advice
    Expert Advice for Developers

    Learn everything you need to know about authentication, authorization, identity, and access management from our team of industry experts.

    • Authentication   Authentication
    • CIAM   CIAM
    • Identity Basics   Identity Basics
    • OAuth   OAuth
    • Security   Security
    • Tokens   Tokens
    • Dev Tools   Dev Tools
  • Account
Navigate to...
  • Welcome
  • Getting Started
  • 5-Minute Setup Guide
  • Reactor
  • Core Concepts
    • Overview
    • Users
    • Roles
    • Groups
    • Registrations
    • Applications
    • Tenants
    • Identity Providers
    • Authentication and Authorization
    • Integration Points
    • Roadmap
  • Installation Guide
    • Overview
    • System Requirements
    • Server Layout
    • Cluster
    • Docker
    • Fast Path
    • Kickstart™
    • Homebrew
    • Packages
    • Database
    • FusionAuth App
    • FusionAuth Search
    • Securing
    • Upgrading
  • APIs
    • Overview
    • Authentication
    • Errors
    • Actioning Users
    • Applications
    • Audit Logs
    • Connectors
      • Overview
      • Generic
      • LDAP
    • Consent
    • Emails
    • Event Logs
    • Families
    • Forms
    • Form Fields
    • Groups
    • Identity Providers
      • Overview
      • Apple
      • Facebook
      • Google
      • HYPR
      • Twitter
      • OpenID Connect
      • SAML v2
      • External JWT
    • Integrations
    • JWT
    • Keys
    • Lambdas
    • Login
    • Passwordless
    • Registrations
    • Reports
    • System
    • Tenants
    • Themes
    • Two Factor
    • Users
    • User Actions
    • User Action Reasons
    • User Comments
    • Webhooks
  • Client Libraries
    • Overview
    • Dart
    • Go
    • Java
    • JavaScript
    • .NET Core
    • Node
    • PHP
    • Python
    • Ruby
    • Typescript
  • Themes
    • Overview
    • Localization
    • Examples
  • Email & Templates
    • Overview
    • Configure Email
    • Email Templates
  • Events & Webhooks
    • Overview
    • Events
    • Writing a Webhook
    • Securing Webhooks
  • Example Apps
    • Overview
    • Go
    • Java
    • JavaScript
    • .NET Core
    • PHP
    • Python
    • Ruby
  • Lambdas
    • Overview
    • Apple Reconcile
    • External JWT Reconcile
    • Facebook Reconcile
    • Google Reconcile
    • HYPR Reconcile
    • JWT Populate
    • LDAP Connector Reconcile
    • OpenID Connect Reconcile
    • SAML v2 Populate
    • SAML v2 Reconcile
    • Twitter Reconcile
  • Identity Providers
    • Overview
    • Apple
    • Facebook
    • Google
    • HYPR
    • Twitter
    • OpenID Connect
      • Overview
      • Azure AD
      • Github
      • Discord
    • SAML v2
      • Overview
      • ADFS
    • External JWT
      • Overview
      • Example
  • Connectors
    • Overview
    • Generic Connector
    • LDAP Connector
    • FusionAuth Connector
  • Integrations
    • Overview
    • CleanSpeak
    • Kafka
    • Twilio
  • OpenID Connect & OAuth 2.0
    • Overview
    • Endpoints
    • Tokens
  • SAML v2 IdP
    • Overview
    • Google
    • Zendesk
  • Plugins
    • Writing a Plugin
    • Password Encryptors
  • Guides
    • Overview
    • Advanced Registration Forms
    • Breached Password Detection
    • Migration
    • Passwordless
    • Securing Your APIs
    • Silent Mode
  • Tutorials
    • Overview
    • Setup Wizard & First Login
    • Register/Login a User
    • Migrate Users
    • JSON Web Tokens
    • Authentication Tokens
    • Start and Stop FusionAuth
    • Switch Search Engines
    • User Account Lockout
    • Two Factor
  • Reference
    • CORS
    • Configuration
    • Data Types
    • Known Limitations
    • Password Encryptors
  • Release Notes
  • Troubleshooting

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

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.

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.

version: '3'

services:
  db:
    image: postgres:11.9-alpine
    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_APP_MEMORY}
      SEARCH_TYPE: database
      FUSIONAUTH_APP_URL: http://fusionauth:9011
    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.

version: '3'

services:

  search:
    image: docker.elastic.co/elasticsearch/elasticsearch:7.8.1
    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:
      SEARCH_TYPE: elasticsearch
      SEARCH_SERVERS: http://search:9200
    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 wil 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 works 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 configation 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 being, 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. The path refers to what the docker container expects.

  • Configure docker-compose.yml to pass the environment variable set by .env into 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 use a kickstart.json at startup.

version: '3'

services:
  db:
    image: postgres:9.6
    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:

Quick Links

  • Download
  • Pricing
  • Enterprise Sales FAQ
  • Contact Us
  • Jobs (come work with us)
  • My Account

Resources

  • Docs
  • Blog
  • Community & Support
  • Upgrade from SaaS
  • Upgrade from Homegrown
  • Upgrade from Open Source

Everything Else

  • Privacy Policy
  • Product Privacy Policy
  • License
  • License FAQ
  • Security (contact, bug bounty, etc)
  • Technical Support

Connect with Us

logo
Subscribe for Updates
We only send dev friendly newsletters. No marketing fluff!
© 2020 FusionAuth