Agents > Xedant Analytics Agent > Installation

Installation

Don’t want to read all this?

Just drop a link to https://xedant.com/agents/analytics/install.md or to https://xedant.com/llms.txt into any AI chat (Claude, ChatGPT, etc.) and ask it to generate the config files and commands. It will read the docs, ask you a few questions about your setup, and hand you a ready-to-use configuration. Save time — let the model do the reading for you.

You can also reach me on Telegram — I’m always glad to help. And that’s not just politeness — I genuinely enjoy talking to like-minded people, especially if you love coding as much as I do.

Xedant Analytics Agent is a self-hosted web application for fast data analysis and visualization. It deploys as a single Docker container (Docker is a tool that packages an app with everything it needs, so it runs the same way on any server), and keeps all permanent data in persistent volumes. Python for Jupyter Notebooks and your own scripts is already built into the image. Reports are plain JSON files: version them in Git and move them by simply copying.

Minimum requirements

Any Linux host with Docker is enough. Everything else is already in the image:

  • ASP.NET Core 9 runtime — the application’s web server;
  • Python 3 + venv + pip — for Jupyter Notebooks and external scripts;
  • sqlite3 and other file utilities for working with data.

No database server required: report documents live as files in a persistent volume, and data sources (SQLite, PostgreSQL, ClickHouse, or your own Python script) connect as needed through the interface.

When idle, Analytics Agent does not load the server: background checks run only on changes, not on a timer. While nobody is working with the app, the memory taken by search and intermediate results is released — and the search index itself lives on disk and is picked up on the next request. That is why Analytics Agent runs comfortably on a modest server next to other applications.

Docker Compose

Create a compose.yml file and run docker compose up -d:

services:
  analytics-agent:
    image: xedant/analytics-agent:latest
    container_name: analytics-agent
    ports:
      - "5010:80"
    volumes:
      # reports, sources and settings — a persistent volume
      - analytics-agent-data:/project/apps/analytics
      # the app's service databases — a separate persistent volume
      - analytics-agent-alerts:/apps/analytics
      # shared Lakehouse with Data Agent (uncomment if you run one)
      # - /data:/data
    environment:
      - ASPNETCORE_ENVIRONMENT=Production
      - ASPNETCORE_URLS=http://+:80
      - ANALYTICS_APP_CONFIG_PATH=/project/apps/analytics
      - ANALYTICS_APP_DATA_PATH=/apps/analytics
      - ANALYTICS_APP_SECRET_KEY=change-me-in-production
      - ANALYTICS_APP_ADMIN_LOGIN=admin
      - ANALYTICS_APP_ADMIN_PASSWORD={sha256-hash-of-your-password}
    restart: unless-stopped
    sysctls:
      fs.inotify.max_user_watches: "524288"
      fs.inotify.max_user_instances: "512"

volumes:
  analytics-agent-data:
  analytics-agent-alerts:

After launch, the interface is available on port 5010: http://localhost:5010.

The sysctls raise the inotify limits — the file watcher needs them to track changes in report files, so edits are picked up instantly, without a reload. Without these limits, the watcher may miss some changes when there are many documents.

Environment variables

  • ANALYTICS_APP_ADMIN_LOGIN — the administrator login (default admin from appsettings).
  • ANALYTICS_APP_ADMIN_PASSWORD — the SHA-256 hash of the password, not the password itself. Compute it with echo -n "your-password" | sha256sum. On sign-in the app hashes the entered password and compares it with this value.
  • ANALYTICS_APP_SECRET_KEY — the key that signs JWT tokens (default default-secret-key-change-in-production — be sure to replace it in production).
  • ANALYTICS_APP_CONFIG_PATH — the folder for report documents, data sources and settings (inside the container, /project/apps/analytics). This is the most valuable part: copy it for a backup.
  • ANALYTICS_APP_DATA_PATH — the folder for the app’s service databases and binaries: the alerts database, the Python environment (inside the container, /apps/analytics).
  • ANALYTICS_APP_BRAND — brand and interface language: xedant (English, the default) or pastukhov (Russian).
  • ANALYTICS_APP_LAKEHOUSE_PATH — the Lakehouse root folder (default /data).
  • ANALYTICS_APP_TEMPLATES_PATH and ANALYTICS_APP_TEMPLATES_RU_PATH — the English and Russian versions of the analysis template library (defaults: templates and templates_ru next to the project; change them only if you move the library).
  • ANALYTICS_APP_TEMPLATE_DATA_PATH and ANALYTICS_APP_TEMPLATE_DATA_RU_PATH — demo data for the templates: the databases on which any template can be opened and studied right after installation. Already unpacked in the image; no need to change.
  • ANALYTICS_APP_BASE_PATH — when the app lives not at the domain root but in a subfolder (for example, /analytics): a path with a leading slash and no trailing one. The same result can be achieved with a reverse proxy that passes the folder in the X-Forwarded-Prefix header.
  • AGENT_API_URL and AGENT_API_KEY — the URL and API key of Xedant Agent for the AI features. Without them the AI buttons are hidden; everything else works.

Without ANALYTICS_APP_ADMIN_LOGIN and ANALYTICS_APP_ADMIN_PASSWORD set, signing in to the app is impossible. The JWT token lives 90 days (129,600 minutes); the session, 1 hour.

Data storage

Permanent data is split into two folders, each with its own volume; both survive container recreation. The volumes are mandatory — without them you will lose your reports and settings on the very first docker compose down.

  • /project/apps/analytics/documents/ — report documents as JSON files;
  • /project/apps/analytics/ — data sources and app settings: the part worth saving and convenient to version in Git;
  • /project/apps/analytics/requirements.txt — Python dependencies for Jupyter Notebooks: seeded on first launch, and you can add your own libraries to it;
  • /project/apps/analytics/scripts/ — your own Python scripts and their library list in requirements.txt: also in a persistent volume, also convenient to version (details in Python Scripts);
  • /apps/analytics/scripts/ — the Python environment for scripts and their working folders: built automatically, no need to back it up separately;
  • /apps/analytics/alerts.db — the alerts database: rules, contact points, silences, firing history. It is a single file — and a complete backup of your alerting settings;
  • /apps/analytics/search-index/ — the search index over documents and templates: it lives on disk, so search answers immediately after a restart and does not hold memory permanently. Deleting it is harmless — it is rebuilt on the next search;
  • ANALYTICS_APP_LAKEHOUSE_PATH (default /data) — Lakehouse data files: Parquet, SQLite, Markdown. In a shared installation with Data Agent it is one folder for both.

First sign-in

Use the login and password set by the ANALYTICS_APP_ADMIN_LOGIN and ANALYTICS_APP_ADMIN_PASSWORD variables (the variable holds the hash; at sign-in you enter the password itself). After signing in you can immediately change the interface language and theme. The home screen shows the “New document” button and the report catalog.

Setup after launch

Data sources — SQLite, PostgreSQL, ClickHouse, or your own Python script — are connected in the “Data Sources” section of the web interface: creating, connection checks, schema auto-detection. Details in the Data Sources section.

Template demo data is connected right away: the sources list shows the ml-demo_… databases on which any template from the library can be opened and walked through before you have connected your own data.

AI features are enabled with the AGENT_API_URL and AGENT_API_KEY variables: the buttons for adding blocks in plain language and “Fix with AI” appear, plus the “Use this template” button in the analysis template library. The list of models and their colors come from your Xedant Agent — the same models as in all the other apps. Details in the agent in the report section.

Docker CLI with a .env file

You can also run Analytics Agent without compose — with a docker run command, keeping the environment variables in a .env file:

# .env
ASPNETCORE_ENVIRONMENT=Production
ASPNETCORE_URLS=http://+:80
ANALYTICS_APP_CONFIG_PATH=/project/apps/analytics
ANALYTICS_APP_DATA_PATH=/apps/analytics
ANALYTICS_APP_SECRET_KEY=a-long-random-string
ANALYTICS_APP_ADMIN_LOGIN=admin
ANALYTICS_APP_ADMIN_PASSWORD=sha256-hash-of-the-password
# optional: AI features via Xedant Agent
# AGENT_API_URL=
# AGENT_API_KEY=
docker run -d \
  --name analytics-agent \
  --env-file .env \
  -p 5010:80 \
  -v analytics-agent-data:/project/apps/analytics \
  -v analytics-agent-alerts:/apps/analytics \
  --sysctl fs.inotify.max_user_watches=524288 \
  --sysctl fs.inotify.max_user_instances=512 \
  --restart unless-stopped \
  xedant/analytics-agent:latest

The --env-file flag reads all the variables from the file. Individual values can be overridden with extra -e flags after it, for example -e ANALYTICS_APP_BRAND=xedant.

← Back to the Analytics Agent home page