diff --git a/manual/api/authentication.md b/manual/api/authentication.md index 01bf187..9e71808 100644 --- a/manual/api/authentication.md +++ b/manual/api/authentication.md @@ -9,23 +9,14 @@ You can generate a token using the following command, for example with aladdin:o echo -n 'aladdin:opensesame' | base64 YWxhZGRpbjpvcGVuc2VzYW1l ``` -Note: Basic auth is not secure. If you need to access SeaSearch over the public internet, it is strongly recommended to use HTTPS (e.g., via reverse proxy such as Nginx). + +!!! danger + Basic auth is not secure. If you need to access SeaSearch over the public internet, it is strongly recommended to use HTTPS (e.g., via reverse proxy such as Nginx). + ``` "Authorization": "Basic YWRtaW46MTIzNDU2Nzg=" ``` -## Administrator User -SeaSearch uses accounts to manage API permissions. When the program starts for the first time, an administrator account must be configured through environment variables. - -Here is an example of setting the administrator account via shell: -``` -set INIT_SS_ADMIN_USER=admin -set INIT_SS_ADMIN_PASSWORD=Complexpass#123 -``` -!!! tip - In most scenarios, you can use the administrator account to provide access for applications. Only when you need to integrate multiple applications with different permissions, you should create regular users. - - ## Regular Users You can create/update users via the API: ``` diff --git a/manual/config/README.md b/manual/config/README.md index 9c65755..2e5467c 100644 --- a/manual/config/README.md +++ b/manual/config/README.md @@ -1,8 +1,4 @@ # SeaSearch Configuration -For the official ZincSearch configuration, refer to: [ZincSearch Official Documentation](https://zincsearch-docs.zinc.dev/environment-variables/). - -The following configuration options are the ones we’ve extended. All configurations can be set in `.env`. - !!! tip After adding new vairables or modifying the existing variables, you have to restart the service to enable changing: diff --git a/manual/deploy/README.md b/manual/deploy/README.md index 8c9030e..1fd5797 100644 --- a/manual/deploy/README.md +++ b/manual/deploy/README.md @@ -1,19 +1,20 @@ -# Deploy +# Deploy SeaSearch -## Download the seasearch.yml +This guide provides detailed instructions for deploying SeaSearch, creating user accounts, and utilizing the SeaSearch APIs. + +## 1. Download the seasearch.yml ```bash wget https://haiwen.github.io/seasearch-docs/repo/seasearch.yml ``` -## Modify .env file +## 2. Modify .env file First, you need to specify the environment variables used by the SeaSearch image in the relevant `.env` file. Some environment variables can be found in [here](../config/README.md). Please add and modify the environment variables (i.e., `<...>`) ​​of the following fields in the `.env` file. - - - ```shell +COMPOSE_FILE='...,seasearch.yml' # ... means other docker-compose yml + # other environment variables in .env file # For Apple's chip (M2, e.g.), you should use the images with -nomkl tags (i.e., seafileltd/seasearch-nomkl:latest) SEASEARCH_IMAGE=seafileltd/seasearch:latest @@ -23,11 +24,97 @@ INIT_SS_ADMIN_USER= INIT_SS_ADMIN_PASSWORD= ``` -## Restart the Service +## 3. Restart the Service ```shell docker-compose down docker-compose up ``` -Browse seasearch services in [http://127.0.0.1:4080/](http://127.0.0.1:4080/). +!!! success "You can browse SeaSearch services in [http://127.0.0.1:4080/](http://127.0.0.1:4080/)" + +## 4. Access API to Create regular user via admin account + +### Get auth token: + +!!! note + SeaSearch's auth token is using **base64 encode** consist of `username` and `password`, you can check [here](../api/authentication.md) for the whole details + +```sh +echo -n 'aladdin:opensesame' | base64 +YWxhZGRpbjpvcGVuc2VzYW1l +``` + +You can use your auth token to access SeaSearch APIs by adding it into `headers`, i.e., + +```json +headers = { + "Authorization": "Basic YWxhZGRpbjpvcGVuc2VzYW1l" +} +``` + +### Create a regular user + +!!! tip + We here just show an example to describe how to use auth token to access SeaSearch APIs, you can check [here](../api/overview.md) for the whole details of SeaSearch APIs. + +You can create a regular user by **POST `/api/user`**, e.g., + +```sh +curl -X POST http://127.0.0.1:4080/api/user \ +-H "Authorization: Basic YWxhZGRpbjpvcGVuc2VzYW1l" \ +-H "Content-Type: application/json" \ +-d '{ + "_id": "prabhat", + "name": "newusername", + "role": "user", + "password": "Complexpass#123" +}' +``` + +!!! success + After submitting a **POST** to `/api/user`, you will recive a response + + ```json + { + "message": "ok", + "id": "prabhat" + } + ``` + + Then, you can remove the initial admin account informations in `.env` (i.e., `INIT_SS_ADMIN_USER`, `INIT_SS_ADMIN_PASSWORD`) + +## 5. Access SeaSearch APIs via regular user + +### Get auth token + +```sh +echo -n 'newusername:Complexpass#123' | base64 +bmV3dXNlcm5hbWU6Q29tcGxleHBhc3MjMTIz +``` + +### Create an index + +You can create an index by **PUT `/Index_name`** with related settings, for exmaple: + +```sh +curl -X POST http://127.0.0.1:4080/my-index-000001 \ +-H "Authorization: Basic YWxhZGRpbjpvcGVuc2VzYW1l" \ +-H "Content-Type: application/json" \ +-d '{ + "settings": { + "number_of_shards": 3, + "number_of_replicas": 2 + } +}' +``` + +response + +```json +{ + "acknowledged": true, + "shards_acknowledged": true, + "index": "logs" +} +``` diff --git a/manual/repo/seasearch.yml b/manual/repo/seasearch.yml index 0365856..5cbd289 100644 --- a/manual/repo/seasearch.yml +++ b/manual/repo/seasearch.yml @@ -7,24 +7,24 @@ services: ports: - "4080:4080" environment: - - ZINC_FIRST_ADMIN_USER=${INIT_SS_ADMIN_USER} - - ZINC_FIRST_ADMIN_PASSWORD=${INIT_SS_ADMIN_PASSWORD} + - ZINC_FIRST_ADMIN_USER=${INIT_SS_ADMIN_USER:-} + - ZINC_FIRST_ADMIN_PASSWORD=${INIT_SS_ADMIN_PASSWORD:-} - GIN_MODE=${GIN_MODE:-release} - ZINC_WAL_ENABLE=${SS_WAL_ENABLE:-true} - - ZINC_STORAGE_TYPE=${SS_STORAGE_TYPE} - - ZINC_SHARD_NUM=${SS_SHARD_NUM} - - ZINC_MAX_OBJ_CACHE_SIZE=${SS_MAX_OBJ_CACHE_SIZE} - - ZINC_S3_ACCESS_ID=${SS_S3_ACCESS_ID} - - ZINC_S3_USE_V4_SIGNATURE=${SS_S3_USE_V4_SIGNATURE} - - ZINC_S3_ACCESS_SECRET=${SS_S3_ACCESS_SECRET} - - ZINC_S3_ENDPOINT=${SS_S3_ENDPOINT} - - ZINC_S3_USE_HTTPS=${SS_S3_USE_HTTPS} - - ZINC_S3_PATH_STYLE_REQUEST=${SS_S3_PATH_STYLE_REQUEST} - - ZINC_S3_AWS_REGION=${SS_S3_AWS_REGION} - - ZINC_SERVER_MODE=${SS_SERVER_MODE} - - ZINC_CLUSTER_ID=${SS_CLUSTER_ID} - - ZINC_ETCD_USERNAME=${SS_ETCD_USERNAME} - - ZINC_ETCD_PASSWORD=${SS_ETCD_PASSWORD} + - ZINC_STORAGE_TYPE=${SS_STORAGE_TYPE:-} + - ZINC_SHARD_NUM=${SS_SHARD_NUM:-} + - ZINC_MAX_OBJ_CACHE_SIZE=${SS_MAX_OBJ_CACHE_SIZE:-} + - ZINC_S3_ACCESS_ID=${SS_S3_ACCESS_ID:-} + - ZINC_S3_USE_V4_SIGNATURE=${SS_S3_USE_V4_SIGNATURE:-} + - ZINC_S3_ACCESS_SECRET=${SS_S3_ACCESS_SECRET:-} + - ZINC_S3_ENDPOINT=${SS_S3_ENDPOINT:-} + - ZINC_S3_USE_HTTPS=${SS_S3_USE_HTTPS:-} + - ZINC_S3_PATH_STYLE_REQUEST=${SS_S3_PATH_STYLE_REQUEST:-} + - ZINC_S3_AWS_REGION=${SS_S3_AWS_REGION:-} + - ZINC_SERVER_MODE=${SS_SERVER_MODE:-} + - ZINC_CLUSTER_ID=${SS_CLUSTER_ID:-} + - ZINC_ETCD_USERNAME=${SS_ETCD_USERNAME:-} + - ZINC_ETCD_PASSWORD=${SS_ETCD_PASSWORD:-} - ZINC_CLUSTER_PROXY_LOG_DIR=${SS_CLUSTER_PROXY_LOG_DIR:-/opt/seasearch/data/log} - ZINC_CLUSTER_PROXY_HOST=${SS_CLUSTER_PROXY_HOST:-0.0.0.0} - ZINC_CLUSTER_PROXY_PORT=${SS_CLUSTER_PROXY_PORT:-4082} @@ -41,8 +41,8 @@ services: - ZINC_LOG_DIR=${SS_LOG_DIR:-/opt/seasearch/data/log} - ZINC_LOG_LEVEL=${SS_LOG_LEVEL:-debug} - ZINC_PLUGIN_GSE_ENABLE = ${SS_PLUGIN_GSE_ENABLE:-false} - - ZINC_PLUGIN_GSE_DICT_EMBED = ${SS_PLUGIN_GSE_DICT_EMBED} - - ZINC_PLUGIN_GSE_DICT_PATH = ${SS_PLUGIN_GSE_DICT_PATH} + - ZINC_PLUGIN_GSE_DICT_EMBED = ${SS_PLUGIN_GSE_DICT_EMBED:-} + - ZINC_PLUGIN_GSE_DICT_PATH = ${SS_PLUGIN_GSE_DICT_PATH:-} networks: - frontend-net - backend-scheduler-net