# Install FusionAuth App

Learn how to install FusionAuth App on a production server with Docker or from a package.

> For the index of this section of the site, see [llms.txt](https://fusionauth.io/docs/llms.txt)

This guide explains how to install FusionAuth App on your own servers, either as a Docker container or from a package on Linux, macOS, or Windows. To run FusionAuth on your own machine for development, see [Install Locally](https://fusionauth.io/docs/get-started/install.md) instead.

Before you can run FusionAuth, you must also [install a database](https://fusionauth.io/docs/deploy/production/install/database.md).

By default, FusionAuth uses the database as the User search engine. To access advanced search functions, [install a search engine](https://fusionauth.io/docs/deploy/production/install/search.md).

The `fusionauth/fusionauth-app` image runs FusionAuth App. In production, the container connects to a database and search engine that you run separately, and you configure the container with [environment variables](https://fusionauth.io/docs/deploy/production/configuration.md). Each configuration option maps to an environment variable: upper-case the option name and replace periods and dashes with underscores. For example, `database.url` becomes `DATABASE_URL`.

1.  Pick a version. Use a specific version tag, such as `fusionauth/fusionauth-app:1.70.1`, and never `latest`. A pinned tag means every node runs the same version, and an update only happens when you change the tag. To find the current version, see the [release notes](https://fusionauth.io/docs/release-notes.md).
    
2.  Create a file named `fusionauth.env` with the database connection, the runtime mode, and the search engine:
    
    fusionauth.env
    
    ```properties
    DATABASE_URL=jdbc:postgresql://db.example.com:5432/fusionauth
    DATABASE_USERNAME=fusionauth
    DATABASE_PASSWORD=ordinary-user-password
    DATABASE_ROOT_USERNAME=postgres
    DATABASE_ROOT_PASSWORD=super-user-password
    FUSIONAUTH_APP_RUNTIME_MODE=production
    FUSIONAUTH_APP_MEMORY=1G
    SEARCH_TYPE=elasticsearch
    SEARCH_SERVERS=http://search.example.com:9200
    ```
    
    With the root credentials, [silent mode](https://fusionauth.io/docs/deploy/production/install/silent-mode.md) creates the FusionAuth database, the ordinary user, and the schema on the first start. If your database provider doesn't give you a superuser, such as on many managed databases, create the database and user yourself. Then leave out the two `DATABASE_ROOT_` lines and add `FUSIONAUTH_APP_SILENT_MODE=true`.
    
    To use the database for user search instead of a search engine, set `SEARCH_TYPE=database` and leave out `SEARCH_SERVERS`.
    
    Keep this file out of version control. In an orchestrator such as Kubernetes or ECS, pass the same values from the platform's secret store instead.
    
3.  Start the container:
    
    ```shell-session
    $ docker run -d --name fusionauth \
      --env-file fusionauth.env \
      --restart unless-stopped \
      -p 9011:9011 \
      -v fusionauth_config:/usr/local/fusionauth/config \
      fusionauth/fusionauth-app:1.70.1
    ```
    
    The `fusionauth_config` volume keeps the generated configuration across container restarts.
    
4.  Check that FusionAuth is ready. The status endpoint returns `200` once FusionAuth can serve requests:
    
    ```shell-session
    $ curl -s -o /dev/null -w "%{http_code}" http://localhost:9011/api/status
    ```
    
5.  Open `http://<your-server>:9011/admin` and complete the [Setup Wizard](https://fusionauth.io/docs/get-started/first-time-setup.md).
    

Before customers log in, put FusionAuth behind a [reverse proxy](https://fusionauth.io/docs/deploy/production/proxy-setup.md) that terminates TLS, and work through [Harden a Production Instance](https://fusionauth.io/docs/deploy/harden/harden-a-production-instance.md). To run more than one node, see [Cluster](https://fusionauth.io/docs/deploy/production/cluster.md). To run the same configuration with Docker Compose, add a custom image, or load plugins, see [Customize Docker Images](https://fusionauth.io/docs/deploy/production/install/docker-configuration.md). To run FusionAuth on Kubernetes, see [Kubernetes](https://fusionauth.io/docs/deploy/production/kubernetes.md).

These commands will download and unpack the latest version of FusionAuth.

Optionally, provide the following environment variables to the install script to augment behavior:

*   `TARGET_DIR`: The location to install the zip (by default, `$PWD/fusionauth`).
*   `VERSION`: The version to install (by default, the latest stable version).

1.  Copy and paste the code below into a terminal to install the FusionAuth ZIP packages into the current working directory:
    
    ```shell-session
    $ curl -fsSL https://raw.githubusercontent.com/FusionAuth/fusionauth-install/master/install.sh | bash -s && \
    ```
    
2.  [Install and configure a database](https://fusionauth.io/docs/deploy/production/install/database.md).
    
3.  Navigate into the `fusionauth` install directory:
    
    ```shell-session
    $ cd fusionauth
    ```
    
4.  Start your FusionAuth instance:
    
    ```shell-session
    $ bin/startup.sh
    ```
    
5.  Visit [http://localhost:9011](http://localhost:9011) to access the Admin UI.
    

You can find the Fusionauth Homebrew formula on GitHub at [FusionAuth/homebrew-fusionauth](https://github.com/FusionAuth/homebrew-fusionauth). To install this formula, follow the steps below:

1.  Install the tap:
    
    ```shell-session
    $ brew tap fusionauth/homebrew-fusionauth
    ```
    
2.  Trust the tap:
    
    ```shell-session
    $ brew trust fusionauth/fusionauth
    ```
    
3.  Install the FusionAuth services:
    
    ```shell-session
    $ brew install fusionauth-app
    ```
    
4.  [Install and configure a database](https://fusionauth.io/docs/deploy/production/install/database.md).
    
5.  Start FusionAuth with Homebrew services:
    
    ```shell-session
    $ brew services start fusionauth-app
    ```
    
6.  Visit [http://localhost:9011](http://localhost:9011) to access the Admin UI.
    

Homebrew stores the configuration file at `/usr/local/etc/fusionauth/fusionauth.properties` (`$(brew --prefix)/etc/fusionauth/fusionauth.properties`) and the logs at `/usr/local/var/log/fusionauth/`.

1.  Copy and paste the code below into a terminal to install the FusionAuth ZIP packages into the current working directory:
    
    ```shell-session
    $ curl -fsSL https://raw.githubusercontent.com/FusionAuth/fusionauth-install/master/install.sh | bash -s && \
    ```
    
2.  [Install and configure a database](https://fusionauth.io/docs/deploy/production/install/database.md).
    
3.  Navigate into the `fusionauth` install directory:
    
    ```shell-session
    $ cd fusionauth
    ```
    
4.  Start your FusionAuth instance:
    
    ```shell-session
    $ bin/startup.sh
    ```
    
5.  Visit [http://localhost:9011](http://localhost:9011) to access the Admin UI.
    

Note

To use Windows Subsystem for Linux (WSL), follow the [Microsoft documentation to install Debian/Ubuntu using WSL 2](https://docs.microsoft.com/en-us/windows/wsl/about), then use the Linux install directions below.

1.  Copy and paste the code below into PowerShell to install the FusionAuth ZIP packages into the current working directory:
    
    ```powershell
    Invoke-WebRequest -UseBasicParsing -Uri https://raw.githubusercontent.com/FusionAuth/fusionauth-install/main/install.ps1 | iex
    ```
    
2.  [Install and configure a database](https://fusionauth.io/docs/deploy/production/install/database.md).
    
3.  Navigate into the `fusionauth` install directory:
    
    ```powershell
    cd fusionauth
    ```
    
4.  Start your FusionAuth instance:
    
    ```powershell
    bin\startup.ps1
    ```
    
5.  Visit [http://localhost:9011](http://localhost:9011) to access the Admin UI.
    

Optionally, you can register FusionAuth with Windows services:

```powershell
\fusionauth\fusionauth-search\elasticsearch\bin\FusionAuthSearch.exe /install
```

```powershell
\fusionauth\fusionauth-app\bin\FusionAuthApp.exe /install
```

To remove the FusionAuth Windows services, run the commands above, but replace `install` with `uninstall`.

To install on a Red Hat based system, use the RPM bundle.

1.  To install the FusionAuth App RPM, run the following command (replacing `<version>` with your desired version number):
    
    ```shell-session
    $ sudo rpm -i fusionauth-app<version>.rpm
    ```
    
2.  [Install and configure a database](https://fusionauth.io/docs/deploy/production/install/database.md).
    
3.  Start FusionAuth:
    
    ```shell-session
    $ sudo systemctl start fusionauth-app
    ```
    
4.  Visit [http://localhost:9011](http://localhost:9011) to access the Admin UI.
    
5.  Congratulations, you have a working instance of FusionAuth! To set up login for an application, see our [First Time Setup guide](https://fusionauth.io/docs/get-started/first-time-setup.md).
    

To install on a Debian based system, use the DEB bundle.

1.  To install the FusionAuth App DEB, run the following command (replacing `<version>` with your desired version number):
    
    ```shell-session
    $ sudo dpkg -i fusionauth-app<version>.deb
    ```
    
2.  [Install and configure a database](https://fusionauth.io/docs/deploy/production/install/database.md).
    
3.  Start FusionAuth:
    
    ```shell-session
    $ sudo systemctl start fusionauth-app
    ```
    
4.  Visit [http://localhost:9011](http://localhost:9011) to access the Admin UI.
    
5.  Congratulations, you have a working instance of FusionAuth! To set up login for an application, see our [First Time Setup guide](https://fusionauth.io/docs/get-started/first-time-setup.md).
    

On the [Downloads](https://fusionauth.io/download.md) page, find the FusionAuth App package for your target architecture on macOS.

1.  Extract the `fusionauth-app` zip bundle to a directory such as `/usr/local/fusionauth`; this location will be referred to as `FUSIONAUTH_HOME`. Once extracted, the directory structure should look similar to this:
    
    ```plaintext
    /usr/local/fusionauth/bin
    /usr/local/fusionauth/config
    /usr/local/fusionauth/config/fusionauth.properties
    /usr/local/fusionauth/fusionauth-app
    ```
    
2.  [Install and configure a database](https://fusionauth.io/docs/deploy/production/install/database.md).
    
3.  In `FUSIONAUTH_HOME`, run the following command to start FusionAuth:
    
    ```shell-session
    $ <FUSIONAUTH_HOME>/bin/startup.sh
    ```
    

Use one of the following approaches to install FusionAuth on a Windows system:

On the [Downloads](https://fusionauth.io/download.md) page, find the FusionAuth App package for your target architecture on Windows.

1.  Extract the `fusionauth-app` zip bundle to a directory such as `\fusionauth`; this location will be referred to as `FUSIONAUTH_HOME`. Once extracted, the directory structure should look similar to this:
    
    ```plaintext
    \fusionauth\bin
    \fusionauth\config
    \fusionauth\config\fusionauth.properties
    \fusionauth\fusionauth-app\
    ```
    
2.  [Install and configure a database](https://fusionauth.io/docs/deploy/production/install/database.md).
    
3.  Navigate into `FUSIONAUTH_HOME`:
    
    ```powershell
    cd \fusionauth\fusionauth-app\bin
    ```
    
4.  In `FUSIONAUTH_HOME`, run the following command to start FusionAuth:
    
    ```powershell
    \fusionauth\bin\startup.ps1
    ```
    

On the [Downloads](https://fusionauth.io/download.md) page, find the FusionAuth App package for your target architecture on Windows.

1.  Extract the `fusionauth-app` zip bundle to a directory such as `\fusionauth`; this location will be referred to as `FUSIONAUTH_HOME`. Once extracted, the directory structure should look similar to this:
    
    ```plaintext
    \fusionauth\bin
    \fusionauth\config
    \fusionauth\config\fusionauth.properties
    \fusionauth\fusionauth-app\
    ```
    
2.  [Install and configure a database](https://fusionauth.io/docs/deploy/production/install/database.md).
    
3.  Navigate into `FUSIONAUTH_HOME`:
    
    ```powershell
    cd \fusionauth\fusionauth-app\bin
    ```
    
4.  In `FUSIONAUTH_HOME`, run the following command to install the Windows service:
    
    ```powershell
    FusionAuthApp.exe /install
    ```
    
5.  Run the following command to start FusionAuth as a Windows Service:
    
    ```powershell
    net start FusionAuthApp
    ```
    

## Start FusionAuth App

Next, you need to start FusionAuth App and use of the following options to set up the database:

*   Enter [Maintenance Mode](https://fusionauth.io/docs/update/database-migrations.md#maintenance-mode) where you can visually configure and create the database
*   Use [silent mode](https://fusionauth.io/docs/deploy/production/install/silent-mode.md) and allow FusionAuth to automatically configure and create the database

Use the instructions below to start FusionAuth. FusionAuth App depends on the Search Engine, the Search Engine must be started first.

Note

Maintenance Mode makes installation simple. If it is not possible for you to use Maintenance Mode, you can edit the FusionAuth configuration files and leverage [silent mode](https://fusionauth.io/docs/deploy/production/install/silent-mode.md) or install the database schema via the command-line using the [Advanced Installation](#advanced-installation) instructions below.

If you do not plan to use [silent mode](https://fusionauth.io/docs/deploy/production/install/silent-mode.md) or [Maintenance Mode](https://fusionauth.io/docs/update/database-migrations.md#maintenance-mode) to configure FusionAuth, do not start FusionAuth at this point. Instead, skip the to [Advanced Installation](#advanced-installation) section and then return to this section after you have configured FusionAuth and the database via the command-line.

### 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.

Caution

**Troubleshooting MySQL root user issues**

If you are using MySQL, your server might not be configured to allow the `root` user to login except from the hostname `localhost`. Depending on how your system is configured, FusionAuth might use a different IP or hostname such as `127.0.0.1` or `myapp.com`. Therefore, you need to ensure that your MySQL server is configured to allow the `root` user to connect from your specific location. To do this, you can create a separate `root` user with the hostname you are targeting, in the example we are using `127.0.0.1`. Here are the SQL statements for this method:

Create new user method with all permissions to all databases and tables

```sql
# 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.

![Maintenance Mode Database Configuration](https://fusionauth.io/img/docs/get-started/download-and-install/maintenance-mode-database.png)

### 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](https://fusionauth.io/docs/get-started/first-time-setup.md).

![Maintenance Mode Search Configuration](https://fusionauth.io/img/docs/get-started/download-and-install/maintenance-mode-search.png)

## Advanced Installation

These instructions will assist you in editing the FusionAuth configuration file and installing the database schema via the command-line. If you used Maintenance Mode to configure FusionAuth App, you can skip this section.

To manually configure the database schema, you will need to downloaded the corresponding zip file for the version of FusionAuth you'll be installing. Navigate to the [Direct Download](https://fusionauth.io/direct-download.md) page and find the file named `fusionauth-database-schema-<version>.zip`. That zip archive will contain the necessary SQL files to complete this section.

When you extract the contents of the zip archive you will find `mysql.sql` and `postgresql.sql`. Typically, these files are used when building a database from the ground up (in other words, creating the schema, in the next section) and are always provided with each release of FusionAuth. For existing databases, migrations can be run and are included in the `migrations` folder. Not all versions of FusionAuth require a database migration. FusionAuth versions with migrations are highlighted in the [release notes](https://fusionauth.io/docs/release-notes.md).

```plaintext
fusionauth-database-schema/
├── migrations
│   ├── mysql
│   │   ├── 1.1.0.sql
           //...
│   │   ├── 1.33.0.sql
│   └── postgresql
│       ├── 1.1.0.sql
           //...
│       ├── 1.33.0.sql
├── mysql.sql
├── passport-to-fusionauth (less common to reference)
│   ├── mysql.sql
│   └── postgresql.sql
└── postgresql.sql
```

### Database Schema

Caution

**Security**

By default, unless you configure the database connection using Maintenance Mode, FusionAuth is configured to connect to the database named `fusionauth` on `localhost` with the user name `fusionauth` and the password `fusionauth`. For development and testing, you can use these defaults; however, we recommend a more secure password for production systems.

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.

MySQL

```shell
# 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
```

PostgreSQL

```shell
# 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 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.

```shell
/usr/local/fusionauth/config
```

```shell
/usr/local/fusionauth/config
```

```plaintext
\fusionauth\config
```

For more information about the other configuration options found in this file, see the [Configuration Reference](https://fusionauth.io/docs/deploy/production/configuration.md) 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](https://fusionauth.io/docs/deploy/production/configuration.md) for more information.

Note

If you are using MySQL, your `database.url` property must have a parameter at the end like this: `?serverTimezone=UTC`. The `?` character is the same as a standard URL parameter, so if you have additional parameters, you should only have a single `?` and parameters should be separated by `&`.

Database Configuration

```ini
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](#start-fusionauth-app) section above.

## Next Steps

To finish configuring FusionAuth, see [First Time Setup](https://fusionauth.io/docs/get-started/first-time-setup.md). Before you run FusionAuth in production, see [Harden a Production Instance](https://fusionauth.io/docs/deploy/harden/harden-a-production-instance.md).

## Troubleshooting

If you receive a message similar to this one in your system log:

```plaintext
ERROR io.fusionauth.api.service.system.NodeService - Node [c98263dc-7f12-4879-93c1-f1a634912a51] cannot be added. The runtime mode is [Development] and this node in [Production] mode.
```

This means that your nodes are in different runtime modes. This will not work and may cause undetermined behavior. All nodes of a FusionAuth cluster must be running in the same mode, either `Production` or `Development`.

To resolve this issue, take the following steps:

*   Stop all existing nodes, whether they are running as containers or processes.
*   Review configuration to confirm that all nodes are configured with the same runtime mode.
*   Restart the nodes.

Related

[Deploy Packages Learn how to determine which installation packages you need. rpmdeb](https://fusionauth.io/docs/deploy/production/install/packages.md)

[Get Started Get Started Learn what FusionAuth is and how to get started using it. install fusionauth](https://fusionauth.io/docs/get-started.md)

[Update Update a Development Instance of FusionAuth Learn how to update an instance of FusionAuth that isn't used for production purposes. rpm](https://fusionauth.io/docs/update/dev-instance.md)

[Update Update to a Newer Version of FusionAuth Learn how to update FusionAuth instances, FusionAuth Cloud deployments, and client libraries to a newer version. rpm](https://fusionauth.io/docs/update.md)
---

## Other pages in Install

> For the full index of this section, see [Deploy](https://fusionauth.io/docs/llms-deploy.txt).

- [Air-gapping](https://fusionauth.io/docs/deploy/production/install/air-gapping.md): Run FusionAuth with no network access (air-gapped).
- [Install a Database](https://fusionauth.io/docs/deploy/production/install/database.md): Learn how to install the database that FusionAuth will use to store user data.
- [Customize Docker Images](https://fusionauth.io/docs/deploy/production/install/docker-configuration.md): Learn how to configure a Docker image containing FusionAuth to meet the needs of your application.
- [Packages](https://fusionauth.io/docs/deploy/production/install/packages.md): Learn how to determine which installation packages you need.
- [Install a Search Engine](https://fusionauth.io/docs/deploy/production/install/search.md): Learn how to install a search engine for your FusionAuth instance.
- [Silent Mode](https://fusionauth.io/docs/deploy/production/install/silent-mode.md): This is a guide to using silent mode during FusionAuth install and updates.