DocsGPT

• In the Azure Portal, search the Marketplace for DocsGPT, select the SecureAnyCloud offer, and choose Create.
• Choose your subscription, resource group and region.
• Set the VM size to Standard_D4s_v4 or larger.
• Under Administrator account, select SSH public key and supply your own key.
• Under Inbound port rules, allow HTTPS (443), HTTP (80) and SSH (22). Then restrict all three to your own address ranges on the networking blade.
• Choose Review + create.

az vm image terms accept --urn sac1647283583153:docsgpt-ubuntu-24-04:default:latest
az vm create \
  --resource-group my-resource-group \
  --name my-docsgpt \
  --image sac1647283583153:docsgpt-ubuntu-24-04:default:latest \
  --size Standard_D4s_v4 \
  --admin-username azureuser \
  --ssh-key-values ~/.ssh/id_rsa.pub \
  --public-ip-sku Standard
# Open HTTPS (and the HTTP redirect) to YOUR network only. MY_CIDR="203.0.113.0/24"
# replace with your own range
az network nsg rule create \
  --resource-group my-resource-group \
  --nsg-name my-docsgptNSG \
  --name allow-https-from-office --priority 1010 \
  --source-address-prefixes "${MY_CIDR}" \
  --destination-port-ranges 80 443 --protocol Tcp --access Allow

ssh azureuser@<vm-ip>

First boot takes about a minute. It generates this VM's secrets and certificate, starts the local model and initializes DocsGPT's database. It proves the sign-in gate before it finishes.

# Every unit reports "active".
systemctl is-active docker ollama docsgpt docsgpt-model-gateway nginx test -f /var/lib/sac/data/docsgpt-firstboot.done && echo "first boot complete"
# Only SSH (22) and nginx (80, 443) listen publicly. DocsGPT listens on 127.0.0.1:7091,
# Ollama on 127.0.0.1:11434, the model gateway on the private Docker bridge address
# 172.30.252.1:11435, and port 53 is the operating system's local DNS resolver.
sudo ss -lntpH | grep -v llama-server | awk '{print $4}' | sort -u

Expected output:

active active active active active first boot complete 0.0.0.0:22 0.0.0.0:443 0.0.0.0:80 127.0.0.1:11434 127.0.0.1:7091 127.0.0.53%lo:53 127.0.0.54:53 172.30.252.1:11435 [::]:22 [::]:443 [::]:80

While the model is loaded, Ollama's model runner also listens on a random high port of 127.0.0.1. The command above hides that port, and it is loopback only. DocsGPT runs as four containers:

sudo docker compose -f /etc/docsgpt/compose.yaml ps --format 'table {{.Service}}\t{{.State}}\t{{.Ports}}'

SERVICE STATE PORTS backend running 127.0.0.1:7091->7091/tcp postgres running 5432/tcp valkey running 6379/tcp worker running 7091/tcp

5432/tcp, 6379/tcp and the worker's 7091/tcp are inside the private Docker network. They are not published to the VM or the network.

First boot generated everything in this file on this VM.

sudo cat /root/docsgpt-credentials.txt

# DocsGPT - per-VM credentials generated on first boot (...). Keep this file private.
# Open DOCSGPT_URL in a browser and sign in with this user name and password.
# Change the password:
sudo htpasswd -B /etc/docsgpt/htpasswd admin DOCSGPT_URL=https://<vm-ip>/ DOCSGPT_USERNAME=admin DOCSGPT_PASSWORD=<DOCSGPT_PASSWORD>
# Bundled local model (CPU): Qwen2.5 1.5B Instruct via Ollama, already the default model in DocsGPT. DOCSGPT_MODEL=qwen2.5:1.5b

• Open DOCSGPT_URL from the credentials file in your browser. The certificate is self-signed and generated for this VM, so your browser shows a warning the first time. Accept it for this address, or follow Step 12 to use your own domain and a trusted certificate.
• When your browser asks for a user name and password, enter admin and DOCSGPT_PASSWORD.
• DocsGPT opens with qwen2.5:1.5b, the local model, already selected.

Change the password from an SSH session. The command asks for the new password twice and stores it as a bcrypt hash:

sudo htpasswd -B /etc/docsgpt/htpasswd admin

nginx reads the change immediately. The password protects the whole site, so everyone who signs in shares one DocsGPT workspace. Give the password only to people who should see every document and conversation. Step 9 explains the access model.

• Select Settings, then Knowledge, then Add knowledge.
• Upload files, or choose a website or sitemap to crawl. DocsGPT accepts PDF, Word, Markdown, text, HTML, CSV, Excel, PowerPoint, EPUB and more.
• DocsGPT splits each document into chunks and indexes them on the VM's CPU. Indexing takes seconds for a small file and a few minutes for a large set. In our test, 77 Markdown documents took about 4.5 minutes.
• Select a source to see its chunks and search them. Use Test retrieval to check what a question would find.

You can do the same through the API. Every API call needs this VM's password. Keep it in a private curl configuration file rather than on the command line:

PW=$(sudo sed -n 's/^DOCSGPT_PASSWORD=//p' /root/docsgpt-credentials.txt) ( umask 077; printf 'user = "admin:%s"\n' "$PW" > ~/.docsgpt-curl ) curl -sk -K ~/.docsgpt-curl https://127.0.0.1/api/config | jq -c '{auth_type, requires_auth}'

{"auth_type":null,"requires_auth":false}

DocsGPT's own login is off (auth_type null) because nginx already asks for this VM's password on every request. DocsGPT never sees an unauthenticated request.

Upload a document and wait for it to be indexed:

cat > ~/harbour-lane-servicing.md <<'EOF'
# Harbour Lane Cycles - Servicing A standard service costs 65 GBP and takes two working days. A full overhaul costs 140 GBP and takes five working days. Every service includes a free safety check after 300 miles. EOF
TASK=$(curl -sk -K ~/.docsgpt-curl -F user=local -F name=harbour-lane-servicing \
  -F file=@"$HOME/harbour-lane-servicing.md" https://127.0.0.1/api/upload | jq -r .task_id) for i in $(seq 1 60); do
S=$(curl -sk -K ~/.docsgpt-curl "https://127.0.0.1/api/task_status?task_id=$TASK" | jq -r .status) [ "$S" = SUCCESS ] && break; sleep 3 done echo "ingest: $S" curl -sk -K ~/.docsgpt-curl https://127.0.0.1/api/sources | jq -r '.[] | .name' | sort

ingest: SUCCESS harbour-lane-servicing

• Select New Chat.
• Select Knowledge under the message box and choose the sources to search.
• Type your question and press Enter. The answer appears with Sources. Select a source card to see the passage it came from.

You can ask the same question through the API:

SRC=$(curl -sk -K ~/.docsgpt-curl https://127.0.0.1/api/sources | jq -r '.[] | select(.name=="harbour-lane-servicing") | .id')
curl -sk -K ~/.docsgpt-curl -H 'Content-Type: application/json' \
  -d "{\"question\":\"How much does a full overhaul cost and how long does it take?\",\"active_docs\":\"$SRC\",\"history\":\"[]\"}" \
  https://127.0.0.1/api/answer | jq -r '.answer, (.sources[] | "source: \(.title)")'

Example output follows. The answer is generated, so your wording will differ:

A full overhaul costs 140 GBP and takes five working days. source: harbour-lane-servicing.md

/stream returns the same answer as server-sent events while it is generated. The full API reference is at docs.docsgpt.cloud. Every call to this VM needs the password, as shown above.

Speed tips for the local model. By default, DocsGPT retrieves six passages for each question, and most of the answer time on a CPU is the model reading them. To retrieve fewer, open Settings > Knowledge, select the menu on a source, and choose Source settings. Then lower Chunks to retrieve (top-k). The change takes effect immediately, with no re-indexing.

Through the API, add "chunks": 3 to the request. Fewer passages mean a shorter prompt and a faster answer, at the cost of context. Short, focused documents also help. For production use, connect a cloud model (Step 10).

• Sign-in. nginx asks for this VM's password on every page and every API call. That includes the web UI, uploads, website imports, /api/answer, /stream, agent and widget endpoints, and webhooks. The password travels only over HTTPS (with HSTS), nginx removes it before the request reaches DocsGPT, and DocsGPT sets no cookies. Wrong passwords are refused with 401.
• Cross-site requests are refused. Browsers re-send a site's password automatically, so another website you visit could otherwise make your browser act on DocsGPT. nginx refuses with 403 any change (POST, PUT, PATCH, DELETE) whose Origin or Referer is another site. It also refuses any request that another site's page makes in the background (images, scripts, fetches), even if the request carries the password.
• Following a link to DocsGPT from elsewhere still opens it. API clients such as curl or scripts, which send no Origin, work normally. DocsGPT's permissive CORS headers are removed, so no other website can read its responses.
• One workspace. Everyone with the password shares the same DocsGPT workspace, documents and conversations. If you need separate user accounts, DocsGPT supports single sign-on through OpenID Connect (AUTH_TYPE=oidc with your own identity provider). See the DocsGPT documentation.
• Agents and widgets. DocsGPT agents have API keys for embedding a chat widget in another website. On this VM, those endpoints are behind the same password and the cross-site rule. A widget on another site will not work until you deliberately open those paths in nginx.
• Network. nginx is the only public listener. It serves DocsGPT on port 443 with a certificate generated for this VM, and port 80 only redirects to HTTPS. DocsGPT listens on 127.0.0.1:7091. PostgreSQL and Valkey are on a private Docker network and require their per-VM passwords.
• The local model. Ollama has no login of its own, so it listens only on the VM's loopback address. The DocsGPT containers reach it through the model gateway on 172.30.252.1:11435. The gateway needs a per-VM key and passes only the OpenAI-style /v1/ API, so nothing on the network can pull or delete models. A firewall rule lets only the DocsGPT backend and worker containers reach the gateway.
• Fail closed. DocsGPT, Ollama and the gateway start only after first boot has written this VM's secrets. nginx starts only after first boot has proven the password gate. If first boot fails, it removes its markers and stops everything, so nothing serves a half-configured VM. Before every start, DocsGPT's unit also refuses to run if a secret is missing or an upstream default, or if a third-party setting was turned on without an explicit opt-in.

You can check the gate yourself. In this check, 405 means that the request reached DocsGPT with the correct password, but that route accepts only POST:

code() { curl -sk -o /dev/null -w '%{http_code}' "$@"; } echo "anonymous UI : $(code https://127.0.0.1/)" echo "anonymous answer API : $(code -X POST https://127.0.0.1/api/answer)" echo "anonymous upload : $(code -X POST https://127.0.0.1/api/upload)" echo "with this VM's password: $(code -K ~/.docsgpt-curl https://127.0.0.1/api/config)" echo "plain HTTP : $(code http://127.0.0.1/)" echo "cross-site POST : $(code -K ~/.docsgpt-curl -X POST -H 'Origin: https://other-site.example' https://127.0.0.1/api/answer)"

Expected output:

anonymous UI : 401 anonymous answer API : 401 anonymous upload : 401 with this VM's password: 200 plain HTTP : 301 cross-site POST : 403

Outbound requests (SSRF protection). DocsGPT fetches web pages when you import a website, and it calls the model providers you configure. A firewall rule applied before any container starts stops the DocsGPT containers from reaching these destinations:

The Azure Instance Metadata Service (169.254.169.254) and the Azure wire server (168.63.129.16). Loopback. Your private address ranges (10.0.0.0/8, 172.16.0.0/12, 192.168.0.0/16, 100.64.0.0/10). Link-local and other reserved ranges. Every service on the VM except the model gateway.

Between the DocsGPT containers, only the connections the application needs are allowed: the API and worker to PostgreSQL and Valkey, and the worker to the API. A fetched URL therefore cannot reach another container either.

The check is on the network packets, so it also holds when a URL redirects or when a host name resolves to one of those addresses. DocsGPT also validates URLs itself, and the firewall is the second, independent layer. Check it from inside the worker, the container that fetches URLs:

sudo docker exec -i docsgpt-worker-1 python - <<'EOF' import socket def reach(host, port): try: socket.create_connection((host, port), timeout=5).close() return "open" except OSError: return "blocked" for name, host, port in [("Azure IMDS ", "169.254.169.254", 80), ("Azure WireServer", "168.63.129.16", 80), ("private network ", "10.0.0.1", 80), ("model gateway ", "172.30.252.1", 11435), ("internet ", "www.example.com", 443)]: print(name, reach(host, port)) EOF

Expected output:

Azure IMDS blocked Azure WireServer blocked private network blocked model gateway open internet open

Reaching a private address on purpose. Suppose you want DocsGPT to import from a server on your own network, or to use a model behind a private endpoint. Add that address to /etc/docsgpt/egress-allow, one entry per line, optionally limited to a TCP port. Then restart Docker. The metadata service, the wire server and loopback can never be allowed:

echo "10.20.30.40 tcp 443" | sudo tee -a /etc/docsgpt/egress-allow
sudo systemctl restart docker docsgpt

DocsGPT's own URL check also refuses private addresses for website imports, so this setting is mainly for model and connector endpoints.

By default, nothing leaves the VM. These settings in /etc/docsgpt/docsgpt.env keep it that way. Only root can read the file:

sudo grep -E '^(LLM_PROVIDER|LLM_NAME|OPENAI_BASE_URL|VERSION_CHECK|TTS_PROVIDER|STT_PROVIDER|ORT_DISABLE_TELEMETRY|HF_HUB_OFFLINE|BACKGROUND_JOBS_ENABLED|MONITORS_ENABLED)=' /etc/docsgpt/docsgpt.env

LLM_PROVIDER=openai LLM_NAME=qwen2.5:1.5b OPENAI_BASE_URL=http://172.30.252.1:11435/v1 VERSION_CHECK=false TTS_PROVIDER=none STT_PROVIDER=none ORT_DISABLE_TELEMETRY=1 HF_HUB_OFFLINE=1 BACKGROUND_JOBS_ENABLED=false MONITORS_ENABLED=false

• OPENAI_BASE_URL points DocsGPT at the bundled model through the model gateway. While it is set, DocsGPT also hides its hosted Arc53 model and the cloud OpenAI catalog.
• VERSION_CHECK=false stops DocsGPT from reporting its version, with an instance identifier, to Arc53 every few hours.
• TTS_PROVIDER and STT_PROVIDER are off. Upstream sends text to Google for speech and audio to OpenAI for transcription.
• ORT_DISABLE_TELEMETRY stops the ONNX runtime that runs the embedding model from sending usage telemetry to Microsoft. HF_HUB_OFFLINE keeps the embedding model from contacting Hugging Face, because the model is already on the VM.
• BACKGROUND_JOBS_ENABLED and MONITORS_ENABLED are off. Their tool descriptions add about 2,500 tokens of tool definitions to every question, which more than doubled answer times on the local model (67 seconds instead of 24 in our test). Turn them back on when you use a cloud model.

Add a cloud model from the web interface. Select Settings > Custom Models > Add model and enter an OpenAI-compatible endpoint. Provide its Base URL, Model ID and API key, and use Test connection to check them.

The model then appears in the model menu next to qwen2.5:1.5b, and you can choose it per chat. Questions you ask with that model, and the passages DocsGPT retrieves for them, are sent to that provider.

Or make a cloud model the default. Edit /etc/docsgpt/docsgpt.env as root and restart DocsGPT. The next example uses Azure OpenAI through its OpenAI-compatible endpoint. Use your resource name, key and the name of your chat deployment:

LLM_PROVIDER=openai LLM_NAME=YOUR_DEPLOYMENT_NAME OPENAI_BASE_URL=https://YOUR_RESOURCE.openai.azure.com/openai/v1 OPENAI_API_KEY=<set-at-first-boot> API_KEY=YOUR_AZURE_OPENAI_KEY

To use Anthropic instead, set LLM_PROVIDER=anthropic and ANTHROPIC_API_KEY=<set-at-first-boot>. Set LLM_NAME to a model ID from the DocsGPT documentation, and remove OPENAI_BASE_URL, OPENAI_API_KEY and API_KEY. Then restart DocsGPT:

sudo systemctl restart docsgpt

The local embedding model still indexes your documents on the VM. Only questions and the retrieved passages go to the provider you chose.

Opting in to Arc53's hosted model. Upstream DocsGPT's default is a free hosted model run by Arc53. It receives your questions and the retrieved passages from your documents. If you want it, choose it deliberately.

In /etc/docsgpt/docsgpt.env, set LLM_PROVIDER=docsgpt. Remove the LLM_NAME, OPENAI_BASE_URL, OPENAI_API_KEY and API_KEY lines, and add SAC_OPT_IN_ARC53_MODEL=yes. Then restart DocsGPT.

Without that opt-in line, DocsGPT refuses to start rather than send your content to a third party by accident. The version check works the same way (VERSION_CHECK=true plus SAC_OPT_IN_VERSION_CHECK=yes).

The bundled model stays loaded in memory so the first question never waits for it:

curl -s http://127.0.0.1:11434/api/ps | jq -r '.models[] | "\(.name) \(.details.parameter_size) \(.details.quantization_level)"'

qwen2.5:1.5b 1.5B Q4_K_M

To try a larger local model, choose one whose license suits you and pull it into Ollama. Add its name to LLM_NAME, comma-separated, for example LLM_NAME=qwen2.5:1.5b,qwen2.5:7b. Then restart DocsGPT:

sudo -u ollama env HOME=/var/lib/ollama OLLAMA_HOST=127.0.0.1:11434 /opt/ollama/bin/ollama pull qwen2.5:7b
sudo systemctl restart docsgpt

Larger models answer better, but they are much slower on a CPU and need more memory. Allow roughly the model's download size again in free RAM.

Point a DNS record at the VM's public IP. Open port 80 to the internet for the certificate check. Then replace the self-signed certificate with one from Let's Encrypt:

sudo apt-get install -y certbot
sudo certbot certonly --webroot -w /var/www/html -d docs.example.com
sudo sed -i \
  -e 's#/etc/docsgpt/tls/server.crt#/etc/letsencrypt/live/docs.example.com/fullchain.pem#' \
  -e 's#/etc/docsgpt/tls/server.key#/etc/letsencrypt/live/docs.example.com/privkey.pem#' \
  /etc/nginx/sites-available/docsgpt
sudo nginx -t && sudo systemctl reload nginx

Certbot renews the certificate automatically. Add --deploy-hook "systemctl reload nginx" to the certonly command so that nginx picks up each renewal.

Check the logs and status:

sudo tail -n 4 /var/log/docsgpt-firstboot.log | cut -c28- sudo docker compose -f /etc/docsgpt/compose.yaml logs --tail 3 backend

The first boot log never contains a password or key.

Restart. sudo systemctl restart docsgpt restarts the DocsGPT containers. The UI answers again after about 30 seconds. sudo systemctl restart ollama restarts the local model server and loads the model again.

Back up. Everything DocsGPT stores (database, uploaded files and indexes) is under /var/lib/docsgpt. Its settings and secrets are in /etc/docsgpt. Stop DocsGPT for a consistent copy:

sudo systemctl stop docsgpt
sudo tar -C / -czf /root/docsgpt-backup-$(date +%F).tar.gz var/lib/docsgpt etc/docsgpt
sudo systemctl start docsgpt

Copy the archive off the VM. It contains your secrets and documents, so keep it as private as the VM itself. You can also snapshot the VM's OS disk in Azure.

Updates. Ubuntu security updates install automatically. DocsGPT, PostgreSQL and Valkey are pinned to image digests in /etc/docsgpt/compose.yaml for a repeatable deployment.

To move to a later DocsGPT release, back up first. Replace the arc53/docsgpt@sha256:... reference with the new release's digest from Docker Hub. Run sudo docker compose -f /etc/docsgpt/compose.yaml pull and restart DocsGPT. DocsGPT migrates its database on start.

Troubleshooting.

• The browser shows 502 Bad Gateway. DocsGPT is still starting. After a reboot or restart, it takes about 30 seconds. Wait and reload.
• The browser keeps asking for the password. Use the user name admin and the password from /root/docsgpt-credentials.txt. Or set a new password with htpasswd (Step 6).
• Answers are slow. The local model runs on the CPU. Lower the number of chunks (Step 8), use a non-burstable VM size, or connect a cloud model (Step 10). On a B-series VM, check the CPU credits in the Azure Portal under the VM's Metrics.
• A website import fails. The firewall blocks private addresses (Step 9), but public websites work. Check sudo docker compose -f /etc/docsgpt/compose.yaml logs --tail 50 worker.
• DocsGPT does not start after you edited docsgpt.env. Run sudo /usr/local/sbin/docsgpt-preflight. It prints the setting it refuses and why.
• First boot did not finish. Read /var/log/docsgpt-firstboot.log.