Run AI Tutor yourself

Almost every install problem below comes from picking the wrong one, because the default configuration assumes the first.

Files land flat in ai-tutor/, not in a deploy/compose/ subdirectory. This is also where backup.sh lives, so that is the directory you run it from later.

That first docker run already pulls the full image (~7 GB), so the docker compose pull in step 4 is usually instant.

Read docker-compose.yml and Caddyfile before running them. Both are commented and short. Caddyfile in particular contains a ready-made plain-HTTP block you will need if you are not on the public-server shape.

Optionally pin the exact image, so a later pull cannot drift from the compose file you just extracted:

docker inspect --format='{{index .RepoDigests 0}}' ghcr.io/eai6/ai-tutor:latest
# put the resulting name@sha256:... into the app service's image: line

Optional: ACME_EMAIL (only used when requesting a certificate) and HTTPS_EDGE.

Public server:

SITE_DOMAIN=tutor.yourdomain.example
ACME_EMAIL=you@yourdomain.example
ALLOWED_HOSTS=tutor.yourdomain.example
CSRF_TRUSTED_ORIGINS=https://tutor.yourdomain.example
HTTPS_EDGE=true

LAN-only or laptop:

SITE_DOMAIN=localhost
#ACME_EMAIL=
ALLOWED_HOSTS=localhost,127.0.0.1
CSRF_TRUSTED_ORIGINS=http://localhost
HTTPS_EDGE=false

Duplicate keys are easy to introduce while editing, and the last one silently wins. Check:

grep -n 'HTTPS_EDGE\|ALLOWED_HOSTS\|CSRF_TRUSTED\|SITE_DOMAIN' .env

Keep a copy of the original first: cp Caddyfile Caddyfile.orig. Then delete the global email block and replace the whole {$SITE_DOMAIN} block with the plain-HTTP block already commented at the bottom of the file:

:80 {
    encode gzip

    reverse_proxy app:8000 {
        header_up X-Real-IP {remote_host}
        transport http {
            read_timeout 300s
            write_timeout 300s
        }
    }

    log {
        output stdout
        format console
    }
}

Laptop only: in docker-compose.yml, bind Caddy to loopback and drop 443, which nothing listens on now.

    ports:
      - "127.0.0.1:80:80"

"80:80" binds every interface including wifi. Docker writes its own iptables rules ahead of ufw, so a firewall rule will not substitute for this — the bind address is the only control that works.

A line like this one:

Indexed. Collection size: 0 → 151.

Or check the health state, which is the same signal:

docker compose ps    # wait for app to show (healthy)

A BertModel LOAD REPORT line flagging embeddings.position_ids as UNEXPECTED during this is normal and can be ignored.

Leaving it blank accepts the container's OS user, which gives you an account called root — easy to do by accident and confusing later. To fix it afterwards:

docker compose exec app python manage.py changepassword <name>

The commonest failure, and a silent one. Django marks session and CSRF cookies Secure; a browser will not send those over plain HTTP, so the login simply bounces.

Finish the HTTPS setup, or set HTTPS_EDGE=false and switch the Caddyfile to the :80 block. Both are required. Then run docker compose up -d — not restart, see below.

If it persists, check what Django actually resolved:

docker compose exec app python -c "
import django; django.setup()
from django.conf import settings
print(settings.ALLOWED_HOSTS, settings.CSRF_TRUSTED_ORIGINS)
"

docker compose restart does not re-read .env. Neither do port or volume changes take effect. Always use docker compose up -d, which recreates the affected containers.

You ran createsuperuser before migrations finished — most likely by pasting it together with up -d. Nothing is broken. Wait for the app to report healthy and run it again.

Caddy is redirecting to HTTPS but has no certificate to serve for the hostname you asked for. Either the certificate was never issued (see the next entry), or you are browsing to localhost while the only site block is for {$SITE_DOMAIN} — no site matches, so the handshake is aborted before any HTTP happens. Switch to the :80 block.

ACME_EMAIL is still the placeholder from env.example. .xx is not a real TLD, so Let's Encrypt refuses the account and Caddy falls back to ZeroSSL, which refuses too. Caddy then retries with backoff for 30 days.

Set a real address, or remove the ACME block entirely if you are not using a public domain. The same applies to SITE_DOMAIN: issuance also needs the domain to already resolve to this server, with ports 80 and 443 reachable from the internet. A laptop behind NAT cannot satisfy that.

To clear the failed account state afterwards:

docker compose down && docker volume rm ai-tutor_caddy_data

The old redirect was a 308 Permanent, and browsers cache those aggressively — you will be sent to https:// without Caddy ever being asked. Use a private window, or clear site data for that host.

Confirm from the shell, which does not cache:

curl -sI http://localhost/admin/    # want 302 to /admin/login/, not 308

Docker's apt repository has no kali-rolling suite. Use Kali's own package, then install the Compose plugin binary directly rather than falling back to the v1 docker-compose script:

sudo apt install docker.io
mkdir -p ~/.docker/cli-plugins
curl -SL https://github.com/docker/compose/releases/latest/download/docker-compose-linux-x86_64 \
  -o ~/.docker/cli-plugins/docker-compose
chmod +x ~/.docker/cli-plugins/docker-compose

Adding yourself to the docker group is effectively passwordless root — anyone who can reach the Docker socket can mount / into a container. On a workstation, consider sudo docker instead.

ai-tutor init runs as root and writes the file 0600 root:root. ai-tutor systemd generates a unit that runs as an unprivileged user. Nothing reconciles them.

See pip step 5 — chown root:<user> and chmod 640 the env file, chown -R the data directory, then systemctl reset-failed before restarting.

collectstatic was never run. Django's manifest storage raises rather than degrading to unstyled output, so even the login form fails. See pip step 6.

Note that curl -I /admin/ still returns a healthy 302, because a redirect renders no template — this failure is only visible in a browser.

If DATABASE_URL is unset, Django falls back to SQLite and everything appears to work — with no pgvector behind retrieval. Run ls -la /var/lib/ai-tutor/: a db.sqlite3 there means the fallback happened.