A container can be replaced without losing the application data stored outside it. For Open WebUI, Docker Compose keeps the service settings and persistent storage together so the web interface can run from a repeatable project.

The official Open WebUI image provides the web application, while a separate model provider supplies chat responses. A fresh installation opens a welcome page before any administrator account or model connection exists.

The local-only port binding keeps the initial setup off the network. The named volume retains accounts, chats, settings, and uploads across container replacement; the secret key also needs to stay unchanged to preserve sessions. Docker with the Compose plugin and OpenSSL must already be available.

Steps to run Open WebUI with Docker Compose:

  1. Create a new project directory for Open WebUI.
    $ mkdir ~/open-webui

    A separate directory avoids overwriting an existing installation's environment or storage settings.

  2. Change into the project directory.
    $ cd ~/open-webui
  3. Create an owner-only .env file.
    $ install -m 600 /dev/null .env
  4. Write a fresh secret directly into the .env file.
    $ printf 'COMPOSE_PROJECT_NAME=open-webui\nOPEN_WEBUI_PORT=3000\nWEBUI_SECRET_KEY=%s\n' "$(openssl rand -hex 32)" > .env

    The file contains an application secret and retains its owner-only permissions. Do not commit it to version control or share it. Changing the key later can invalidate sessions and make encrypted tokens unreadable; a protected backup of the original file provides recovery.

  5. Create compose.yaml with the official release image and persistent volume.
    ~/open-webui/compose.yaml
    services:
      open-webui:
        image: ghcr.io/open-webui/open-webui:v0.12.4
        restart: unless-stopped
        healthcheck:
          start_period: 5m
        ports:
          - "127.0.0.1:${OPEN_WEBUI_PORT:-3000}:8080"
        extra_hosts:
          - "host.docker.internal:host-gateway"
        environment:
          WEBUI_SECRET_KEY: "${WEBUI_SECRET_KEY:?set WEBUI_SECRET_KEY in .env}"
        volumes:
          - open-webui:/app/backend/data
    
    volumes:
      open-webui:

    The extra_hosts entry lets Linux Docker Engine resolve host.docker.internal for a later connection to a model server on the host. It does not install a model server. The port is reachable only on this computer; protected remote access is a separate setup.

    The first account on a fresh installation becomes its administrator. The local-only binding prevents remote visitors from claiming that account during initial setup. Removing the 127.0.0.1: prefix would publish the port on other host interfaces.

  6. Validate the Compose configuration without printing the secret.
    $ docker compose config --quiet

    No output with exit status 0 means the configuration is valid. Plain docker compose config can print the resolved secret.

  7. Pull the selected Open WebUI release.
    $ docker compose pull
  8. Start the service with its healthcheck enabled.
    $ docker compose up -d --wait

    The image supplies the healthcheck command. The five-minute startup grace allows the initial embedding-model download to finish before failed probes count toward an unhealthy state. The –wait option returns after the service becomes healthy; an error or timeout means startup needs attention before continuing.

  9. Check the running service and local port binding.
    $ docker compose ps

    The STATUS column should include (healthy), and PORTS should show 127.0.0.1:3000->8080/tcp.

  10. Confirm that the web application answers its health endpoint.
    $ curl -fsS http://127.0.0.1:3000/health
    {"status":true}
  11. Recreate the container with its named data volume retained.

    Recreating the container briefly interrupts the service. Compose reattaches open-webui_open-webui at /app/backend/data.

    $ docker compose up -d --force-recreate --wait

    Do not run docker compose down -v unless you intend to delete the stored accounts, chats, settings, and uploads. Backups are needed before updates, migrations, or host rebuilds.

  12. Open http://127.0.0.1:3000 in a browser on the Docker host.

    The Welcome to your AI home. page with its Get started button confirms the recreated service is accessible. Administrator creation and model-provider connection can follow separately.

Share this guide