A first Open WebUI instance often starts as one Docker container on a workstation or small server before a larger Compose setup is needed. With Docker already installed and running, the official image can serve Open WebUI through a local browser without a separate Python installation.

The official image stores users, chats, settings, uploads, and runtime data under /app/backend/data. Mounting a named Docker volume at that path keeps the data outside the disposable container layer so the container can be restarted or recreated without erasing the instance.

The local web address is accessible from the Docker host, so the first administrator account can be created before remote access is considered. Docker Engine 28.0.0 or newer is required for the loopback-only network boundary used here. A protected env file holds WEBUI_SECRET_KEY outside the container command; changing that key during a later recreation can invalidate sessions and encrypted integration data.

Steps to run Open WebUI with Docker:

  1. Create a local directory for the Open WebUI env file.
    $ mkdir -p ~/open-webui
  2. Change into the directory.
    $ cd ~/open-webui
  3. Restrict permissions for files created in the current shell.
    $ umask 077
  4. Enable overwrite protection in the current shell.
    $ set -C

    The no-clobber option prevents a later redirection from replacing an existing env file and losing its secret.

  5. Create the env file with a generated WEBUI_SECRET_KEY.
    $ printf 'WEBUI_SECRET_KEY=%s\n' "$(openssl rand -hex 32)" > open-webui.env

    The file is readable only by its owner, and the secret is not printed in the terminal. The same file and named volume are needed when recreating this installation.
    Related: How to set WEBUI_SECRET_KEY in Open WebUI

  6. Pull the official Open WebUI release image.
    $ docker pull ghcr.io/open-webui/open-webui:v0.12.4
    v0.12.4: Pulling from open-webui/open-webui
    Digest: sha256:a5b9e403d19154796850679c8c5d1295301cee954be8b84ddd62af92426558f7
    Status: Image is up to date for ghcr.io/open-webui/open-webui:v0.12.4
    ghcr.io/open-webui/open-webui:v0.12.4

    This release was tested as version 0.12.4. A first pull also prints layer-download progress. A version tag avoids following the moving main tag during a later recreation.

  7. Start Open WebUI on the host's loopback interface.
    $ docker run --detach \
      --name open-webui \
      --publish 127.0.0.1:3000:8080 \
      --add-host=host.docker.internal:host-gateway \
      --env-file open-webui.env \
      --mount type=volume,source=open-webui,target=/app/backend/data \
      --restart unless-stopped \
      ghcr.io/open-webui/open-webui:v0.12.4

    The command prints the new container ID. The mapping exposes container port 8080 only at 127.0.0.1:3000 on the host. Omitting 127.0.0.1 would publish it on all host interfaces, potentially letting another person claim the first administrator account. The host-gateway mapping lets Linux Docker Engine containers reach host services through host.docker.internal; Docker Desktop already provides that name. The restart policy restarts the container with Docker unless it was explicitly stopped.

  8. Check the container status.
    $ docker ps --filter 'name=^/open-webui$' --format 'table {{.Names}}\t{{.Status}}\t{{.Ports}}'

    The row should show open-webui, Up with (healthy), and 127.0.0.1:3000→8080/tcp. Initial startup can take several minutes while bundled components initialize or download models. If STATUS still shows (health: starting), the service is not ready yet. An exited or unhealthy container needs diagnosis with docker logs open-webui.
    Related: How to view Open WebUI Docker logs

  9. Confirm the data volume is mounted inside the container.
    $ docker inspect --format '{{range .Mounts}}{{.Type}} {{.Name}} -> {{.Destination}}{{end}}' open-webui
    volume open-webui -> /app/backend/data

    Removing the open-webui volume deletes the instance data. A later container recreation must retain this volume and open-webui.env.
    Related: How to update Open WebUI in Docker

  10. Request the Open WebUI health endpoint.
    $ curl --fail --silent --show-error http://127.0.0.1:3000/health
    {"status":true}

    The response confirms the application is serving requests. Connection errors or an HTTP error mean startup has not completed successfully.

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

    A new instance displays Welcome to your AI home. with a Get started button. The first account created becomes the administrator. A model provider is configured separately before chat can return model responses.
    Related: How to connect Ollama to Open WebUI
    Related: How to connect an OpenAI-compatible provider to Open WebUI

Share this guide