UnifySearch Server User Guide#
- Run UnifySearch Server with Docker
- Manual install UnifySearch Server
1. Quick Start (Recommended for Most Users)#
This method is the simplest way to get UnifySearch Server running. It uses Docker-managed volumes, which handles data persistence automatically without requiring manual directory setup on your host machine.
Command:
docker run -d \
--name unifysearch-server \
-p 9000:9000 \
-v unifysearch_data_vol:/app/easysearch/data \
-v unifysearch_config_vol:/app/easysearch/config \
-v unifysearch_logs_vol:/app/easysearch/logs \
unifysearch/unifysearch-server:0.9.0🔒 SECURITY WARNING
By default, this command initializes the UnifySearch Server with a randomly generated initial admin password for security. You will need to retrieve this password from the server logs after the first startup. If you prefer to set a specific password beforehand, you must use the EASYSEARCH_INITIAL_ADMIN_PASSWORD environment variable.
After running the command:
- UnifySearch Server will be running in the background. Access the Web UI at
http://localhost:9000. - Your data, configuration, and logs are safely stored in Docker volumes named
unifysearch_data_vol,unifysearch_config_vol, andunifysearch_logs_vol.
Docker CAP Issue Some Docker environments may restrict certain capabilities required by UnifySearch Server. If you encounter permission issues, consider the following options:
SYS_PTRACEcapability is required for UnifySearch Server to run properly. If you encounter permission issues, you may need to add--cap-add=SYS_PTRACEto thedocker runcommand.SYS_NICEcapability may also be required in some environments.--security-opt seccomp=unconfinedcan be used as a last resort but is not recommended for production due to security implications.
Here is an example command with added capabilities:
docker run -d \
--name unifysearch-server \
--cap-add=SYS_PTRACE \
--cap-add=SYS_NICE \
--security-opt seccomp=unconfined \
-p 9000:9000 \
-v unifysearch_data_vol:/app/easysearch/data \
-v unifysearch_config_vol:/app/easysearch/config \
-v unifysearch_logs_vol:/app/easysearch/logs \
unifysearch/unifysearch-server:0.9.02. Advanced Start (Using Host Directories)#
This method provides direct access to the data, configuration, and log files on your host machine. It’s suitable for users who want to easily edit configuration files or manage data directly.
Step 1: Prepare Host Directories and Environment File
First, create the necessary directories and a .env file for your password.
# Create the parent directory for all UnifySearch Server files.
# We recommend using a standard location like /data/unifysearch-server.
sudo mkdir -p /data/unifysearch-server/{data,logs,config}
# Create an environment file to store your password securely.
# Replace EASYSEARCH_INITIAL_ADMIN_PASSWORD value with a strong, secret password.
echo "EASYSEARCH_INITIAL_ADMIN_PASSWORD=$(tr -dc 'A-Za-z0-9_.@+=-' < /dev/urandom | head -c 20)" | sudo tee /data/unifysearch-server/.env > /dev/nullStep 2: Initialize Configuration from the Image (One-time Setup)
This clever command runs a temporary container to copy the default configuration files from the image into your newly created local config directory.
docker run --rm \
-v /data/unifysearch-server/config:/tmp/config \
--env-file /data/unifysearch-server/.env \
unifysearch/unifysearch-server:0.9.0 \
cp -a /app/easysearch/config/. /tmp/config/--rm: Automatically removes the container after it exits.-v /data/unifysearch-server/config:/tmp/config: Mounts your local config directory into a temporary path inside the container.--env-file /data/unifysearch-server/.env: Loads your password environment variable into the container.cp -a ...: The command executed inside the container. It copies all contents from the image’s config directory to the mounted host directory.
Step 3: Set Directory Permissions
The container runs with a specific user (UID 602). You must grant this user write permissions to the host directories.
Note: This step might be unnecessary on some Docker environments like Docker Desktop for Mac. Test without it first if you are unsure.
sudo chown -R 602:602 /data/unifysearch-serverStep 4: Run the UnifySearch Server Container
Now, start the main container, mounting your prepared host directories and using the .env file for the password.
docker run -d \
--name unifysearch-server \
--hostname unifysearch-server \
--restart unless-stopped \
--env-file /data/unifysearch-server/.env \
-m 4g --cpus="2" \
-p 9000:9000 \
-v /data/unifysearch-server/data:/app/easysearch/data \
-v /data/unifysearch-server/config:/app/easysearch/config \
-v /data/unifysearch-server/logs:/app/easysearch/logs \
-e ES_JAVA_OPTS="-Xms2g -Xmx2g" \
unifysearch/unifysearch-server:0.9.0--env-file: Securely loads environment variables (like your password) from the.envfile.
3. Upgrading UnifySearch Server#
Follow these steps to upgrade to a new version while preserving all your data. The procedure is the same whether you used the Quick Start or Advanced Start method.
Step 1: Pull the New Image
# Replace '0.9.0' with the new version tag.
docker pull unifysearch/unifysearch-server:0.9.0Step 2: Stop and Remove the Old Container
docker stop unifysearch-server && docker rm unifysearch-serverStep 3: Start a New Container with the Same Volumes/Mounts
Re-run your original docker run command, but update the image tag to the new version. It is crucial to use the exact same -v volume or bind mount paths as before.
- If you used Quick Start, re-run the Quick Start command with the new image tag.
- If you used Advanced Start, re-run the Advanced Start command with the new image tag.
4. Full Cleanup and Removal#
These commands will completely remove the UnifySearch Server container and its data.
🛑 DANGER ZONE 🛑
The following commands will permanently delete all your UnifySearch Server data. This action cannot be undone. Proceed with caution.
Step 1: Stop and Remove the Container
docker stop unifysearch-server && docker rm unifysearch-serverStep 2: Remove Data, Config, and Logs
- If you used Quick Start (Docker Volumes):
docker volume rm data config logs - If you used Advanced Start (Host Directories):
sudo rm -rf /data/unifysearch-server
Step 3: Remove the Docker Image
docker rmi unifysearch/unifysearch-server:0.9.0Manual Installation#
Follow these steps for a manual setup:
Easysearch#
Install Easysearch
docker run -itd \
--name easysearch -p 9200:9200 \
-v data:/app/easysearch/data \
-v config:/app/easysearch/config \
-v logs:/app/easysearch/logs \
infinilabs/easysearch:1.14.1Get the bootstrap password of the Easysearch:
docker logs easysearch | grep "admin:"UnifySearch#
Modify unify.yml with correct env settings, or start the unifysearch server with the correct environments like this:
$ OLLAMA_MODEL=deepseek-r1:1.5b ES_PASSWORD=45ff432a5428ade77c7b ./bin/unifysearch-server
___ ___ ___ ___ _ _____
/ __\/___\/ __\/___\ /_\ \_ \
/ / // // / // // //_\\ / /\/
/ /__/ \_// /__/ \_// / _ \/\/ /_
\____|___/\____|___/ \_/ \_/\____/
[UNIFYSEARCH] UnifySearch - search, connect, collaborate – all in one place.
[UNIFYSEARCH] 1.0.0_SNAPSHOT#001, 2024-10-23 08:37:05, 2025-12-31 10:10:10, 9b54198e04e905406db90d145f4c01fca0139861
[10-23 17:17:36] [INF] [env.go:179] configuration auto reload enabled
[10-23 17:17:36] [INF] [env.go:185] watching config: /path/to/unifysearch/config
[10-23 17:17:36] [INF] [app.go:285] initializing unifysearch, pid: 13764
[10-23 17:17:36] [INF] [app.go:286] using config: /path/to/unifysearch/unify.yml
[10-23 17:17:36] [INF] [api.go:196] local ips: 192.168.3.10
[10-23 17:17:36] [INF] [api.go:360] api listen at: http://0.0.0.0:2900
[10-23 17:17:36] [INF] [module.go:136] started module: api
[10-23 17:17:36] [INF] [module.go:155] started plugin: statsd
[10-23 17:17:36] [INF] [module.go:161] all modules are started
[10-23 17:17:36] [INF] [instance.go:78] workspace: /path/to/unifysearch/data/unifysearch/nodes/csai3njq50k2c4tcb4vg
[10-23 17:17:36] [INF] [app.go:511] unifysearch is up and running now.Once the UnifySearch Server is running, you are ready to setup it up through UI based management console.