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
DATABASE_USER=fusionauth
DATABASE_PASSWORD=hkaLBM3RVnyYeYeqE3WI1w2e4Avpy0Wd5O3s3

ES_JAVA_OPTS=-Xms512m -Xmx512m

FUSIONAUTH_MEMORY=512M

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_USER: ${POSTGRES_USER}
      DATABASE_ROOT_PASSWORD: ${POSTGRES_PASSWORD}
      DATABASE_USER: ${DATABASE_USER}
      DATABASE_PASSWORD: ${DATABASE_PASSWORD}
      FUSIONAUTH_MEMORY: ${FUSIONAUTH_MEMORY}
      FUSIONAUTH_SEARCH_ENGINE_TYPE: database
      FUSIONAUTH_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:

version: '3'

services:

  search:
    image: docker.elastic.co/elasticsearch/elasticsearch:7.6.2
    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:
      FUSIONAUTH_SEARCH_ENGINE_TYPE: elasticsearch
      FUSIONAUTH_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.

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:

If there were migrations required, they’ll be applied automatically to your database if the installation is has a runtime mode of development. If the installation is in production mode, make sure you apply the migrations out of band.

If you have previously been on fusionauth/fusionauth-app:latest you may need to 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.

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