Fess Site Search (FSS) is a customizable JavaScript widget generator that enables you to easily embed powerful search functionality on your website, powered by the Fess search engine.
- Visual Customization Wizard: Interactive web interface for customizing colors, fonts, and layout
- Advanced CSS Support: Upload custom CSS files for fine-grained control
- Live Preview: See your search widget in action before deployment
- Multi-language: Support for English and Japanese
- Vue.js Components: Modern, responsive search interface built with Vue 3
- Easy Integration: Just one JavaScript file to embed on your site
Visit FSS Generator to create your customized search widget instantly.
The fastest way to get started:
# Build the Docker image
docker build -t fss .
# Run the container
docker run -d -p 5000:5000 fss
# Access the application
open http://localhost:5000# Install uv (if not already installed)
curl -LsSf https://astral.sh/uv/install.sh | sh
# Clone the repository
git clone https://github.com/codelibs/fess-site-search.git
cd fess-site-search
# Run the installation script
chmod +x install.sh
./install.sh# Set Flask environment variable
export FLASK_APP=app/__init__.py
# Run with uv
uv run flask run
# Or activate the virtual environment first
source .venv/bin/activate # On Windows: .venv\Scripts\activate
flask runThe application will be available at http://localhost:5000.
-
Configure Your Fess Server
- Enter your Fess server URL (e.g.,
https://search.example.com)
- Enter your Fess server URL (e.g.,
-
Customize Appearance
- Choose theme colors (background, text, links, borders)
- Select font family
- Or upload a custom CSS file
-
Generate Widget
- Click "Generate" to create your customized JavaScript file
- Preview the search widget with sample queries
-
Deploy to Your Site
- Download the generated
fess-ss-{hash}.min.jsfile - Add it to your website:
- Download the generated
<!DOCTYPE html>
<html>
<head>
<title>My Website</title>
</head>
<body>
<!-- Your content here -->
<!-- Fess Site Search Widget -->
<div id="fess-search"></div>
<script src="path/to/fess-ss-{hash}.min.js"></script>
</body>
</html>fess-site-search/
├── app/ # Flask backend application
│ ├── views.py # HTTP route handlers
│ ├── backend.py # Form processing and build orchestration
│ ├── build_manager.py # Concurrent build process manager
│ ├── static/ # Static assets (CSS, JS, images)
│ └── templates/ # Jinja2 HTML templates
├── fss/ # Vue.js frontend application
│ ├── src/ # Vue components and source code
│ ├── public/ # Public assets
│ └── package.json # Node.js dependencies
├── tests/ # Test suite
├── pyproject.toml # Python project configuration
├── Dockerfile # Docker container definition
└── install.sh # Installation script
# Install dependencies
uv sync --all-extras
# Run Flask development server
uv run flask run
# Run tests
uv run pytest -v
# Run linter
uv run ruff check app/ tests/
# Format code
uv run ruff format app/ tests/cd fss/
# Install dependencies
npm install
# Development server with hot-reload
npm run serve
# Build for production
npm run build
# Lint code
npm run lint
# Fix linting issues
npm run lint:fix# Run all tests (excluding slow webpack build tests)
uv run pytest -v -m "not slow"
# Run all tests including slow tests (requires Flask server)
uv run pytest -v
# Run only slow tests (webpack build tests)
uv run pytest -v -m "slow"
# Run specific test file
uv run pytest tests/test_status.py -vTest Categories:
- Fast tests (
not slow): Basic Flask routes and functionality (~5 seconds) - Slow tests (
slow): Dynamic webpack builds and uploads (~30-120 seconds)
Note: Slow tests require a running Flask server and may take several minutes in CI environments.
# Build optimized production image
docker build -t fss:latest .
# Run in production mode
docker run -d \
-p 5000:5000 \
-e APP_WEBPACK_LIMIT=4 \
--name fss-prod \
fss:latest# Build frontend
cd fss/
npm run build
# Copy to Flask static directory
mkdir -p ../app/static/fss
cp dist/fess-ss.js ../app/static/fss/
# Run with Gunicorn
cd ..
uv run gunicorn app:app \
-b 0.0.0.0:5000 \
-w 4 \
--threads 12 \
--preload| Variable | Description | Default |
|---|---|---|
FLASK_APP |
Flask application entry point | app/__init__.py |
FLASK_ENV |
Flask environment (development/production) |
production |
APP_WEBPACK_LIMIT |
Maximum concurrent webpack builds | 2 |
The application supports concurrent build processes with semaphore-based throttling. Adjust APP_WEBPACK_LIMIT based on your server resources:
- Small instances (1-2 CPU cores):
APP_WEBPACK_LIMIT=2 - Medium instances (4-8 CPU cores):
APP_WEBPACK_LIMIT=4 - Large instances (8+ CPU cores):
APP_WEBPACK_LIMIT=8
- User Manual: Complete guide for using FSS Generator
- Technical Specifications: Detailed technical documentation
- Fess Documentation: Learn about the Fess search engine
Contributions are welcome! Please follow these steps:
- Fork the repository
- Create a feature branch (
git checkout -b feature/amazing-feature) - Make your changes
- Run tests (
uv run pytest -v) - Run linter (
uv run ruff check . && uv run ruff format .) - Commit your changes (
git commit -m 'Add amazing feature') - Push to the branch (
git push origin feature/amazing-feature) - Open a Pull Request
If you find a bug, please create an issue on GitHub Issues with:
- Clear description of the problem
- Steps to reproduce
- Expected vs actual behavior
- Environment details (OS, Python version, Node.js version)
This project is licensed under the Apache License 2.0 - see the LICENSE file for details.
- Fess: Powerful enterprise search engine
- Vue.js: Progressive JavaScript framework
- Flask: Lightweight web framework
- Website: fss-generator.codelibs.org
- Documentation: User Manual
- Issues: GitHub Issues
- Email: support@n2sm.net
Made with ❤️ by CodeLibs Project