FusionAuth App Installation

Red Hat

To install on a Red Hat based system, use the RPM bundle. Execute this command to install the FusionAuth App RPM (replace <version> with the correct version number):

sudo rpm -i fusionauth-app<version>.rpm

Debian

To install on a Debian based system, use the DEB bundle. Execute this command to install the FusionAuth App DEB (replace <version> with the correct version number):

sudo dpkg -i fusionauth-app<version>.deb

macOS

To install on macOS, use the .zip bundle. Extract the fusionauth-app zip bundle anywhere on the file system. Remember where you extract the file. This location will be referred to as FUSIONAUTH_HOME. We suggest extracting this file to a directory such as /usr/local/fusionauth.

Once the zip bundle has been extracted, the directory structure should look similar to this. If you installed somewhere other the default FUSIONAUTH_HOME, your directory structure will be different, this is only for shown as an example.

/usr/local/fusionauth/bin
/usr/local/fusionauth/config
/usr/local/fusionauth/config/fusionauth.properties
/usr/local/fusionauth/fusionauth-app

Windows

Please note, that versions equal to 1.37.0 and less than 1.40.0 did not have a native Windows install option. It is recommended to plan to install version 1.40.0 or later.

To install on Windows, use the .zip bundle. Extract the fusionauth-app zip bundle anywhere on the file system. Remember where you extract the file. This location will be referred to as FUSIONAUTH_HOME. We suggest extracting this file to a directory such as \fusionauth on Windows.

Once the zip bundle has been extracted, the directory structure should look similar to this. If you installed somewhere other the default FUSIONAUTH_HOME, your directory structure will be different, this is only for shown as an example.

\fusionauth\bin
\fusionauth\config
\fusionauth\config\fusionauth.properties
\fusionauth\fusionauth-app\

Next, install the Windows service by changing to the directory designated as FUSIONAUTH_HOME and then running the install command. For versions less than 1.40.0, adjust the example below to use \fusionauth\fusionauth-app\apache-tomcat\bin instead.

cd \fusionauth\fusionauth-app\bin
FusionAuthApp.exe /install

Development

When in development runtime mode, FusionAuth will enter an interactive Maintenance Mode when installing and upgrading FusionAuth to aid in the configuration of the database and Elasticsearch, and apply necessary database migrations.

Production

Production runtime mode should be configured when deploying FusionAuth to a production environment.

When in production runtime mode, maintenance mode will never run. Maintenance mode is not intended for multi-node deployments and will not reliably coordinate database migrations among the nodes, which can result in a corrupted database schema. Additionally, disabling maintenance mode prevents end-users from navigating to the interactive maintenance mode page rather than the login page at runtime.

In production runtime mode, database migrations will need to be applied out of band using our documented manual method, or using some other external mechanism. See the Upgrade FusionAuth documentation for reference.

In order to enable the production runtime mode, all database and (optional) Elasticsearch configuration properties must be configured properly, see the Configuration Reference. The configured database and Elasticsearch will be expected to be running and ready to accept connections.

Database Configuration

The first step will be to configure the database connection to allow FusionAuth to configure the database.

To complete this step you will need to confirm the database type, host, port and name. The connection type defaults to MySQL with the default MySQL port of 3306. If you are connecting to a PostgreSQL database the default port is 5432, your configuration may be different.

In the Super User credentials section you will need to supply FusionAuth with a username and password to the database so that it may create a new database and configure the FusionAuth schema. The provided credentials must have adequate authority to complete successfully. These credentials are not persisted and only utilized to complete maintenance mode.

# replace password with a secure password, or omit the `IDENTIFIED BY` clause to create user without a password
CREATE USER 'root'@'127.0.0.1' IDENTIFIED BY password;
GRANT ALL PRIVILEGES ON *.* TO 'root'@'127.0.0.1' WITH GRANT OPTION;
FLUSH PRIVILEGES;

The final section labeled FusionAuth credentials will be used to define a new database user to own the FusionAuth schema and connect to the database when FusionAuth starts up. A default username and password have been generated for you, feel free to utilize these values or modify them to suit your InfoSec requirements. These credentials will be created and used by FusionAuth to connect to the database at runtime. These credentials will be saved to the fusionauth.properties configuration file.

Click the submit button once you have completed this form and if the provided credentials and database connection information was correct you will be taken to the next step of the maintenance process or FusionAuth will continue starting up if the configuration is complete.

Search Configuration

If this is your first time starting up FusionAuth we will need to validate your connection to the search engine service and create a search index for use by FusionAuth.

No configuration is required, but you will need to complete this step by clicking on the Submit button to continue. Once this step is complete you will complete the initial configuration using the Setup Wizard.

Database Schema

In the following examples, <root_user> is the name of the root user for your database. The <root_user> must be either the root user or a user that has privileges to create databases. For MySQL, this is generally a user named root, on PostgreSQL, this is generally a user named postgres, your configuration may vary. Run the following SQL commands to configure the database for use by FusionAuth. Additionally, <ordinary_user> and <ordinary_password> are non-superuser accounts that are used to connect to the FusionAuth database.

# Create the fusionauth database, replace <root_user> a valid superuser.
mysql --default-character-set=utf8 -u<root_user> -e "CREATE DATABASE fusionauth CHARACTER SET = 'utf8mb4' COLLATE = 'utf8mb4_bin';"

# Create the non-superuser account in the database, replace <root_user> a valid superuser, <ordinary_user> a valid non-superuser and <ordinary_password> with a secure password.
mysql --default-character-set=utf8mb4 -u<root_user> -e "CREATE USER <ordinary_user> IDENTIFIED BY '<ordinary_password>'"

# Grant ordinary user all authority to fusionauth database, replace <root_user> a valid superuser and <ordinary_user> with your user from above.
mysql --default-character-set=utf8mb4 -u<root_user> -e "GRANT ALL ON fusionauth.* TO '<ordinary_user>'@'%'" fusionauth

# Create FusionAuth schema, run this command from the directory where you have extracted the FusionAuth Database Schema zip, replace <ordinary_user> and <ordinary_password> with the values from above.
mysql --default-character-set=utf8mb4 -u<ordinary_user> -p<ordinary_password> fusionauth < mysql.sql

# Create the fusionauth database, replace <root_user> a valid superuser.
psql -U<root_user> -c "CREATE DATABASE fusionauth ENCODING 'UTF-8' LC_CTYPE 'en_US.UTF-8' LC_COLLATE 'en_US.UTF-8' TEMPLATE template0"

# Note, if installing on Windows, the Encoding values are different, replace the previous command with this version.
psql -U<root_user> -c "CREATE DATABASE fusionauth ENCODING 'UTF-8' LC_CTYPE 'English_United States' LC_COLLATE 'English_United States' TEMPLATE template0;"

# Create the non-superuser account in the database, replace <root_user> a valid superuser, <ordinary_user> a valid non-superuser and <ordinary_password> with a secure password.
psql -U<root_user> -c "CREATE ROLE <ordinary_user> WITH LOGIN PASSWORD '<ordinary_password>';"

# Grant ordinary user all authority to fusionauth database, replace <root_user> a valid superuser and <ordinary_user> with your user from above.
psql -U<root_user> -c "GRANT ALL PRIVILEGES ON DATABASE fusionauth TO <ordinary_user>; ALTER DATABASE fusionauth OWNER TO <ordinary_user>;"

# Create FusionAuth schema, run this command from the directory where you have extracted the FusionAuth Database Schema zip, replace <ordinary_user> with
the value from above.
psql -U<ordinary_user> fusionauth < postgresql.sql

Configuration

Before starting FusionAuth for the first time, you’ll need to add your database connection in the the configuration. The name of this file is fusionauth.properties.

The configuration file may be found in the following directory, assuming you installed in the default locations. If you have installed in an alternate location, the path to this file will be different.

Windows

\fusionauth\config

macOS or Linux

/usr/local/fusionauth/config

For more information about the other configuration options found in this file, see the Configuration Reference section.

Find the default database JDBC url, username and password values, verify this information is correct. The default JDBC url is configured for MySQL, if you’re using PostgreSQL you’ll need to update the URL. See the database.url property documentation in Configuration Reference for more information.

database.url=jdbc:mysql://localhost:3306/fusionauth?serverTimezone=UTC
database.username=fusionauth
database.password=fusionauth

FusionAuth should now be configured, the database should be created and everything should be ready to run. You can start FusionAuth using the instructions in the Start FusionAuth App section above.