Startup, Shutdown, and Initial Setup

This page describes the procedures for starting, stopping, and initial setup of the Fess server.

Important

Before starting Fess, you must start OpenSearch. If OpenSearch is not running, Fess will not function correctly.

Startup Methods

The startup procedure varies depending on the installation method.

TAR.GZ Version

Start OpenSearch

$ cd /path/to/opensearch-3.3.0
$ ./bin/opensearch

To start in the background:

$ ./bin/opensearch -d

Start Fess

$ cd /path/to/fess-15.3.0
$ ./bin/fess

To start in the background:

$ ./bin/fess -d

Note

Startup may take several minutes. You can check the startup status in the log file (logs/fess.log).

ZIP Version (Windows)

Start OpenSearch

Open the OpenSearch installation directory
Double-click opensearch.bat in the bin folder

Or from command Prompt:

c:\> cd c:\opensearch-3.3.0
c:\opensearch-3.3.0> bin\opensearch.bat

Start Fess

Open the Fess installation directory
Double-click fess.bat in the bin folder

Or from command Prompt:

c:\> cd c:\fess-15.3.0
c:\fess-15.3.0> bin\fess.bat

RPM/DEB Version (chkconfig)

Start OpenSearch:

$ sudo service opensearch start

Start Fess:

$ sudo service fess start

check startup status:

$ sudo service fess status

RPM/DEB Version (systemd)

Start OpenSearch:

$ sudo systemctl start opensearch.service

Start Fess:

$ sudo systemctl start fess.service

check startup status:

$ sudo systemctl status fess.service

Enable automatic startup:

$ sudo systemctl enable opensearch.service
$ sudo systemctl enable fess.service

Docker Version

Start using Docker compose:

$ docker compose -f compose.yaml -f compose-opensearch2.yaml up -d

check startup status:

$ docker compose -f compose.yaml -f compose-opensearch2.yaml ps

check logs:

$ docker compose -f compose.yaml -f compose-opensearch2.yaml logs -f fess

Verify Startup

Verify that Fess has started successfully.

Health check

Access the following URL using a browser or curl command:

http://localhost:8080/

If started successfully, the Fess search screen will be displayed.

check from command line:

$ curl -I http://localhost:8080/

If HTTP/1.1 200 OK is returned, it has started successfully.

check Logs

check the startup logs to ensure there are no errors.

TAR.GZ/ZIP version:

$ tail -f /path/to/fess-15.3.0/logs/fess.log

RPM/DEB version:

$ sudo tail -f /var/log/fess/fess.log

Or use journalctl:

$ sudo journalctl -u fess.service -f

Docker version:

$ docker compose -f compose.yaml -f compose-opensearch2.yaml logs -f fess

Tip

When started successfully, a message like the following will be displayed in the logs:

INFO  Boot - Fess is ready.

Access via Browser

Access the following URLs to verify the web interface.

Search Screen

URL: http://localhost:8080/

The Fess search screen will be displayed. In the initial state, no search results will be displayed because no crawl configuration has been performed.

Admin Screen

URL: http://localhost:8080/admin

Default administrator account:

Username: admin
Password: admin

Warning

Important Security Notice

You must change the default password. Especially in production environments, it is strongly recommended to change the password immediately after the first login.

Initial Setup

After logging into the admin screen, perform the following initial configuration.

Step 1: change Administrator Password

Log in to the admin screen (http://localhost:8080/admin)
click “System” → “User” from the left menu
click the admin user
Enter a new password in the “Password” field
click the “confirm” button
click the “Update” button

Important

Passwords should meet the following criteria:

8 characters or more
combination of uppercase letters, lowercase letters, numbers, and symbols
Not easily guessed

Step 2: create crawl configuration

create a configuration to crawl target sites or file systems.

click “crawler” → “Web” from the left menu
click the “New” button
Enter required information:
- Name: Name of the crawl configuration (e.g., company Website)
- URL: Target URL for crawling (e.g., https://www.example.com/)
- Max Access count: Maximum number of pages to crawl
- Interval: crawl interval (milliseconds)
click the “create” button

Step 3: Execute crawl

click “System” → “Scheduler” from the left menu
click the “Start Now” button for the “Default crawler” job
Wait for the crawl to complete (progress can be checked on the dashboard)

Step 4: Verify Search

Access the search screen (http://localhost:8080/)
Enter a search keyword
Verify that search results are displayed

Note

crawling may take time. For large-scale sites, it may take from several hours to several days.

Other Recommended Settings

For production environments, consider the following settings.

configure Mail Server

configure the mail server to receive failure notifications and reports via email.

click “System” → “General” from the left menu
click the “Mail” tab
Enter SMTP server information
click the “Update” button

configure Time Zone

click “System” → “General” from the left menu
Set “Time Zone” to an appropriate value (e.g., Asia/Tokyo)
click the “Update” button

Adjust Log Level

In production environments, you can adjust the log level to reduce disk usage.

Edit the configuration file (app/WEB-INF/classes/log4j2.xml).

For details, refer to the administrator guide.

Shutdown Methods

TAR.GZ/ZIP Version

Stop Fess

Kill the process:

$ ps aux | grep fess
$ kill <PID>

Or, stop from the console with ctrl+c (if running in the foreground).

Stop OpenSearch:

$ ps aux | grep opensearch
$ kill <PID>

RPM/DEB Version (chkconfig)

Stop Fess:

$ sudo service fess stop

Stop OpenSearch:

$ sudo service opensearch stop

RPM/DEB Version (systemd)

Stop Fess:

$ sudo systemctl stop fess.service

Stop OpenSearch:

$ sudo systemctl stop opensearch.service

Docker Version

Stop containers:

$ docker compose -f compose.yaml -f compose-opensearch2.yaml stop

Stop and remove containers:

$ docker compose -f compose.yaml -f compose-opensearch2.yaml down

Warning

To also delete volumes with the down command, add the -v option. In this case, all data will be deleted, so use with caution.

Restart Methods

TAR.GZ/ZIP Version

Stop and then start.

RPM/DEB Version

chkconfig:

$ sudo service fess restart

systemd:

$ sudo systemctl restart fess.service

Docker Version

$ docker compose -f compose.yaml -f compose-opensearch2.yaml restart

Troubleshooting

Won’t Start

Verify OpenSearch is running
```
$ curl http://localhost:9200/
```
If OpenSearch is not running, start OpenSearch first.
check for port conflicts
```
$ sudo netstat -tuln | grep 8080
```
If port 8080 is already in use, change the port number in the configuration file.
check logs

Identify the problem from error messages.
Verify Java version
```
$ java -version
```
Verify that Java 21 or later is installed.

For detailed troubleshooting, refer to Troubleshooting.

Next Steps

After Fess has started successfully, refer to the following documentation to begin operation:

Administrator Guide: Details on crawl configuration, search settings, and system settings
Security configuration - Security configuration for production environments
Troubleshooting - common problems and solutions
Upgrade Procedure - Version upgrade procedures
Uninstallation Procedure - Uninstall procedures

Menu

Startup, Shutdown, and Initial Setup

Startup Methods

TAR.GZ Version

Start OpenSearch

Start Fess

ZIP Version (Windows)

Start OpenSearch

Start Fess

RPM/DEB Version (chkconfig)

RPM/DEB Version (systemd)

Docker Version

Verify Startup

Health check

check Logs

Access via Browser

Search Screen

Admin Screen

Initial Setup

Step 1: change Administrator Password

Step 2: create crawl configuration

Step 3: Execute crawl

Step 4: Verify Search

Other Recommended Settings

configure Mail Server

configure Time Zone

Adjust Log Level

Shutdown Methods

TAR.GZ/ZIP Version

Stop Fess

RPM/DEB Version (chkconfig)

RPM/DEB Version (systemd)

Docker Version

Restart Methods

TAR.GZ/ZIP Version

RPM/DEB Version

Docker Version

Troubleshooting

Won’t Start

Next Steps