This chapter details the preparation of a Linux Ubuntu server environment for hosting OpenWebUI. It covers the installation of Docker Community Edition (Docker CE) and Docker Compose, emphasizing best practices for a secure and persistent setup. Additionally, it instructs on creating custom Docker networks and volumes for data persistence. This robust foundation is crucial for managing AI tools like OpenWebUI effectively within containerized environments.

Assumptions and Prerequisites

• You have a fresh installation of Ubuntu Server (LTS recommended) or a desktop variant with command-line access.
• You have a non-root user with sudo privileges. Running commands directly as root is discouraged for security reasons.
• Your system has internet connectivity to download packages.
• Basic familiarity with the Linux command line is assumed.

Step-by-Step Installation of Docker CE and Docker Compose

Step 1: Update System Packages and Install Dependencies

It’s crucial to start by ensuring your system’s package list is up-to-date and installing necessary dependencies for Docker.

sudo apt update
sudo apt upgrade -y
sudo apt install -y ca-certificates curl gnupg lsb-release

Step 2: Add Docker’s Official GPG Key

Docker uses a GPG key to verify the authenticity of its packages. This step adds their official key to your system.

sudo install -m 0755 -d /etc/apt/keyrings
curl -fsSL https://download.docker.com/linux/ubuntu/gpg | sudo gpg --dearmor -o /etc/apt/keyrings/docker.gpg
sudo chmod a+r /etc/apt/keyrings/docker.gpg

Step 3: Set Up the Docker Repository

This command adds the Docker repository to your APT sources, allowing your system to find and install Docker packages.

echo \
  "deb [arch="$(dpkg --print-architecture)" signed-by=/etc/apt/keyrings/docker.gpg] https://download.docker.com/linux/ubuntu \
  "$(. /etc/os-release && echo "$VERSION_CODENAME")" stable" | sudo tee /etc/apt/sources.list.d/docker.list > /dev/null

Step 4: Install Docker Engine, Containerd, and Docker Compose

Now, update the package index again with the new Docker repository and install the core Docker components.

sudo apt update
sudo apt install -y docker-ce docker-ce-cli containerd.io docker-buildx-plugin docker-compose-plugin

Step 5: Add Your User to the Docker Group (Post-installation Step 1)

To run Docker commands without sudo, add your user to the docker group. You must log out and log back in for this change to take effect.

sudo usermod -aG docker $USER

Note: After running this command, log out and log back in to your server for the group membership change to apply.

Step 6: Configure Docker to Start on Boot

Docker is typically configured to start automatically, but it’s good practice to ensure it’s enabled.

sudo systemctl enable docker.service
sudo systemctl enable containerd.service

Step 7: Create Custom Docker Networks for OpenWebUI

Custom networks provide better isolation and allow containers to communicate by name. This is crucial for multi-container applications like OpenWebUI.

docker network create openwebui-net

Step 8: Create Custom Docker Volumes for OpenWebUI Data Persistence

Volumes are the preferred way to persist data generated by Docker containers. This ensures your OpenWebUI configurations and data are not lost when containers are removed or updated.

docker volume create openwebui-data

Verification Commands and Expected Indicators

After installation, verify that Docker and Docker Compose are correctly installed and running.

Verify Docker Engine Installation

Check the Docker version and run the official hello-world container.

docker --version
docker run hello-world

Expected Output for docker --version:

Docker version 2x.xx.x, build xxxxxxx

Expected Output for docker run hello-world:

Hello from Docker!
This message shows that your installation appears to be working correctly.
...

Verify Docker Compose Installation

Check the Docker Compose plugin version.

docker compose version

Expected Output:

Docker Compose version v2.xx.x

Verify Docker Service Status

Ensure the Docker daemon is active and running.

sudo systemctl status docker

Expected Output:

● docker.service - Docker Application Container Engine
     Loaded: loaded (/lib/systemd/system/docker.service; enabled; vendor preset: enabled)
     Active: active (running) ...
...

Verify Custom Docker Network and Volume Creation

Confirm that the custom network and volume exist.

docker network ls | grep openwebui-net
docker volume ls | grep openwebui-data

Expected Output for docker network ls | grep openwebui-net:

abcdefghijkl  openwebui-net       bridge    Local

Expected Output for docker volume ls | grep openwebui-data:

local     openwebui-data

Common Failure Modes and Fixes

• “permission denied while trying to connect to the Docker daemon socket”Cause: Your user is not in the docker group, or the changes haven’t taken effect.

  Fix: Ensure you’ve run sudo usermod -aG docker $USER and then completely logged out and logged back into your session. For SSH, this means closing your terminal and re-establishing the connection.

• “E: Unable to locate package docker-ce” or similar APT errorsCause: Docker repository not added correctly, or a typo in the sources.list.d file.

  Fix: Re-run Step 2 and Step 3 carefully, making sure there are no errors. Check the contents of /etc/apt/sources.list.d/docker.list to ensure it matches the expected format.

• Docker service not running (systemctl status docker shows inactive)Cause: Docker failed to start, possibly due to a system misconfiguration or resource issue.

  Fix: Check Docker logs for more details: sudo journalctl -u docker.service. Try restarting the service: sudo systemctl restart docker.

• docker compose command not foundCause: The Docker Compose plugin was not installed, or your PATH is not correct.

  Fix: Re-run Step 4 to ensure docker-compose-plugin is installed. If using an older Docker version, you might need to install docker-compose separately (which is no longer the recommended approach for newer Docker CE versions).

Security and Safety Notes

• Use a Non-Root User: Always perform system administration tasks using a non-root user with sudo privileges instead of directly as root. This limits potential damage from accidental commands.
• Keep Docker Updated: Regularly update Docker CE and Docker Compose using sudo apt update && sudo apt upgrade to benefit from the latest security patches and bug fixes.
• sudo and Docker Group: The docker group grants root-level privileges to interact with the Docker daemon. Members of this group can effectively execute commands as root on the host machine. Only add trusted users to the docker group.
• Firewall Configuration: For production environments, configure a firewall (e.g., UFW) to restrict access to your server. Only expose ports that are absolutely necessary (e.g., SSH, and later, the port for OpenWebUI).
• Data Persistence: Using Docker volumes for OpenWebUI data is a best practice. This isolates data from the container’s lifecycle and simplifies backups and upgrades.

This completes the foundational setup of your Ubuntu server with Docker CE and Docker Compose, preparing it for the deployment of OpenWebUI. The next step will involve deploying OpenWebUI itself, leveraging this robust Docker environment.

This chapter guides you through deploying OpenWebUI using Docker Compose and integrating it with OpenRouter.ai on an Ubuntu system. This integration supercharges your local OpenWebUI instance with advanced AI model routing and automation capabilities provided by OpenRouter.ai.Assumptions/Prerequisites:

• You have an Ubuntu 22.04 LTS or newer system.
• Docker Engine and Docker Compose are already installed and configured, as detailed in the previous chapter.
• You have basic familiarity with the Linux command line and text editors (e.g., nano, vi).
• An OpenRouter.ai account and an API key are available. You can obtain one by signing up on the OpenRouter.ai website.

Step-by-Step Deployment and Configuration:

1. Create a Project Directory for OpenWebUI:
It’s good practice to create a dedicated directory for your Docker Compose project.

mkdir -p ~/openwebui
cd ~/openwebui

2. Create the docker-compose.yaml File:
This file will define the OpenWebUI service, including environment variables for OpenRouter.ai integration, port mappings, and volume mounts for persistent data. Use your preferred text editor.

nano docker-compose.yaml

Paste the following content into the file. Replace YOUR_OPENROUTER_API_KEY with your actual OpenRouter.ai API key.

version: '3.8'

services:
  openwebui:
    image: ghcr.io/open-webui/open-webui:main
    container_name: openwebui
    restart: always
    ports:
      - "8080:8080" # Maps host port 8080 to container port 8080
    volumes:
      - ./data:/app/backend/data # Persistent storage for OpenWebUI data
    environment:
      # Core OpenWebUI environment variables
      - WEBUI_SECRET_KEY=a_long_complex_and_random_string_for_security # Change this to a strong, random key
      - WEBUI_SERVER_PORT=8080
      - WEBUI_BACKEND_URL=http://localhost:8080
      - OPENAI_API_BASE_URL=https://openrouter.ai/api/v1
      - OPENAI_API_KEY=YOUR_OPENROUTER_API_KEY # Your OpenRouter.ai API Key
      - OPENAI_MODEL_LIST="openai/gpt-4o,mistralai/mistral-7b-instruct-v0.2,google/gemma-7b-it" # Example models, customize as needed
      - OLLAMA_API_BASE_URL=""
      # Optional: Enable telemetry (set to 0 to disable)
      - WEBUI_TELEMETRY=1
    # Uncomment the resources section below to limit container resources if needed
    # deploy:
    #   resources:
    #     limits:
    #       cpus: '2'
    #       memory: 4G

Important:

• Replace YOUR_OPENROUTER_API_KEY with your actual API key from OpenRouter.ai.
• Change WEBUI_SECRET_KEY to a strong, unique value for security. Generate one using a command like head /dev/urandom | tr -dc A-Za-z0-9_ | head -c 50 ; echo ''.
• Customize OPENAI_MODEL_LIST with the specific models you want to use from OpenRouter.ai (e.g., openai/gpt-4o,mistralai/mixtral-8x7b-instruct). Refer to the OpenRouter.ai documentation for available models.

3. Start OpenWebUI with Docker Compose:
From within the ~/openwebui directory, run the following command to download the OpenWebUI image and start the container in detached mode.

docker compose up -d

4. Create an OpenWebUI Admin User:
After the container starts, you need to create an admin user through the web interface. Open your web browser and navigate to http://YOUR_SERVER_IP:8080 (replace YOUR_SERVER_IP with your Ubuntu server’s IP address).
Follow the on-screen instructions to register your first admin user.

5. Configure OpenRouter.ai within OpenWebUI:
Once logged in as an admin user:

• Navigate to the Settings (gear icon) in the bottom-left corner.
• Go to the Connections section.
• You should see an existing “OpenAI” connection. If not, click “Add Connection” and select “OpenAI”.
• Verify that the “Base URL” is set to https://openrouter.ai/api/v1 and the “API Key” field contains your OpenRouter.ai API key (it might be masked). These should be pre-filled from your docker-compose.yaml environment variables.
• Select the models you wish to expose from OpenRouter.ai within OpenWebUI. The models specified in OPENAI_MODEL_LIST will be available here.
• Click “Save” or “Update” to apply the changes.

Verification Commands + Expected Indicators:

1. Check Docker Container Status:
Ensure the OpenWebUI container is running.

docker ps --filter name=openwebui

Expected output:

CONTAINER ID   IMAGE                               STATE    PORTS                    NAMES
xxxxxxxxxxxx   ghcr.io/open-webui/open-webui:main   Up       0.0.0.0:8080->8080/tcp   openwebui

The STATE should be Up.

2. Check Docker Container Logs:
Review the logs for any errors during startup.

docker logs openwebui

Look for lines indicating successful startup, such as:

• INFO: Application startup complete.
• Messages showing models being loaded or API connections being established.

3. Access OpenWebUI in Browser:
Open your web browser and go to http://YOUR_SERVER_IP:8080. You should see the OpenWebUI interface. After logging in, you should be able to select and interact with the OpenRouter.ai models from the model dropdown menu.

Common Failure Modes + Fixes:

• Container fails to start or exits immediately:
  • Symptom: docker ps shows container with status Exited, or docker logs openwebui shows errors like “Error: bind: address already in use”.
  • Fix: Check docker logs openwebui for detailed error messages. If port 8080 is in use, change the host port mapping in docker-compose.yaml (e.g., "8081:8080") and retry docker compose up -d. Syntax errors in docker-compose.yaml will also cause this; validate your YAML.
• “API key is invalid” or “Forbidden” errors in OpenWebUI or logs:
  • Symptom: OpenWebUI displays errors when trying to chat, or logs show 401/403 HTTP status codes from OpenRouter.ai.
  • Fix: Double-check that OPENAI_API_KEY in your docker-compose.yaml precisely matches your OpenRouter.ai API key. Ensure there are no leading/trailing spaces or typos. Generate a new key on OpenRouter.ai if uncertain.
• Models not appearing in OpenWebUI dropdown:
  • Symptom: You’ve configured OPENAI_MODEL_LIST, but the models don’t show up.
  • Fix: Ensure the model names in OPENAI_MODEL_LIST are exactly as specified by OpenRouter.ai (e.g., openai/gpt-4o, not just gpt-4o). Check OpenWebUI’s Settings -> Connections to ensure the OpenAI connection is enabled and populated. Restart the container after changes to docker-compose.yaml using docker compose down && docker compose up -d.
• OpenWebUI is inaccessible (browser timeout):
  • Symptom: Web browser times out when trying to reach http://YOUR_SERVER_IP:8080.
  • Fix: Verify the container is running with docker ps. Check if a firewall (e.g., ufw) on your Ubuntu host is blocking port 8080. If ufw is active, allow the port: sudo ufw allow 8080/tcp.

Safety/Security Notes:

• API Key Management: Your OpenRouter.ai API key grants access to your account and potentially incurs costs. Never hardcode it directly into publicly accessible files or commit it to version control without proper secrets management. Using environment variables via docker-compose.yaml (with restricted file permissions) is a better approach for self-hosting than directly in code, but for production, consider Docker Secrets or external secret management tools.
• WEBUI_SECRET_KEY: This key is crucial for OpenWebUI’s internal security (e.g., session management). Always set it to a strong, random, and unique string. Keep it confidential.
• Firewall Configuration: Restrict access to OpenWebUI’s port (8080) on your server’s firewall. If you only need to access it from your local network, configure ufw to allow access only from specific IP ranges rather than globally.
• Volume Mounts: The ./data:/app/backend/data volume mount ensures persistence of your OpenWebUI data (user configurations, chat history). Secure this directory on your host system with appropriate file permissions to prevent unauthorized access.
• Image Updates: Regularly update your OpenWebUI Docker image to benefit from security fixes and new features. Stop the container, pull the latest image, then restart: docker compose pull && docker compose up -d.

By integrating OpenRouter.ai, OpenWebUI gains a powerful backend for AI model routing. OpenRouter.ai acts as a unified API endpoint, allowing you to seamlessly switch between various leading AI models (e.g., GPT-4o, Mixtral, Llama, Gemma) without changing your OpenWebUI configuration for each model. This enhances flexibility, enables cost-optimization by choosing the most appropriate model for a task, and simplifies managing multiple AI services through a single interface within your self-hosted OpenWebUI instance. It provides routing logic that intelligent AI automation platforms demand, ensuring that your OpenWebUI deployment is not just a chat interface, but a versatile AI orchestration hub.

• • Assumptions/Prerequisites
    • You have successfully deployed OpenWebUI with Docker on Ubuntu, integrated with OpenRouter.ai, as detailed in the previous chapters.
    • You have basic familiarity with Linux command-line operations, Docker, and `docker-compose`.
    • You have root or `sudo` privileges on your Ubuntu server.
    • You understand the importance of regular backups.
  • Routine Updates for OpenWebUI, Docker, and OpenRouter.ai Components

Maintaining security and functionality requires regular updates. This involves updating the underlying Ubuntu operating system, Docker itself, the OpenWebUI Docker image, and ensuring your OpenRouter.ai API keys are valid.

• • 1. Update Ubuntu System Packages

This keeps your base system secure and stable.

sudo apt update
sudo apt upgrade -y
sudo apt autoremove -y

• • 1. Update Docker Engine and Docker Compose (if installed separately)

For Docker Desktop or installations via `apt` from Docker’s official repository, `sudo apt upgrade -y` usually handles this. If you installed `docker-compose` as a standalone binary, check for new versions.

# Check Docker version
docker --version

# Or for docker-compose (if standalone)
docker-compose --version

# To update docker-compose standalone (example for Linux x86_64)
sudo curl -L "https://github.com/docker/compose/releases/download/v2.24.1/docker-compose-$(uname -s)-$(uname -m)" -o /usr/local/bin/docker-compose
sudo chmod +x /usr/local/bin/docker-compose

Note: Adjust the `v2.24.1` version in the `docker-compose` update command to the latest stable release from the official Docker Compose GitHub page.

• • 1. Update OpenWebUI Docker Container

The recommended way to update OpenWebUI is to pull the latest image and recreate your container using `docker-compose`.

cd /path/to/your/openwebui-docker-compose-directory
docker-compose down
docker-compose pull
docker-compose up -d --remove-orphans

Verification: After executing these commands, navigate to `http://your_server_ip:8080` (or your configured port). Check the OpenWebUI dashboard or settings for version information. You should see a newer version number reflected.

• • 1. OpenRouter.ai API Key Management

Ensure your API keys remain active and are rotated periodically for security best practices. Log into the OpenRouter.ai dashboard to manage your keys.

• • Troubleshooting Common Issues
    • OpenWebUI container fails to start:
      • • Fix: Check Docker container logs for errors.

      docker logs openwebui

      • Common Problem: Port conflicts, database errors, or incorrect environment variables.
      • Resolution: Ensure port `8080` (or specified) is free. If database-related, check volume permissions or try removing and recreating the volume (caveat: this will erase historical data). Verify `docker-compose.yaml` environment variables for `OPENROUTER_API_KEY` and other settings.
    • OpenWebUI is unreachable:
      • • Fix: Verify the container is running and check firewall rules.

      docker ps -a
      sudo ufw status

      • Common Problem: Container stopped, or firewall blocking access.
      • Resolution: Start the container if stopped (`docker start openwebui`). Open port `8080` (or your configured port) in your firewall (`sudo ufw allow 8080/tcp`).
    • OpenRouter.ai models are not accessible in OpenWebUI:
      • Fix: Check API key validity and network connectivity.
      • Common Problem: Incorrect or expired API key, or networking issues preventing OpenWebUI from reaching OpenRouter.ai.
      • Resolution: Double-check `OPENROUTER_API_KEY` in your `docker-compose.yaml`. Ensure your server has outbound internet access. Test API key directly with `curl` from the server if possible.
  • Optimization Techniques for Resource Allocation

For AI automation, efficient resource usage is crucial. Docker allows controlling CPU and memory for containers.

• • 1. Memory Limits

Prevent OpenWebUI from consuming all available RAM, especially if you run other services.

# Add to your docker-compose.yaml in the openwebui service section:
services:
  openwebui:
    image: ghcr.io/open-webui/open-webui:main
    ... (other configurations)
    deploy:
      resources:
        limits:
          memory: 4g  # Example: Limit to 4GB RAM
        reservations:
          memory: 2g  # Example: Reserve 2GB RAM

• • 1. CPU Limits

Control the CPU share for the OpenWebUI container. This can be defined as a quota or shares.

# Add to your docker-compose.yaml in the openwebui service section:
services:
  openwebui:
    image: ghcr.io/open-webui/open-webui:main
    ... (other configurations)
    deploy:
      resources:
        limits:
          cpus: '2.0'  # Example: Limit to 2 CPU cores
        reservations:
          cpus: '1.0'  # Example: Reserve 1 CPU core

Note: After modifying `docker-compose.yaml`, run `docker-compose up -d` to apply changes. Monitor disk I/O, network usage, CPU, and RAM with tools like `htop`, ` glances`, or `docker stats` to fine-tune these values.

• Safety/Security Notes
  • Regular Backups: Regularly back up your OpenWebUI data volumes, especially the database.
  • Firewall: Keep unnecessary ports closed. Only expose OpenWebUI’s port if external access is strictly required, ideally behind a reverse proxy with SSL.
  • API Key Security: Never hardcode API keys directly in publicly accessible files. Use environment variables as shown in previous chapters. Rotate API keys periodically.
  • Principle of Least Privilege: Run Docker and OpenWebUI with the minimum necessary privileges.
  • Keep Software Updated: Regularly update your OS, Docker, and OpenWebUI to patch security vulnerabilities.
  • Docker Security Best Practices: Review Docker security guides for container hardening.
• Summary of Benefits, Community, and Future-Proofing
  • Benefits of Self-Hosting: Self-hosting OpenWebUI with OpenRouter.ai provides unparalleled control over your data, customizable environments, and full ownership of your AI workflows. This open-source approach fosters transparency and reduces vendor lock-in, crucial for sensitive AI automation tasks.
  • Flexibility and Control: The Dockerized setup offers flexibility in deployment, allowing easy migrations and scaling. Integration with OpenRouter.ai gives you dynamic access to a wide range of cutting-edge AI models without being tied to a single provider.
  • Community Engagement: OpenWebUI thrives on its active community. Engage with the project on GitHub, participate in discussions, report bugs, and contribute. This collaborative environment ensures continuous improvement and support.
  • Upgrade Paths and Future-Proofing: The modular design of OpenWebUI and Docker makes it adaptable to future AI advancements. As new models emerge or OpenWebUI adds features, updating your setup is straightforward. The open-source nature means you’re not reliant on a single company’s roadmap, allowing you to integrate with evolving AI technologies as needed. This approach future-proofs your AI automation platform against rapid changes in the AI landscape.