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.7.0
$ ./bin/opensearch

To start in the background:

$ ./bin/opensearch -d

Start Fess

$ cd /path/to/fess-15.7.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

  1. Open the OpenSearch installation directory

  2. Double-click opensearch.bat in the bin folder

Or from Command Prompt:

C:\> cd C:\opensearch-3.7.0
C:\opensearch-3.7.0> bin\opensearch.bat

Start Fess

  1. Open the Fess installation directory

  2. Double-click fess.bat in the bin folder

Or from Command Prompt:

C:\> cd C:\fess-15.7.0
C:\fess-15.7.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

Note

compose.yaml and compose-opensearch3.yaml are not included with Fess itself. They are provided by the docker-fess project (https://github.com/codelibs/docker-fess); obtain the repository and run the following commands inside the compose directory.

Start using Docker Compose:

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

Check startup status:

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

Check logs:

$ docker compose -f compose.yaml -f compose-opensearch3.yaml logs -f fess01

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.7.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-opensearch3.yaml logs -f fess01

Tip

When startup completes successfully, a startup-completion message like the following is shown on the console and in the log:

...Booting the Tomcat: port=8080 contextPath=/
...
Boot successful: url -> http://localhost:8080

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

  1. Log in to the admin screen (http://localhost:8080/admin)

  2. Click “System” → “User” from the left menu

  3. Click the admin user

  4. Enter a new password in the [Password] field

  5. Re-enter the same password in the [Password (Confirm)] field

  6. Click the [Update] button

Important

Passwords should meet the following criteria:

  • 8 characters or more (the required minimum length set by password.min.length)

  • Combination of uppercase letters, lowercase letters, numbers, and symbols

  • Not easily guessed

By default, only the minimum length (8 characters) is required; a combination of character types is not enforced. Character-type requirements can be enabled with settings such as password.require.uppercase.

Step 2: Create Crawl Configuration

Create a configuration to crawl target sites or file systems.

  1. Click “Crawler” → “Web” from the left menu

  2. Click the “New” button

  3. Enter required information:

    • Name: Name of the crawl configuration (e.g., Company Website)

    • URL: Target URL for crawling (e.g., https://www.example.com/). To specify multiple URLs, enter one URL per line

    • Max Access Count: Maximum number of documents to crawl (optional)

    • Interval: Wait time between accesses (milliseconds; default: 10000)

    Note

    Other items (such as user agent, number of threads, and depth) use their default values when left blank.

  4. Click the “Create” button

Step 3: Execute Crawl

  1. Click “System” → “Scheduler” from the left menu

  2. Open the [Default Crawler] job and click the “Start Now” button

  3. Wait for the crawl to complete (progress can be checked on the dashboard)

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-opensearch3.yaml stop

Stop and remove containers:

$ docker compose -f compose.yaml -f compose-opensearch3.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-opensearch3.yaml restart

Troubleshooting

Won’t Start

  1. Verify OpenSearch is running

    $ curl http://localhost:9200/

    If OpenSearch is not running, start OpenSearch first.

  2. Check for port conflicts

    $ sudo netstat -tuln | grep 8080

    If port 8080 is already in use, change the port number.

    • TAR.GZ edition: change FESS_PORT in bin/fess.in.sh

    • ZIP edition (Windows): edit -Dfess.port=8080 directly in bin\fess.in.bat

    • RPM edition: change FESS_PORT in /etc/sysconfig/fess

    • DEB edition: change FESS_PORT in /etc/default/fess

  3. Check logs

    Identify the problem from error messages.

  4. 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: