Installation and operation

This document contains the information needed to install and operate Parsewise in the customer's infrastructure: the delivery set, environment requirements, configuration, the installation procedure and operation.

1. Delivery set

The delivery manifests are the manifests of the rightsholder's cloud installation, and its addresses and services are written in them. Before applying them the customer adapts them to their own installation:

• image addresses — to the versions from the delivery registry;
• values written directly in the server and queue worker manifests: FRONTEND_URL, SHOPS_DOMAIN, R2_ENDPOINT, R2_PUBLIC_URL, SMTP_HOST, SMTP_PORT, SMTP_USE_TLS, SMTP_START_TLS — to their own (a value in the manifest takes precedence over a value in a secret); LLM_MODEL_QUERY — to the name of their model, or remove it;
• references to the secret keys yandex-gpt-api-key, yandex-gpt-folder-id, yandex-maps-api-key and to the metrika-credentials secret — remove them: only the cloud installation needs them, and without them pods do not start in the cluster;
• in the dashboard manifest — remove NEXT_PUBLIC_API_URL and NEXT_PUBLIC_YM_COUNTER_ID and set the PARSEWISE_* parameters from section 3;
• the secrets template — fill in with their own values and apply; it holds every secret the delivery manifests read, including app-config-full with the parameters SECRET_KEY, DOCS_USERNAME, DOCS_PASSWORD, EMAIL_FROM, INGRESS_LB_IP, LLM_BASE_URL;
• parameters of services the customer does not use — remove them: payments through Robokassa, Yandex Metrica;
• the sample bucket access policy — put in the name of their bucket and the server's account; it is written for Yandex Object Storage, in other storage the same access rules (section 2) are set with its own tools;
• for project addresses of the form project.domain — issue a certificate for *.domain through cert-manager with a DNS01 check at their DNS provider and reference it in 06a-ingress-shops.yaml.

Manifests of the marketing website, documentation and monitoring are not part of the delivery.

Images are handed over as an OCI archive for loading into the customer's registry or through the rightsholder's image registry.

Images are built from the rightsholder's mirrors: base images, Python packages and npm packages are not downloaded from public repositories during the build. For audio and video processing the server image includes ffmpeg from the Debian distribution. The embedding model is not downloaded during installation or start-up. Processes in the server and dashboard containers run as an unprivileged user.

2. Environment requirements

Each server and queue worker pod opens up to 40 connections to PostgreSQL. With many replicas a connection pooler is recommended, for example PgBouncer or Odyssey.

Compute resources

Total resource requests without Kubernetes system components: about 5.8 vCPU and 14.9 GiB of memory at the minimum number of replicas, about 21.1 vCPU and 47.6 GiB at the maximum. A node must fit an embedding pod with a memory request of 2.5 GiB.

The configuration on which the rightsholder runs the software: 4–10 nodes of 4 vCPU and 8 GiB each with automatic node addition; the main and vector databases are separate PostgreSQL 15 clusters of 2 vCPU and 8 GiB with a 20 GiB disk growing automatically up to 64 GiB; Valkey 7.2 — 2 vCPU and 4 GiB.

3. Configuration

The parameters of the server, queue worker and scheduler are set with environment variables — from Kubernetes secrets or as values in the manifests (section 1). All three deployments receive the same parameters for connecting to the databases, Redis and object storage.

Required

The parameters FRONTEND_URL, EMAIL_FROM, SHOPS_DOMAIN and INGRESS_LB_IP have default values pointing to the rightsholder's cloud installation, so in the customer's installation they must be set.

Language model

The software does not use services of the company OpenAI: "OpenAI-compatible" is only the API format supported by vLLM and other model servers. The names openai and OPENAI_API_KEY follow that format.

Embedding

Optional

Dashboard and widget

The dashboard reads the installation parameters from the container's environment variables at start-up. A variable that is not set keeps the value the image was built with; a variable with an empty value switches the corresponding function off. The image is built with the values of the rightsholder's cloud installation — the Yandex Metrica counter, the Yandex ID and VK ID applications, the widget address on releases.parsewise.ru — so in the customer's installation PARSEWISE_YM_COUNTER_ID, PARSEWISE_YANDEX_CLIENT_ID and PARSEWISE_VK_CLIENT_ID are set explicitly, with their own values or empty, and PARSEWISE_WIDGET_SCRIPT_URL with the widget's address in the customer's infrastructure.

The widget receives the API server address with the apiUrl parameter in window.ParsewiseConfig on the page, together with the project identifier shopId; the link to the personal data processing policy — with the privacyPolicyUrl parameter or from the project settings.

The same build of the dashboard and the widget works in any installation: there is no need to rebuild them for the customer's address and parameters.

4. Installation

1. Prepare PostgreSQL: the main and the vector databases. The vector type must be available in the vector database. If it is not, the software runs CREATE EXTENSION IF NOT EXISTS vector; if the application role has no such right, the database administrator runs CREATE EXTENSION vector in advance.
2. Prepare Redis and an S3-compatible object storage bucket; configure the CORS rules and access to the bucket's objects according to section 2.
3. Load the images into a registry reachable by the cluster and put their addresses in the manifests.
4. Create the namespace and the secrets with the parameters from section 3.
5. Put the domain names of the API and the dashboard into the routing manifest and configure TLS.
6. Apply the manifests. At start-up the server creates the missing tables of the main database and applies the migrations included in the image; the vector store creates its own tables and indexes.
7. Place the widget files on a static server or in the customer's object storage.
8. Check the installation:
   • all pods are ready; embedding pods take up to three minutes to load the model;
   • a GET /v1/public/health request to the API server returns {"status": "ok"};
   • the server log contains the line Alembic migrations applied (head reached) and has no Alembic upgrade failed messages and no pgvector errors.

5. Getting started

1. Sign in to the dashboard and create a project.
2. Set up the assistant's persona: name, avatar and answer rules.
3. Fill the knowledge base: upload files, import products or profiles from a file, or connect a source by link.
4. Invite team members and assign roles.
5. Connect the widget to the pages of the website or personal account:

<script>
  window.ParsewiseConfig = {
    shopId: "PROJECT_ID",
    apiUrl: "https://API_SERVER_ADDRESS",
  };
</script>
<script async src="https://STATIC_ADDRESS/widget.iife.js"></script>

The detailed procedure for working in the dashboard is in the User and administrator guide.

6. Operation