FusionAuth Container Deployment

FusionAuth Docker images are hosted on Docker Hub. To pull the latest FusionAuth App image, use the following command:

docker pull fusionauth/fusionauth-app:latest

The reference docker-compose.yml defaults to using OpenSearch as the search engine. You can enable optional services using the --profile switch in the Docker Compose command. You can use the switch multiple times to enable several profiles at once.

Available profiles:

• caddy: Enables a Caddy service configured to proxy to FusionAuth on ports 80 and 443.
• mailcatcher: Enables Mailcatcher, a test SMTP server for development and testing.
• kafka: Enables Kafka (and Zookeeper) for receiving Webhook events.
• cleanspeak: Enables Cleanspeak for filtering usernames and profile data for profanity.
• opentelemetry: Enables an OpenTelemetry Collector for monitoring.
• prometheus: Enables Prometheus (can be connected to OpenTelemetry).
• alertmanager: Enables AlertManager to generate alerts for anomalies and errors.

docker compose --profile caddy --profile kafka up

Kubernetes is a supported platform, and the supported installation method is via Helm.

Note that the FusionAuth Helm chart is managed in a separate repository. For detailed instructions, refer to the Kubernetes Install Guide.

A specialized Docker Compose configuration is available for setting up a monitoring stack. This setup includes OpenTelemetry, Prometheus, and Alert Manager.

Location: docker/fusionauth/monitoring/docker-compose.yml

This directory also contains configuration files for these services. For more detailed operational guidance, refer to the official documentation for OpenTelemetry and Prometheus.

Alertmanager works in conjunction with Prometheus to handle and manage alerts. You must provide a configuration file via the ALERTMANAGER_CONFIG_FILE environment variable, which is mounted to /etc/alertmanager/alertmanager-config.yml inside the container.

Ports:

• 9093: Alertmanager web UI

# Example environment variable setup
ALERTMANAGER_CONFIG_FILE: ./alertmanager-config.yml

Cleanspeak provides filtering of usernames and profile data. To use it in a containerized environment, you must provide a Cleanspeak license and configure the following environment variables in the cleanspeak service:

• DATABASE_URL: jdbc:postgresql://db:5432/cleanspeak
• DATABASE_ROOT_USERNAME: ${POSTGRES_USER}
• DATABASE_ROOT_PASSWORD: ${POSTGRES_PASSWORD}
• DATABASE_USERNAME: ${DATABASE_USER}
• DATABASE_PASSWORD: ${DATABASE_PASSWORD}
• CLEANSPEAK_APP_MEMORY: ${CLEANSPEAK_APP_MEMORY}
• LICENSE_ID: ${CLEANSPEAK_LICENSE_ID}
• SEARCH_SERVERS: http://search:9200

cleanspeak:
  image: cleanspeak/cleanspeak-app:latest
  profiles:
    - cleanspeak
  environment:
    DATABASE_URL: jdbc:postgresql://db:5432/cleanspeak
    LICENSE_ID: ${CLEANSPEAK_LICENSE_ID}
    SEARCH_SERVERS: http://search:9200

The OpenTelemetry service collects metrics from FusionAuth and can push them to Prometheus or other systems. To customize the collector's behavior, you must provide a configuration file via the OPENTELEMETRY_COLLECTOR_CONFIG_FILE environment variable, which is mounted to /etc/opentelemetry/collector-config.yml inside the container.

Ports:

• 8889: Internal collector metrics
• 4318: OTLP HTTP receiver

# Example environment variable setup
OPENTELEMETRY_COLLECTOR_CONFIG_FILE: ./path/to/your/opentelemetry-collector-config.yml

Prometheus can monitor FusionAuth either directly or via OpenTelemetry. Configuration is managed through two primary environment variables that map to files inside the container:

• PROMETHEUS_CONFIG_FILE: Points to the main Prometheus configuration file (mounted to /etc/prometheus/prometheus.yml).
• PROMETHEUS_RULES_FILE: Points to the Prometheus alerting rules file (mounted to /etc/prometheus/rules.yml).

Ports:

• 9090: Prometheus web UI and API

# Example environment variable setup
PROMETHEUS_CONFIG_FILE: ./prometheus.yml
PROMETHEUS_RULES_FILE: ./rules.yml