Deploy Open WebUI
Your own AI chat interface for any OpenAI-compatible provider, with App storage for chats and uploads.
Open WebUI is a chat interface for language models: conversations, document upload and search, multiple users, an admin panel. This template runs the maintained upstream image on Dockhold and adds a start script that wires it to Dockhold's port, App storage, your admin account and your model provider. Deploy it as it is, or use it as the starting point for your own copy.
1. Open the deploy link
Start from theopen-webui-starter template. Open thedeploy linkand sign in if asked.
2. Size the app and turn on App storage
Under App size, start at 2 GB. This app needs a paid plan: its image is far larger than the free plan allows, and it runs a document-search model in memory. Grow the app as your usage grows. Under App storage, turn it on and pick10 GB. Open WebUI keeps its database, uploads and session key on that storage, so without it the next restart would start empty.
3. Add your secrets
Under Environment, in the Secrets list, click New secret three times to store the three values, tick each one, and set its Env var name to the name Open WebUI expects. Give the entries names that belong to this app, for example open-webui-admin-email, because secrets are shared across your apps by name and two apps that share an entry would share a password.
| Secret (your name) | Env var name | Value |
|---|---|---|
open-webui-admin-email | WEBUI_ADMIN_EMAIL | The email you will sign in with |
open-webui-admin-password | WEBUI_ADMIN_PASSWORD | 8 to 72 characters |
open-webui-openai-key | OPENAI_API_KEY | An API key from OpenAI, or from another OpenAI-compatible provider |
To use a provider other than OpenAI, also add a plain variableOPENAI_API_BASE_URL with the provider's address:https://api.anthropic.com/v1 for Anthropic's Claude models or https://openrouter.ai/api/v1 for OpenRouter. Any provider that speaks the OpenAI API works the same way.
4. Deploy
Click Deploy and wait until the app shows as running. The first start takes about a minute: the app is started once on an internal address to verify the admin account before the public address opens, so nobody else can claim it. Later starts are about half that.
5. Sign in and start chatting
Open your app's URL, sign in with that email and password, pick a model at the top of the chat, and send a message.
If the app refuses to start, its page shows one line saying what is missing. App storage is on the app's Size tab; secrets are attached on its Variables tab and their values are edited under Settings, then Secrets. Fix it and click Restart.
Two ways to use it
Run Open WebUI. Deploy this repository as it is. You get a hosted Open WebUI with an admin panel, and you manage users, models and connections in that panel. The app stays on the version it was built with; Restart starts the same build again. To move to a newer Open WebUI, switch to the Develop path below.
Develop your copy. Click Use this templateon GitHub to make your own copy, connect that repository in Dockhold, and deploy it. From then on every push builds and starts the new version. Upgrades happen on this path.
Only the second path gives you push-to-deploy and upgrades. The first path never reads your GitHub account.
What it runs
Chat goes to the provider you chose. Your prompts, and the relevant parts of documents you upload, are sent to that provider. Document search runs inside the app: a small embedding model, bundled with the image, indexes uploaded files so the chat can quote from them. There is no local chat model and no Ollama in this template.
Settings Open WebUI owns after the first start
Open WebUI reads the settings below from variables on itsfirst start, stores them in its database on App storage, and from then on the admin panel owns them. Changing the variable in Dockhold afterwards does nothing on an existing installation.
| Setting | Seeded from | Owned after the first start by |
|---|---|---|
| Admin email and password | WEBUI_ADMIN_EMAIL, WEBUI_ADMIN_PASSWORD | Open WebUI (Settings, then Account). The variables are ignored once any account exists. |
| Provider key and address | OPENAI_API_KEY, OPENAI_API_BASE_URL | Open WebUI (Admin, then Settings, then Connections). Rotating the key in Dockhold does not change the running app; rotate it in Connections. |
| Signup | closed | Open WebUI (Admin, then Settings). Closed by the admin bootstrap; invite users from Admin, then Users. |
| Public URL | the app's Dockhold address | Open WebUI (Admin, then Settings, then General). After connecting a custom domain in Dockhold, set it there. |
| Session lifetime | 7 days | Open WebUI (Admin, then Settings, then General) |
| Session key | the file on App storage | the file (see "Sessions and the session key" below) |
Sessions and the session key
A login lasts seven days. Changing the admin password does not sign out sessions that already exist; they close on their own within that week. ARestart does not sign anyone out either.
Open WebUI signs every login with one key, kept in a file on App storage. That file is part of your backup set. Binding a secret namedWEBUI_SECRET_KEY is a recovery action, not a setting: it wins over the file, and binding, changing or unbinding it signs everyone out. An installation that started with the key bound this way has no key file at all.
Keep the admin password somewhere safe, or create a second admin in Admin, then Users. Open WebUI has no self-service password reset without an email provider, so a lost password on an installation with a single admin means a fresh installation.
Backups and upgrading
Your backup set is all of App storage, including the session key file, plus the three secrets. Admin, then Settings, then Database, then Export Database in the admin panel downloads a copy of the database file: users, chats and settings. Uploaded documents, the search index and the key file live only on App storage, so the storage contents are the complete set. Take a copy before you upgrade and on a schedule.
The database file holds your provider key in plain text, and any single sign-on client secrets you add later. Store the file and its export the way you store the key itself.
Upgrades happen on the Develop path: take a backup first, move your copy to a newer version, and push. If the app comes back on the previous version after an upgrade, do not keep using it; restore the backup and retry. An app on the Run path stays on the version it was built with.
Troubleshooting
- App refuses to start, asks for App storage: Open WebUI keeps its database and uploads in a folder that needs to survive a restart. Turn on App storage on the app's Size tab; the app restarts on its own.
- App refuses to start, names a missing secret:
WEBUI_ADMIN_EMAIL,WEBUI_ADMIN_PASSWORDorOPENAI_API_KEYis not set. Add the missing ones as secrets on the app's Variables tab and restart. - App refuses to start, asks you to turn off the managed database: this version of the template keeps Open WebUI's data on App storage and does not use the managed database. Turn the managed database off for this app and restart.
- App refuses to start, says the admin account could not be created: the bound
WEBUI_ADMIN_EMAILandWEBUI_ADMIN_PASSWORDdo not match an existing admin, or Open WebUI could not create one from them. Check the values on the app's Variables tab and restart.
License: Open WebUI is distributed under theOpen WebUI License, the BSD 3-Clause license plus one clause: once an installation has had more than fifty users in a rolling thirty-day period, you may not alter or remove the "Open WebUI" name, logo or other branding, unless you have upstream's written permission. This template does not change the branding. Whether your use fits the license is your responsibility as the operator.