Deploying OpenWebUI + OpenRouter API on a Debian Server with Cloudflare DNS

This article explains how to deploy a browser-accessible OpenWebUI chat interface on a Debian-based system and connect it to large language models through the OpenRouter API, creating a self-hosted ChatGPT-like web interface. We will also configure a domain using Cloudflare DNS, allowing the service to be accessed directly through <ai.your-domain>.

1. Introduction to the Tools and Components

1. OpenWebUI

OpenWebUI is an open-source web chat frontend that supports both local models, such as Ollama, and remote models, such as OpenAI and OpenRouter.

It provides a modern chat interface, user management, multi-model support, and other features, making it an ideal self-hosted AI frontend.

2. OpenRouter API

OpenRouter provides a unified API for accessing models from multiple providers, including OpenAI, Anthropic, Mistral, and others.

After registering, you can obtain an API key in the following format:

text
sk-or-v1-xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

Configure this key in OpenWebUI to access the available models.

3. Cloudflare DNS

Cloudflare DNS is used to point your own domain name to the public IP address of your server.

It can also provide reverse proxying, security acceleration, and HTTPS support.

2. Environment Preparation

Make sure your system is Debian / Ubuntu and meets the following requirements:

Python $\geqslant$ 3.11
pip and venv are available
You own a manageable domain name
The domain has been added to Cloudflare DNS

Install Required Dependencies

bash
sudo apt update
sudo apt install python3 python3-venv python3-pip git -y

3. Install OpenWebUI

1. Create and Activate a Virtual Environment

bash
mkdir -p /opt/openwebui
cd /opt/openwebui
python3 -m venv venv
source venv/bin/activate

2. Install OpenWebUI

bash
pip install open-webui

3. Start the Service

bash
openwebui serve

By default, OpenWebUI listens on port 8080.

You can access it directly at:

text
http://<server-IP>:8080

The first account created will automatically become the administrator account.

4. Configure Cloudflare DNS

Select your domain.
Add an A record:

text
Name: ai
Content: <your server's public IP>
Proxy status: optional (DNS only / Proxied)

After saving the record, you can test it with:

bash
ping ai.<your-domain>

If the domain resolves to the correct IP address, the DNS configuration is working.

Note that the Cloudflare proxy should be disabled.

5. Connect the OpenRouter API

Register at OpenRouter and copy your API key.
In the OpenWebUI interface, go to:

Admin Settings → Connections → OpenRouter
Paste your API key and save the configuration.

6. Reverse Proxy with Caddy

The architecture we want is:

text
[ Internet ]
      ↓
   ai.<your-domain>  ──(443/80)──▶  [Caddy] ──▶ localhost:8080 (OpenWebUI)

1. Install Caddy

bash
sudo apt install -y debian-keyring debian-archive-keyring apt-transport-https
curl -1sLf 'https://dl.cloudsmith.io/public/caddy/stable/gpg.key' | sudo gpg --dearmor -o /usr/share/keyrings/caddy-stable-archive-keyring.gpg
curl -1sLf 'https://dl.cloudsmith.io/public/caddy/stable/debian.deb.txt' | sudo tee /etc/apt/sources.list.d/caddy-stable.list
sudo apt update
sudo apt install -y caddy

2. Configure Caddy

Edit /etc/caddy/Caddyfile and add:

text
ai.<your-domain> {
    reverse_proxy localhost:8080
}

3. Enable and Start Caddy

bash
sudo systemctl enable --now caddy
sudo systemctl restart caddy

7. Allow All Users to Access All Models

By default, ordinary users may not be able to access all models configured by the administrator.

To solve this, set the following environment variable:

bash
BYPASS_MODEL_ACCESS_CONTROL=True

Set it in the virtual environment:

bash
source /openwebui/venv/bin/activate
export BYPASS_MODEL_ACCESS_CONTROL=True
openwebui serve

8. Keep OpenWebUI Running in the Background

Simple Method: `nohup`

bash
nohup openwebui serve > openwebui.log 2>&1 &

Recommended Method: Manage the Service with systemd

Create the file:

text
/etc/systemd/system/openwebui.service

with the following contents:

ini
[Unit]
Description=Open WebUI
After=network-online.target
Wants=network-online.target

[Service]
Type=simple

# The current installation is under /root and runs as root
User=root
Group=root

WorkingDirectory=/root/openwebui

# Start the executable directly from the virtual environment
ExecStart=/root/openwebui/venv/bin/open-webui serve

# Automatically restart if the service exits unexpectedly
Restart=on-failure
RestartSec=3

# Logging: choose one of the following approaches

# Option A: write logs to journald
# Recommended. This is also the default behavior.
StandardOutput=journal
StandardError=journal

# Option B: continue writing logs to a file
# Requires systemd 240+ for append:
# StandardOutput=append:/root/openwebui/openwebui.log
# StandardError=append:/root/openwebui/openwebui.log

# Optional: add environment variables here if needed
# Environment="HOST=0.0.0.0"
# Environment="PORT=8080"

[Install]
WantedBy=multi-user.target

Enable and start the service:

bash
sudo systemctl daemon-reload
sudo systemctl enable openwebui
sudo systemctl start openwebui

You can then check the service status with:

bash
sudo systemctl status openwebui

9. Update OpenWebUI

When a new version is released, activate the virtual environment and run:

bash
source /openwebui/venv/bin/activate
pip install --upgrade open-webui

Then restart the service:

bash
sudo systemctl restart openwebui

10. Summary

At this point, you have completed the following configuration:

Item	Status
Cloudflare DNS configuration	✅
OpenWebUI installation	✅
OpenRouter API integration	✅
Model access enabled for all users	✅
Background service and automatic startup	✅
Update mechanism	✅

You can now access your self-hosted AI platform at:

text
https://ai.<your-domain>

You now have a fully self-hosted, modern, and secure AI chat system 🎉

Contents