Mastering Open-Source AI with OpenWebUI and OpenRouter on Linux

• Prerequisites:
  • Ubuntu 22.04+ (tested on 24.04)
  • Root/sudo access
  • Docker & Docker Compose (v2+)
  • OpenRouter.ai account & API key (https://openrouter.ai/keys)
• Install Docker (Official Ubuntu method):

  sudo apt update && sudo apt upgrade -y
  sudo apt install ca-certificates curl -y
  sudo install -m 0755 -d /etc/apt/keyrings
  sudo curl -fsSL https://download.docker.com/linux/ubuntu/gpg -o /etc/apt/keyrings/docker.asc
  sudo chmod a+r /etc/apt/keyrings/docker.asc
  echo "deb [arch=$(dpkg --print-architecture) signed-by=/etc/apt/keyrings/docker.asc] https://download.docker.com/linux/ubuntu $(. /etc/os-release && echo "$VERSION_CODENAME") stable" | sudo tee /etc/apt/sources.list.d/docker.list > /dev/null
  sudo apt update
  sudo apt install docker-ce docker-ce-cli containerd.io docker-buildx-plugin docker-compose-plugin -y
  sudo usermod -aG docker $USER
  newgrp docker

  Test: docker compose version

mkdir ~/openwebui && cd ~/openwebui

Create docker-compose.yml:

version: '3.8'
services:
  openwebui:
    image: ghcr.io/open-webui/open-webui:main
    container_name: openwebui
    restart: unless-stopped
    ports:
      - "3000:8080"
    environment:
      - WEBUI_SECRET_KEY=your-secure-random-key  # Generate: openssl rand -hex 32
      - OPENAI_API_BASE=https://openrouter.ai/api/v1
      - OPENAI_API_KEY=your-openrouter-api-key-here
    volumes:
      - openwebui:/app/backend/data
    healthcheck:
      test: ["CMD", "wget", "--quiet", "--tries=1", "--spider", "http://localhost:8080/health"]
      interval: 30s
      timeout: 10s
      retries: 3
volumes:
  openwebui:

Run:

docker compose up -d

Access: http://your-server-ip:3000

1. Sign up/login at OpenWebUI.
2. Admin > Connections > OpenAI > Edit:
3. Base URL: https://openrouter.ai/api/v1
4. API Key: sk-or-... (from OpenRouter dashboard)
5. Save. Models auto-load (e.g., openai/gpt-4o-mini).

sudo systemctl enable --now docker.socket docker.service
sudo ufw allow 3000

Optional HTTPS (Caddy):

sudo apt install caddy -y
cat <<EOF | sudo tee /etc/caddy/Caddyfile
your-domain.com {
    reverse_proxy localhost:3000
}
EOF
sudo systemctl restart caddy