Docker for Fess

Official Docker images and Docker Compose configurations for Fess, an open-source enterprise search server built on OpenSearch.

About

Fess bundles the search engine and a web-based administration UI, so you can index and search web sites, file systems, and databases without setting up or operating OpenSearch yourself. For full documentation, see the official Fess site.

Features

• Full-text search with faceted navigation, filtering, and suggestions
• Built-in crawlers for web pages, file systems, and databases
• Indexing for MS Office, PDF, HTML, XML, CSV, and 40+ other file formats
• Authentication and access control via LDAP, Active Directory, and SSO
• Web-based administration for crawlers, schedules, and dictionaries
• Distributed architecture with horizontal scaling

Tech Stack

• Search Engine: OpenSearch 3.x
• Application Server: Apache Tomcat (embedded)
• Runtime: Java 21 (Eclipse Temurin)
• Base Images: Alpine Linux (production), Amazon Linux 2023, Ubuntu Noble
• Containerization: Docker & Docker Compose
• Optional Services: OpenSearch Dashboards, MinIO object storage

Quick Start

Prerequisites

System Requirements:

• Docker and Docker Compose installed
• At least 4GB RAM available
• For OpenSearch: vm.max_map_count >= 262144

Set vm.max_map_count (Linux/WSL):

# Temporary
sudo sysctl -w vm.max_map_count=262144

# Permanent
echo 'vm.max_map_count=262144' | sudo tee -a /etc/sysctl.conf

Standard Deployment

# Clone the repository
git clone https://github.com/codelibs/docker-fess.git
cd docker-fess

# Start Fess with OpenSearch
docker compose -f compose.yaml -f compose-opensearch3.yaml up -d

# Access Fess web interface
open http://localhost:8080

With OpenSearch Dashboards

# Start with visualization dashboard
docker compose -f compose.yaml -f compose-opensearch3.yaml -f compose-dashboards3.yaml up -d

# Access services
open http://localhost:8080  # Fess
open http://localhost:5601  # OpenSearch Dashboards

With Object Storage (MinIO)

# Start with MinIO for file storage
docker compose -f compose.yaml -f compose-opensearch3.yaml -f compose-minio.yaml up -d

# Access services
open http://localhost:8080  # Fess
open http://localhost:9001  # MinIO Console

Usage

Basic Search Setup

1. Access Fess Admin: Navigate to http://localhost:8080/admin

   • Default credentials: admin / admin

2. Create a Web Crawler:

   • Go to Crawler > Web
   • Add URL: https://example.com/*
   • Start crawling from System > Scheduler

3. Configure Search:

   • Set crawl schedules, filters, and permissions
   • Monitor crawl status and logs

Environment Variables

Configure Fess behavior through environment variables:

environment:
  # Search backend configuration
  - SEARCH_ENGINE_HTTP_URL=http://search01:9200
  
  # Dictionary and data paths
  - FESS_DICTIONARY_PATH=/usr/share/opensearch/config/dictionary/
  
  # Performance tuning
  - FESS_HEAP_SIZE=1g
  - FESS_JAVA_OPTS=-server -Xms1g -Xmx1g
  
  # Plugin installation
  - FESS_PLUGINS=fess-webapp-semantic-search:15.7.0 fess-ds-wikipedia:15.7.0

Multi-Instance Deployment

Run multiple Fess instances sharing one OpenSearch cluster:

cd compose/multi-instance

# Start OpenSearch + 2 Fess instances
docker compose -f compose.yaml -f compose-fess01.yaml -f compose-fess02.yaml up -d

# Access instances
open http://localhost:8080  # Fess instance 1
open http://localhost:8081  # Fess instance 2

Each instance uses separate indices for data isolation.

Service URLs

Service	URL	Purpose
Fess Web UI	http://localhost:8080	Main search interface
Fess Admin	http://localhost:8080/admin	Administration panel
OpenSearch API	http://localhost:9200	Direct search engine access
OpenSearch Dashboards	http://localhost:5601	Data visualization
MinIO Console	http://localhost:9001	Object storage management

Development

Building Images

Fess Application:

# Build specific version
docker build --rm -t ghcr.io/codelibs/fess:15.7.0 ./fess/15.7/

# Build with custom args
docker build --build-arg FESS_VERSION=15.7.0 -t my-fess ./fess/15.7/

OpenSearch with Fess Plugins:

# Build OpenSearch image
docker build --rm -t ghcr.io/codelibs/fess-opensearch:3.7.0 ./opensearch/3.7/

Project Structure

docker-fess/
├── fess/                    # Fess Docker images
│   ├── 15.7/               # Latest stable version
│   ├── 15.6/               # Previous versions
│   └── snapshot/           # Development builds
├── opensearch/             # OpenSearch images with Fess plugins
│   ├── 3.7/               # Latest OpenSearch
│   └── 3.6/               # Previous versions
├── elasticsearch/          # Elasticsearch images (legacy)
├── compose/                # Docker Compose configurations
│   ├── compose.yaml        # Base Fess service
│   ├── compose-opensearch3.yaml  # OpenSearch 3.x
│   ├── compose-dashboards3.yaml  # OpenSearch Dashboards
│   ├── compose-minio.yaml  # MinIO object storage
│   └── multi-instance/     # Multi-instance setup
└── archive/                # Archived older versions

Configuration Files

Key Configuration Locations:

• /etc/fess/ - Main configuration directory
• /opt/fess/ - Custom configuration overrides
• /var/log/fess/ - Application logs
• /var/lib/fess/ - Variable data storage

Custom Index Configuration:

# Configure separate indices for multi-instance
FESS_JAVA_OPTS="-Dfess.config.index.document.search.index=myapp.search \
                -Dfess.config.index.document.update.index=myapp.update \
                -Dfess.config.index.config.index=myapp_config"

Version Matrix

Fess Version	OpenSearch	Elasticsearch	Java	Base Image
15.7.0	3.7.0	-	21	Alpine/Ubuntu Noble/Amazon Linux 2023
15.6.0	3.6.0	-	21	Alpine/Ubuntu Noble/Amazon Linux 2023
15.5.1	3.5.0	-	21	Alpine/Ubuntu Noble/Amazon Linux 2023
15.4.0	3.4.0	-	21	Alpine/Ubuntu Noble/Amazon Linux 2023
15.3.0	3.3.0	-	21	Alpine/Ubuntu Noble/Amazon Linux 2023
15.2.0	3.2.0	-	21	Alpine/Ubuntu Noble/Amazon Linux 2023
15.1.0	3.1.0	-	21	Alpine/Ubuntu Noble/Amazon Linux 2023
15.0.0	2.15	8.10+	17	Alpine
14.x	2.x	7.17/8.x	11	Alpine

Troubleshooting

Common Issues

Container fails to start:

# Check vm.max_map_count
cat /proc/sys/vm/max_map_count  # Should be >= 262144

# Check container logs
docker compose logs fess01
docker compose logs search01

Out of memory errors:

# Increase heap size
export FESS_HEAP_SIZE=2g
docker compose up -d

Search not working:

# Verify OpenSearch connection
curl http://localhost:9200/_cluster/health

# Check Fess connectivity
docker compose exec fess01 curl http://search01:9200

Data persistence:

# List volumes
docker volume ls | grep compose

# Remove volumes (WARNING: deletes data)
docker volume rm compose_search01_data compose_search01_dictionary

Performance Tuning

For production deployments:

1. Memory allocation:

   • Fess: 2-4GB heap (FESS_HEAP_SIZE=2g)
   • OpenSearch: 50% of available RAM (OPENSEARCH_JAVA_OPTS=-Xms2g -Xmx2g)

2. Storage optimization:

   • Use SSD storage for OpenSearch data volumes
   • Separate OS disk from data volumes

3. Network configuration:

   • Use dedicated network for container communication
   • Configure proper DNS resolution

Advanced Usage

Custom Plugins

Install additional Fess plugins:

environment:
  - FESS_PLUGINS=fess-webapp-semantic-search:15.7.0 fess-ds-wikipedia:15.7.0

SSL/TLS Configuration

Configure HTTPS for production:

# Mount certificate volumes
volumes:
  - ./certs/keystore.jks:/usr/share/fess/keystore.jks:ro
  
environment:
  - FESS_JAVA_OPTS=-Dserver.ssl.key-store=/usr/share/fess/keystore.jks

Backup and Recovery

# Backup OpenSearch data
docker run --rm -v compose_search01_data:/data -v $(pwd):/backup alpine tar czf /backup/opensearch-backup.tar.gz /data

# Restore OpenSearch data
docker run --rm -v compose_search01_data:/data -v $(pwd):/backup alpine tar xzf /backup/opensearch-backup.tar.gz -C /

License

Apache License 2.0

Copyright 2016-2026 CodeLibs Project and the Others.