Scripts Directory

September 9, 2025 · View on GitHub

This directory contains utility scripts for setting up, configuring, and managing various aspects of the application environment. Below is an overview of each script along with usage instructions.

Available Scripts

1. init_env.py

  • Description:
    Updates and prepares the environment keys file located at /app/env/.env.keys. This script ensures that API keys hints and configuration hints (for providers such as OpenAI, Anthropic, Cohere, Hugging Face, etc.) are included.
  • Key Functions:
    • load_env_file(path: str) -> List[str]: Reads an environment file and returns its lines.
    • write_env_file(path: str, lines: List[str]) -> None: Writes a list of strings back to the environment file.
    • main() -> None: Checks for various API keys in the file and appends missing hints.
  • Usage:
    The script is automatically mounted to the container and runs when you start the application.

2. install_docker_ubuntu.sh

  • Description:
    A shell script to install Docker on Ubuntu systems. It:
    • Updates the package list and installs required dependencies.
    • Purges any previous Docker installations.
    • Configures Docker's repository and imports the GPG key.
    • Installs Docker Compose (standalone version v2.32.4).
  • Usage: 
    ./scripts/install_docker_ubuntu.sh

3. meilisearch_dump.py

  • Description:
    A comprehensive tool for creating MeiliSearch dumps AND exporting data between instances. This script now supports both traditional dump creation and the new Meilisearch 1.16+ export functionality for direct instance-to-instance migration.

  • Key Features:

    • 🆕 EXPORT MODE (Meilisearch 1.16+): Direct instance-to-instance migration without dump files
    • DUMP MODE (Traditional): Creates timestamped backup files with monitoring
    • 🔒 AUTO-BACKUP (NEW): Automatic backup creation before/after export operations for data safety
    • 📁 IMPORT MANAGEMENT (NEW): Automatic copy to just_chat_rag.dump with backup of existing
    • Conflict resolution: additive operations with document replacement
    • Selective export with index patterns and filters
    • Settings override capabilities for target instances
    • Configurable payload sizes for performance optimization
    • Detailed timing information and progress feedback

  • Usage:

    🚀 Export Mode (NEW - Recommended for 1.16+)

    # Basic export with automatic backup (recommended)
uv run scripts/meilisearch_dump.py --export \
  --target-url "http://production.example.com:7700" \
  --target-api-key "target_master_key"

# Export with import dump update (ready for immediate use)
uv run scripts/meilisearch_dump.py --export \
  --target-url "http://staging.example.com:7700" \
  --target-api-key "staging_key" \
  --update-import

# Export without backup (faster, but less safe)
uv run scripts/meilisearch_dump.py --export \
  --target-url "http://dev.example.com:7700" \
  --target-api-key "dev_key" \
  --no-backup

# Advanced export with selective patterns and settings
uv run scripts/meilisearch_dump.py --export \
  --target-url "http://staging.example.com:7700" \
  --target-api-key "staging_key" \
  --index-patterns "products,users*" \
  --override-settings \
  --payload-size "100MiB" \
  --filter "status = 'active'" \
  --update-import

    📁 Dump Mode (Traditional)

    # Basic dump creation (uses environment defaults)
uv run scripts/meilisearch_dump.py

# Dump with immediate import readiness (recommended)
uv run scripts/meilisearch_dump.py --update-import

# With custom connection settings and import update
uv run scripts/meilisearch_dump.py --host localhost --port 7700 --api-key your_key --update-import

# Custom dumps folder path
uv run scripts/meilisearch_dump.py --dumps-path /custom/dumps/path

  • Important Notes:

    🆕 Export Mode (Meilisearch 1.16+):

    • ✅ No file management required - direct instance-to-instance transfer
    • ✅ Additive operation - existing data is preserved, duplicates are replaced
    • ✅ Real-time migration - no intermediate files or manual import steps
    • 🔒 Auto-backup by default - creates PRE-EXPORT and POST-EXPORT dumps for safety
    • 📁 Import ready with --update-import - automatically updates just_chat_rag.dump
    • ⚠️ Requires target instance API access - ensure target is accessible and has proper API key
    • ⚠️ Network connectivity required during the entire export process
    • 🐳 Docker networking: Use 172.17.0.1 (host gateway) instead of localhost for container-to-host communication
    • 🔒 Version requirement: Both source and target instances MUST be Meilisearch 1.16.0 or higher

    📁 Dump Mode (Traditional):

    • Critical: Creates dumps with datetime format, but MeiliSearch import expects just_chat_rag.dump
    • 📁 Use --update-import to automatically copy latest dump to just_chat_rag.dump (recommended)
    • Manual option: cp ./dumps/YYYYMMDD-HHMMSS.dump ./dumps/just_chat_rag.dump
    • 🛡️ Automatic backup - existing just_chat_rag.dump backed up to .bak before update
    • Environment variables: MEILISEARCH_HOST, MEILISEARCH_PORT, MEILI_MASTER_KEY
    • Dump files are saved to ./dumps/ directory by default

  • Migration Workflows:

    🚀 Modern Workflow (Export Mode - Recommended)

    1. Run export command with target instance details (auto-backup enabled)
    2. Data is directly migrated with conflict resolution
    3. Optional: Use --update-import for immediate local import readiness
    4. Automatic PRE/POST-EXPORT backups created for safety

    📁 Traditional Workflow (Dump Mode)

    1. Run the script with --update-import flag (recommended)
    2. Dump created and automatically copied to just_chat_rag.dump
    3. Transfer just_chat_rag.dump to target environment if needed
    4. Remove MeiliSearch volume and restart: docker compose down && docker volume rm just-chat_meili-data && docker compose up

    📁 Legacy Manual Workflow (if needed)

    1. Run the script to create a timestamped dump
    2. Manually rename: cp ./dumps/YYYYMMDD-HHMMSS.dump ./dumps/just_chat_rag.dump
    3. Transfer to target environment if needed
    4. Remove MeiliSearch volume and restart: docker compose down && docker volume rm just-chat_meili-data && docker compose up

  • Updating to Meilisearch 1.16+ for Export Features:

    # Update your docker-compose.yml to use Meilisearch 1.16+
# services:
#   meilisearch:
#     image: getmeili/meilisearch:v1.20.0

# Pull and restart with updated image
docker compose pull
docker compose up -d

# Verify version
curl "http://localhost:7700/version"

4. replacement_entrypoint.sh

  • Description:
    A customizable Docker entrypoint script that can replace the default entrypoint in the container. This script serves as a template that you can modify to add custom initialization logic. The script is particularly useful when you need to:

    • Add custom setup steps before the main application starts
    • Modify container environment or permissions
    • Install additional dependencies
    • Run initialization scripts

  • Usage:

    1. Modify the script according to your needs
    2. Mount it to the container by updating your docker-compose.yml:
    volumes:
  - ./scripts/replacement_entrypoint.sh:/usr/local/bin/entrypoint.sh
entrypoint: [ "/usr/local/bin/entrypoint.sh" ]

  • Customization:
    The script can be modified to include various initialization tasks such as:

    • Environment setup
    • Permission adjustments
    • Dependency installation
    • Pre-startup checks
    • Custom initialization scripts

General Notes

  • Administrative Privileges:
    Some scripts (e.g., Docker installation or modifying system users/groups) require root or sudo privileges.

  • Customization:
    These scripts are provided as a baseline and can be tailored to fit specific project requirements.

For further details, please refer to the inline comments provided within each script.