Installation Methods
Fess provides distributions in ZIP archives, RPM/DEB packages, and Docker images. Using Docker allows you to easily set up Fess on Windows, Mac, and other platforms.
Note
This page explains setup on Windows using Docker. Users on Linux or macOS can follow similar steps, but the Docker Desktop installation differs by platform. For details, refer to the Docker documentation.
For production environments, be sure to refer to Fess Installation Guide. For system requirements, see System Requirements.
Warning
Important Notes for Production Environments
Running with the embedded OpenSearch is not recommended for production environments or load testing. Always set up an external OpenSearch server.
Setup Overview
Follow these steps in order:
Install Docker Desktop
Configure the OS (adjust vm.max_map_count)
Download Fess startup files
Start Fess and verify operation
Installing Docker Desktop
If Docker Desktop is not already installed, please follow these steps.
Download
Download the installer for your OS from Docker Desktop.
Running the Installer
Double-click the downloaded installer to start installation.
Confirm that “Install required Windows components for WSL 2” or “Install required Enable Hyper-V Windows Features” is selected, and click the OK button.
When installation is complete, click the “close” button to close the screen.
Starting Docker Desktop
Click “Docker Desktop” in the Windows menu to start it.
After Docker Desktop starts, the terms of service will be displayed. Check “I accept the terms” and click the “Accept” button.
A tutorial start prompt will appear, but here we’ll click “Skip tutorial” to skip it. After clicking “Skip tutorial”, the Dashboard will be displayed.
Configuration
To allow OpenSearch to run as a Docker container, adjust the “vm.max_map_count” value on the OS side. The configuration method differs depending on your environment, so refer to “Set vm.max_map_count to at least 262144” for configuration methods for each environment.
Setting Up Fess
Creating Startup Files
Create a directory and download compose.yaml and compose-opensearch3.yaml.
Note
compose-opensearch3.yaml is an additional configuration file for using OpenSearch 3.x. It is used in combination with compose.yaml.
You can also download them using the curl command as follows:
Starting Fess
Start Fess with the docker compose command.
Open a command prompt, navigate to the folder containing the compose.yaml file, and execute the following command:
Note
Startup may take several minutes. You can check the logs with the following command:
You can exit the log display with Ctrl+C.
Verification
Note
Once startup is complete, access the following URLs in your browser to verify.
Search: http://localhost:8080/
Admin UI: http://localhost:8080/admin/
The default administrator account username/password is admin/admin.
Warning
Important Security Notice
Be sure to change the default password. Especially in production environments, it is strongly recommended to change the password immediately after the first login.
The administrator account is managed by the application server. In Fess’s admin UI, users authenticated with the fess role by the application server are treated as administrators.
Other
Stopping Fess
To stop Fess, execute the following command in the folder where you started Fess:
To stop and remove containers:
Warning
To also remove volumes with the down command, add the -v option. Note that this will delete all data.
Changing Administrator Password
You can change the password on the User edit page in the admin UI.
Access http://localhost:8080/admin/ and log in.
Select “User” from the top-right menu.
Open the edit page for the admin user and change the password.
Next Steps
Now that Fess is set up, refer to the following documentation to get started:
Startup, Shutdown, and Initial Setup — Detailed startup, stop, and configuration
Fess Administrator Guide — Administrator guide (crawl settings, user management, etc.)
Fess User Guide — User guide (how to search)
If you encounter any issues, refer to Troubleshooting.