fischermanch/aria repository overview

⁠ARIA on Docker

ARIA is a lean, modular, self-hosted AI assistant with memory, recipes, secure connections, LLM-assisted action planning, and a browser-first UI.

This Docker page is intentionally simple:

• one recommended install path first
• one fully manual Docker Compose path
• clear update rules for both

Repository and full documentation:

• GitHub: https://github.com/FischermanCH/A.R.I.A.
• Wiki: https://github.com/FischermanCH/A.R.I.A./wiki
• Setup docs: https://github.com/FischermanCH/A.R.I.A./tree/main/docs/setup
• Changelog: https://github.com/FischermanCH/A.R.I.A./blob/main/CHANGELOG.md
• Product Homepage: https://fischerman.ch/projects/a-r-i-a-adaptive-reasoning-intelligence-agent/

⁠Current alpha highlights

Current public alpha release on Docker Hub:

• 0.1.0-alpha511

Current public alpha focus:

• Chat Prompt Queue lets users keep writing while ARIA is busy, then edit, remove, or reorder waiting prompts before sequential execution.
• Pending Confirmations stay visible as their own queue/action items with run, plan-again, and discard actions.
• Graphical Memory browser adds Qdrant/Memory drilldown, document and chunk inspection, semantic proximity, fullscreen, and touch/iOS handling.
• Notes workspace adds folder moves from cards/editor, a dense list view, and bulk-move support.
• Auto-memory and agentic learning UI are clearer, with user-facing controls and better separation between memory, learning reflections, and technical maintenance.
• Navigation is generated from a shared registry across the header, account menu, Settings, Admin, Memory, Recipes, and Connections.
• Agentic Operator Trace and runtime result contracts make understanding, context, policy, runtime, result, and summary phases easier to inspect.
• Document inventory and corpus checks are more source-bound and less likely to answer from unrelated snippets.
• Web freshness answers prefer official/vendor/compare/release sources for current product and version questions.
• Multi-target SSH/runtime paths keep full-fleet scope for prompts such as all Linux servers when no true subgroup is named.

⁠What you need

• Docker
• one long random key for Qdrant
• one long random key for SearXNG

Generate suitable values on Unix:

openssl rand -hex 32
openssl rand -hex 32

⁠Recommended path: aria-setup

If you want the easiest install and the easiest future updates, use:

• aria-setup

It:

• asks only for the values it cannot safely guess
• creates one managed ARIA install directory
• writes a ready-to-run docker-compose.yml
• writes a matching .env
• creates visible persistent storage directories
• adds aria-stack.sh for status, logs, health, and updates
• includes aria-updater, so admin users can later start a controlled update from /updates

Managed installs also support the same controlled update flow from chat for admin users:

• zeige update status
• starte update
• bestätige update <token>

Install:

curl -fsSL https://raw.githubusercontent.com/FischermanCH/A.R.I.A./main/aria-setup -o aria-setup
chmod +x aria-setup
sudo ./aria-setup

If you already know the target values and want a fully unattended run:

sudo ./aria-setup \
  --stack-name aria-main \
  --install-dir /opt/aria/aria-main \
  --http-port 8800 \
  --public-url http://localhost:8800 \
  --non-interactive

By default this creates:

• /opt/aria/aria/docker-compose.yml
• /opt/aria/aria/.env
• /opt/aria/aria/aria-stack.sh
• /opt/aria/aria/storage/

Useful commands afterwards:

cd /opt/aria/aria
./aria-stack.sh ps
./aria-stack.sh logs
./aria-stack.sh health
./aria-stack.sh update

Managed update rules:

• normal image refresh:
  • ./aria-stack.sh update recreates only the aria service
• stack layout change, for example a new sidecar service:
  • aria-setup upgrade --install-dir /opt/aria/aria
• deliberate full-stack recovery:
  • ./aria-stack.sh repair or ./aria-stack.sh update-all only when release notes say so
• admin-triggered browser update:
  • /updates

The same managed update helper can also be used from chat by admin users.

Before larger upgrades, create a configuration snapshot in ARIA under:

• /config/backup

⁠Manual Docker Compose

Use this if you want to manage Compose yourself.

Use:

• docker-compose.public.yml

Do not use:

• docker-compose.yml

Reason:

• docker-compose.yml is the local repo/dev stack
• docker-compose.public.yml is the public runtime stack

⁠Manual Compose setup in 4 steps

⁠1. Create a directory

mkdir -p /opt/aria-manual
cd /opt/aria-manual

⁠2. Download the official files

curl -fsSL https://raw.githubusercontent.com/FischermanCH/A.R.I.A./main/docker-compose.public.yml -o docker-compose.yml
curl -fsSL https://raw.githubusercontent.com/FischermanCH/A.R.I.A./main/.env.example -o .env

⁠3. Edit .env

Minimum values:

ARIA_QDRANT_API_KEY=replace-with-a-long-random-key
SEARXNG_SECRET=replace-with-a-long-random-key
ARIA_HTTP_PORT=8800
ARIA_PUBLIC_URL=http://localhost:8800

Optional LLM / embedding environment overrides should usually stay empty when you manage saved provider profiles inside ARIA. Only set them if you deliberately want Docker to force the live runtime values.

⁠4. Start the stack

docker compose up -d

This starts:

• aria
• qdrant
• searxng
• searxng-valkey

Qdrant stays internal by default and is not published on host ports in the public sample.

Copy/paste-ready docker-compose.public.yml:

services:
  qdrant:
    image: qdrant/qdrant:latest
    restart: unless-stopped
    environment:
      QDRANT__SERVICE__API_KEY: ${ARIA_QDRANT_API_KEY}
    volumes:
      - qdrant_storage:/qdrant/storage

  searxng-valkey:
    image: valkey/valkey:8-alpine
    restart: unless-stopped
    volumes:
      - searxng_valkey:/data

  searxng:
    image: searxng/searxng:latest
    restart: unless-stopped
    depends_on:
      - searxng-valkey
    environment:
      FORCE_OWNERSHIP: "false"
      SEARXNG_SECRET: ${SEARXNG_SECRET}
      SEARXNG_LIMITER: "false"
      SEARXNG_VALKEY_URL: "valkey://searxng-valkey:6379/0"
    entrypoint:
      - /bin/sh
      - -lc
      - |
        umask 077
        mkdir -p /etc/searxng
        python - <<'PY'
        import json
        import os
        from pathlib import Path

        secret = os.environ.get("SEARXNG_SECRET", "ultrasecretkey")
        valkey_url = os.environ.get("SEARXNG_VALKEY_URL", "valkey://searxng-valkey:6379/0")
        lines = [
            "use_default_settings: true",
            "",
            "general:",
            '  instance_name: "ARIA Search"',
            "",
            "search:",
            "  safe_search: 1",
            '  autocomplete: ""',
            "  formats:",
            "    - html",
            "    - json",
            "",
            "server:",
            f"  secret_key: {json.dumps(secret)}",
            "  limiter: false",
            "  image_proxy: true",
            "",
            "valkey:",
            f"  url: {json.dumps(valkey_url)}",
            "",
        ]
        Path("/etc/searxng/settings.yml").write_text("\\n".join(lines), encoding="utf-8")
        PY
        exec /usr/local/searxng/entrypoint.sh
    volumes:
      - searxng_cache:/var/cache/searxng

  aria:
    image: fischermanch/aria:alpha
    restart: unless-stopped
    depends_on:
      - qdrant
      - searxng
    ports:
      - "${ARIA_HTTP_PORT:-8800}:8800"
    extra_hosts:
      - "host.docker.internal:host-gateway"
    environment:
      ARIA_ARIA_HOST: "0.0.0.0"
      ARIA_ARIA_PORT: "8800"
      ARIA_PUBLIC_URL: ${ARIA_PUBLIC_URL:-http://localhost:8800}
      ARIA_QDRANT_URL: http://qdrant:6333
      ARIA_QDRANT_API_KEY: ${ARIA_QDRANT_API_KEY}
    volumes:
      - aria_config:/app/config
      - aria_prompts:/app/prompts
      - aria_data:/app/data
      - qdrant_storage:/qdrant/storage:ro

volumes:
  qdrant_storage:
  searxng_cache:
  searxng_valkey:
  aria_config:
  aria_prompts:
  aria_data:

⁠Manual Compose updates

Before larger upgrades, create a configuration snapshot in ARIA under:

• /config/backup

For a normal ARIA release update:

cd /opt/aria-manual
docker compose pull aria
docker compose up -d --no-deps aria

If the release notes say the stack layout changed:

cd /opt/aria-manual
curl -fsSL https://raw.githubusercontent.com/FischermanCH/A.R.I.A./main/docker-compose.public.yml -o docker-compose.yml
docker compose up -d

Important:

• keep the same compose project
• keep the same volumes
• do not rename the stack casually between updates
• use the documented host-side docker compose commands for manual installs; the browser /updates button and chat-driven update flow are part of the managed install path
• if a managed install ever reports a mount mismatch after an update, ./aria-stack.sh repair is the supported recovery path

For multi-stack hosts or older installs pinned to a fixed image tag, the host helper can inspect and update exactly one Compose project:

docker/aria-host-update.sh detect
docker/aria-host-update.sh update --project <name> --dry-run
docker/aria-host-update.sh update --project <name> --target-image fischermanch/aria:<version>

The helper recreates only the aria service and preflights the intended host port before recreate. If another process already owns that port, it aborts safely before touching the running stack.

⁠Backup and recovery

ARIA includes a browser-based configuration backup under:

• /config/backup

That backup contains:

• config.yaml
• connection profiles and routing metadata
• secure-store secrets and user accounts
• prompt files
• custom recipe manifests
• error interpreter rules

It does not contain:

• memories / Qdrant collections
• chat history
• logs, uploads, or Docker stack values
• local SSH key files under data/ssh_keys

Useful chat shortcuts after setup:

• suche im internet nach rabbit r1 neuigkeiten
• zeige stats
• zeige aktivitäten
• exportiere config backup

⁠Which path should you use?

• want the easiest install and easiest updates:
  • aria-setup
• want full Docker Compose control:
  • docker-compose.public.yml

For new public installs, prefer aria-setup unless you explicitly want to manage the compose directory yourself.

⁠Screenshots