This guide deploys Khoj with Docker Compose on Debian 10 to latest stable, Ubuntu LTS, and RHEL 9+ compatible hosts. The playbook downloads the official docker-compose.yml from the Khoj repository and configures environment variables.
- name: Deploy Khoj
hosts: khoj
become: true
vars:
app_root: /opt/khoj
app_port: 42110
# Required: Set these before running
khoj_admin_password: "your-secure-admin-password"
khoj_django_secret_key: "your-secret-key-min-50-characters-random"
# Optional: Database credentials (change from defaults!)
postgres_password: "your-secure-db-password"
# Optional: API keys
openai_api_key: ""
anthropic_api_key: ""
gemini_api_key: ""
# Optional: Network settings
khoj_domain: "" # e.g., "khoj.example.com"
khoj_no_https: "False" # Set to "True" if not using HTTPS
tasks:
- name: Install Docker on Debian/Ubuntu
apt:
name:
- docker.io
- docker-compose-plugin
- wget
state: present
update_cache: true
when: ansible_os_family == "Debian"
- name: Install Docker on RHEL family
dnf:
name:
- docker
- docker-compose-plugin
- wget
state: present
when: ansible_os_family == "RedHat"
- name: Enable and start Docker
service:
name: docker
state: started
enabled: true
- name: Create app directory
file:
path: "{{ app_root }}"
state: directory
mode: "0755"
- name: Download official Khoj docker-compose.yml
get_url:
url: https://raw.githubusercontent.com/khoj-ai/khoj/master/docker-compose.yml
dest: "{{ app_root }}/docker-compose.yml"
mode: "0644"
- name: Configure environment variables in docker-compose.yml
lineinfile:
path: "{{ app_root }}/docker-compose.yml"
regexp: "{{ item.regexp }}"
line: "{{ item.line }}"
loop:
- { regexp: '^ - KHOJ_ADMIN_PASSWORD=', line: ' - KHOJ_ADMIN_PASSWORD={{ khoj_admin_password }}' }
- { regexp: '^ - KHOJ_DJANGO_SECRET_KEY=', line: ' - KHOJ_DJANGO_SECRET_KEY={{ khoj_django_secret_key }}' }
- { regexp: '^ - POSTGRES_PASSWORD=', line: ' - POSTGRES_PASSWORD={{ postgres_password }}' }
- { regexp: '^ # - OPENAI_API_KEY=', line: ' - OPENAI_API_KEY={{ openai_api_key }}' }
- { regexp: '^ # - ANTHROPIC_API_KEY=', line: ' - ANTHROPIC_API_KEY={{ anthropic_api_key }}' }
- { regexp: '^ # - GEMINI_API_KEY=', line: ' - GEMINI_API_KEY={{ gemini_api_key }}' }
when: item.line | length > 0
- name: Configure domain settings (if applicable)
lineinfile:
path: "{{ app_root }}/docker-compose.yml"
regexp: "{{ item.regexp }}"
line: "{{ item.line }}"
loop:
- { regexp: '^ # - KHOJ_DOMAIN=', line: ' - KHOJ_DOMAIN={{ khoj_domain }}' }
- { regexp: '^ # - KHOJ_NO_HTTPS=', line: ' - KHOJ_NO_HTTPS={{ khoj_no_https }}' }
when: khoj_domain | length > 0
- name: Start Khoj stack
command: docker compose up -d
args:
chdir: "{{ app_root }}"
- name: Display setup instructions
debug:
msg: |
Khoj has been deployed to {{ app_root }}
ACCESS:
- Local: http://localhost:{{ app_port }}
{% if khoj_domain | length > 0 %}
- Remote: https://{{ khoj_domain }}
{% endif %}
FIRST RUN:
1. Open http://localhost:{{ app_port }}
2. Create admin account with email and password
3. Configure chat models in admin panel
ADMIN PANEL:
- URL: http://localhost:{{ app_port }}/server/admin
- Use localhost (not 127.0.0.1) to avoid CSRF errors
IMPORTANT:
- Change default database password in docker-compose.yml
- Set strong KHOJ_DJANGO_SECRET_KEY (50+ characters)
- Configure API keys for cloud models or Ollama for local models
Repository: https://github.com/khoj-ai/khoj
Documentation: https://docs.khoj.dev/
ansible-playbook -i inventory.ini khoj.yml
Create a khoj_vars.yml file:
khoj_admin_password: "MySecureP@ssw0rd123!"
khoj_django_secret_key: "abcdefghijklmnopqrstuvwxyz0123456789ABCDEFGHIJKLMNOPQRSTUVWXYZ!@#$"
postgres_password: "SecureDbP@ss456!"
openai_api_key: "sk-..."
khoj_domain: "khoj.example.com"
khoj_no_https: "False"
Run with extra vars:
ansible-playbook -i inventory.ini khoj.yml -e "@khoj_vars.yml"
Access Khoj: Open http://localhost:42110 (or your domain)
Create Admin Account:
Configure Chat Models:
/server/admin (use localhost, not 127.0.0.1)For Local Models (Ollama):
ollama pull qwen3OPENAI_BASE_URL=http://host.docker.internal:11434/v1/ansible-playbook -i inventory.ini khoj.yml --tags upgrade
Or manually on the host:
cd /opt/khoj
docker compose pull
docker compose up -d
# Backup Docker volumes
tar -czf khoj-backup-$(date +%Y%m%d).tar.gz /opt/khoj
# Backup database
docker compose exec database pg_dump -U postgres postgres > khoj-db-backup.sql
localhost (not 127.0.0.1) to avoid CSRF errorsKHOJ_DOMAIN and KHOJ_NO_HTTPS=True for remote accessAny questions?
Feel free to contact us. Find all contact information on our contact page.