Frequently Asked Questions (FAQ)

This document provides answers to common questions about managing and using the Qdrant deployment.

Authentication and Security

How do I change the admin password?

To change the admin password, follow these steps:

1. Generate a new bcrypt hash for your desired password using Caddy’s built-in tool:

   docker run --rm caddy:2-alpine caddy hash-password --plaintext YOUR_NEW_PASSWORD

   Replace YOUR_NEW_PASSWORD with your desired password.

   Important: Make sure to use the caddy:2-alpine image to ensure compatibility with your deployment.

2. Method 1 (Using environment variables - recommended for most cases):

   Update the .env file with your new password and the generated hash:

   ADMIN_PASSWORD=YOUR_NEW_PASSWORD
   ADMIN_PASSWORD_HASH=YOUR_GENERATED_HASH

   For example:

   ADMIN_PASSWORD=new_secure_password
   ADMIN_PASSWORD_HASH=$2a$14$tC.4t2YAnLvBsAXrgf8bQOveZOqhCxo44B4tAcQVx2FQodpDxikfS

   Note: Caddy requires bcrypt hashes in the $2a$ format. If your hash starts with $2y$ (PHP format), it will not work correctly.

3. Method 2 (Direct Caddyfile modification - use if environment variables don’t work):

   If you experience issues with environment variables not being properly interpolated, you can directly modify the Caddyfile:

   a. Open the config/Caddyfile.prod file

   b. Locate the basic_auth section and replace it with your hardcoded credentials:

   # Basic Auth for all routes
   basic_auth {
       # Username and hashed password
       admin YOUR_GENERATED_HASH
   }

   For example:

   # Basic Auth for all routes
   basic_auth {
       # Username and hashed password for "new_secure_password"
       admin $2a$14$tC.4t2YAnLvBsAXrgf8bQOveZOqhCxo44B4tAcQVx2FQodpDxikfS
   }

4. Restart the service using the restart script:

   ./restart.sh

5. Verify that you can authenticate with the new password.

Important: Always keep your .env file secure as it contains sensitive information.

What should I do if I get a 401 Unauthorized error?

If you’re getting a 401 Unauthorized error after changing your password, it’s likely that the password hash in the .env file doesn’t match your password. Follow the steps above to generate a new hash and update both the password and hash in the .env file.

For more detailed troubleshooting of authentication issues, refer to the Troubleshooting Guide.

API Usage

How do I authenticate API requests?

When making API requests to Qdrant through the Caddy proxy, you need to include both:

1. Basic Authentication with your admin username and password
2. The Qdrant API key in the request headers

Example using curl:

curl -X GET "https://your-domain.com/collections" \
  -u "admin:your_password" \
  -H "Content-Type: application/json" \
  -H "api-key: your_api_key"

Maintenance

How do I backup my Qdrant data?

Qdrant data is stored in a Docker volume. To backup this data:

1. Stop the service:

   docker compose -f docker-compose.prod.yml down

2. Create a backup of the Qdrant volume:

   docker run --rm -v qdrant_storage:/data -v $(pwd)/backups:/backups alpine tar -czf /backups/qdrant-backup-$(date +%Y%m%d).tar.gz /data

3. Restart the service:

   docker compose -f docker-compose.prod.yml up -d

How do I restore from a backup?

To restore from a backup:

1. Stop the service:

   docker compose -f docker-compose.prod.yml down

2. Restore the backup to the Qdrant volume:

   docker run --rm -v qdrant_storage:/data -v $(pwd)/backups:/backups alpine sh -c "rm -rf /data/* && tar -xzf /backups/your-backup-file.tar.gz -C /"

3. Restart the service:

   docker compose -f docker-compose.prod.yml up -d