# A Practical Guide to Running Open WebUI with Ace Data Cloud

If you want a private, team-friendly AI chat interface but do not want to wire every model provider separately, Open WebUI plus an OpenAI-compatible endpoint is one of the fastest setups to get working.

![Open WebUI connected to Ace Data Cloud](https://platform2.cdn.acedata.cloud/gpt-image/c3059007-8ade-4ef3-b1f6-98793a97734d_0.png)

Open WebUI is useful because it gives you the parts many small teams eventually need: accounts, admin controls, chat history, model selection, and a knowledge-base workflow. The important trick is that it can talk to any OpenAI-compatible server. In this guide, we will connect it to Ace Data Cloud using the same `/v1` style endpoint that OpenAI clients expect.

This is not a complex integration. Most of the setup comes down to three values: a base URL, an API token, and a persistent data volume.

## What you are building

The goal is to run Open WebUI in Docker and point it at Ace Data Cloud as the model backend.

The key values are:

- Base URL: `https://api.acedata.cloud/v1`
- Chat endpoint used under the hood: `POST /v1/chat/completions`
- Model discovery endpoint used by Open WebUI: `/v1/models`
- API authentication: `Authorization: Bearer {token}`
- Example chat model from the documentation: `gpt-5`
- Example embedding model for RAG: `text-embedding-3-large`

The detail that matters most is the base URL path. Open WebUI appends API paths such as `/chat/completions` to the base URL you provide. So `https://api.acedata.cloud/v1` becomes `https://api.acedata.cloud/v1/chat/completions`, which is correct.

A common mistake is to use `https://api.acedata.cloud/openai/v1`. The document notes that this becomes `https://api.acedata.cloud/openai/v1/chat/completions`, which returns a 404 because `/openai` does not have `/v1` after it.

## Start Open WebUI with Docker

If you are testing on a server or a local machine with Docker, the quickest path is a single container command:

```bash
docker run -d \
  --name open-webui \
  -p 3000:8080 \
  -e WEBUI_SECRET_KEY=$(openssl rand -base64 32) \
  -e OPENAI_API_BASE_URL=https://api.acedata.cloud/v1 \
  -e OPENAI_API_KEY={token} \
  -v open-webui:/app/backend/data \
  ghcr.io/open-webui/open-webui:main
```

Replace `{token}` with your Ace Data Cloud API token. Keep the token out of screenshots, repos, and shared shell history whenever possible.

A few choices in this command are worth calling out:

- `OPENAI_API_BASE_URL` must end with `/v1` for this configuration.
- `OPENAI_API_KEY` is the token Open WebUI will use when calling the model API.
- `WEBUI_SECRET_KEY` protects the web session and should be stable for a real deployment.
- `-v open-webui:/app/backend/data` keeps users, settings, and conversation data across container restarts.

After the container starts, open `http://your-server-IP:3000`. The first registered account becomes the administrator, so do that initial signup intentionally.

## Verify the endpoint before debugging the UI

When something fails in a UI, I like to test the lower-level API first. It removes a lot of guesswork.

Use this curl command to check whether your token and base URL are working:

```bash
curl -X POST 'https://api.acedata.cloud/v1/chat/completions' \
  -H 'Authorization: Bearer {token}' \
  -H 'Content-Type: application/json' \
  -d '{
    "model": "gpt-5",
    "messages": [{"role": "user", "content": "ping"}]
  }'
```

A successful response should be an OpenAI-compatible `chat.completion` object. If you receive `HTTP 403 used_up`, that means the token is valid but the account does not currently have enough balance for the request. If you receive a 404, check the base URL path first.

Once curl works, go back to Open WebUI and open **Admin Panel → Settings → Connections**. Use **Verify Connection** to confirm the provider. In **Settings → Models**, you can filter and pin the models your team actually uses.

## Add a knowledge base without losing control of documents

Open WebUI also has a knowledge-base workflow for RAG. According to the integration document, Open WebUI uses ChromaDB by default for vectors, and you can set the embedding model to `text-embedding-3-large` through the OpenAI provider path.

The practical benefit is simple: your original documents remain on your own Open WebUI server, while only the matched text segments are sent to the model during retrieval. For an internal team wiki, support notes, or engineering runbooks, that separation is often easier to reason about than uploading everything into a hosted chatbot product.

If you expose the instance to other people, spend a few minutes on access control. In **Admin Panel → Users**, the document recommends setting the default user role to `pending`, so new users must be reviewed before they can use the system. That small setting can prevent accidental quota usage from open registration.

If you put nginx in front of Open WebUI, the same document also recommends:

```nginx
proxy_buffering off;
client_max_body_size 100M;
```

That helps with streaming responses and larger document uploads.

## Troubleshooting checklist

If the setup does not work on the first try, check these in order:

1. The base URL is exactly `https://api.acedata.cloud/v1`.
2. The token is present in `OPENAI_API_KEY` and has not been copied with extra spaces.
3. The direct curl request returns a `chat.completion` object.
4. Open WebUI can call `/models` from the Connections settings page.
5. The Docker volume is mounted if data disappears after restart.
6. For document chat, the embedding model is set to `text-embedding-3-large`.

Most failed setups I have seen come from path confusion rather than model configuration. Get the base URL right, verify with curl, and only then tune the Open WebUI settings.

If you want to compare this against the original integration notes, the Ace Data Cloud documentation for this setup is here: https://platform.acedata.cloud/documents/development_open_webui