Folders and files
| Name | Name | Last commit date | ||
|---|---|---|---|---|
Official Docker images and Docker Compose configurations for Fess, an open-source enterprise search server built on OpenSearch.
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.
- 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
- 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
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# 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# 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# 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-
Access Fess Admin: Navigate to http://localhost:8080/admin
- Default credentials: admin / admin
-
Create a Web Crawler:
- Go to Crawler > Web
- Add URL: https://example.com/*
- Start crawling from System > Scheduler
-
Configure Search:
- Set crawl schedules, filters, and permissions
- Monitor crawl status and logs
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.8.0 fess-ds-wikipedia:15.8.0Run 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 2Each instance uses separate indices for data isolation.
| 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 |
Fess Application:
# Build specific version
docker build --rm -t ghcr.io/codelibs/fess:15.8.0 ./fess/15.8/
# Build with custom args
docker build --build-arg FESS_VERSION=15.8.0 -t my-fess ./fess/15.8/OpenSearch with Fess Plugins:
# Build OpenSearch image
docker build --rm -t ghcr.io/codelibs/fess-opensearch:3.8.0 ./opensearch/3.8/docker-fess/
├── fess/ # Fess Docker images
│ ├── 15.8/ # Latest stable version
│ ├── 15.7/ # Previous versions
│ └── snapshot/ # Development builds
├── opensearch/ # OpenSearch images with Fess plugins
│ ├── 3.8/ # Latest OpenSearch
│ └── 3.7/ # 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
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"| Fess Version | OpenSearch | Elasticsearch | Java | Base Image |
|---|---|---|---|---|
| 15.8.0 | 3.8.0 | - | 21 | Alpine/Ubuntu Noble/Amazon Linux 2023 |
| 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 |
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 search01Out of memory errors:
# Increase heap size
export FESS_HEAP_SIZE=2g
docker compose up -dSearch not working:
# Verify OpenSearch connection
curl http://localhost:9200/_cluster/health
# Check Fess connectivity
docker compose exec fess01 curl http://search01:9200Data persistence:
# List volumes
docker volume ls | grep compose
# Remove volumes (WARNING: deletes data)
docker volume rm compose_search01_data compose_search01_dictionaryFor production deployments:
-
Memory allocation:
- Fess: 2-4GB heap (FESS_HEAP_SIZE=2g)
- OpenSearch: 50% of available RAM (OPENSEARCH_JAVA_OPTS=-Xms2g -Xmx2g)
-
Storage optimization:
- Use SSD storage for OpenSearch data volumes
- Separate OS disk from data volumes
-
Network configuration:
- Use dedicated network for container communication
- Configure proper DNS resolution
Install additional Fess plugins:
environment:
- FESS_PLUGINS=fess-webapp-semantic-search:15.8.0 fess-ds-wikipedia:15.8.0Configure 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 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 /Copyright 2016-2026 CodeLibs Project and the Others.