---
title: "Deploy Hugging Face Chat UI + MongoDB (Password Protected)"
description: "Open source HuggingChat interface with MongoDB behind a password gateway"
category: "AI/ML"
url: https://railway.com/deploy/hugging-face-chat-ui-mongodb-password-pr
---

# Deploy Hugging Face Chat UI + MongoDB (Password Protected)

Open source HuggingChat interface with MongoDB behind a password gateway

**[Deploy Hugging Face Chat UI + MongoDB (Password Protected) on Railway](https://railway.com/template/hugging-face-chat-ui-mongodb-password-pr)**

Machine-readable deploy manifest (JSON, validated by TemplateCI): https://railway.com/deploy/hugging-face-chat-ui-mongodb-password-pr/manifest.json

- **Creator:** Protemplate
- **Category:** AI/ML
- **Total deploys:** 2

## Template content

### MongoDB https://avatars.githubusercontent.com/u/45120?v=4

- **Image:** mongo:8.0.34
- **Start command:** `docker-entrypoint.sh mongod --ipv6 --bind_ip_all --wiredTigerCacheSizeGB 0.25 --setParameter diagnosticDataCollectionEnabled=false`

### chat-ui-gateway https://raw.githubusercontent.com/huggingface/chat-ui/90b4c8625698678092808ef4e6567eb3547e11fc/static/chatui/icon-256x256.png

- **Image:** caddy:2.11-alpine
- **Start command:** `sh -c 'echo IyBTdGFydCBjb21tYW5kIG9mIHRoZSBjaGF0LXVpLWdhdGV3YXkgc2VydmljZSAoY2FkZHk6Mi4xMS1hbHBpbmUpLgojIEVtYmVkZGVkIGFzIGJhc2U2NCBpbiBzZXJpYWxpemVkLWNvbmZpZy5qc29uOyByZWdlbmVyYXRlIHdpdGg6CiMgICBiYXNlNjQgPCBzY3JpcHRzL2dhdGV3YXktc3RhcnQuc2ggfCB0ciAtZCAnXG4nCiMgQmFzaWMgYXV0aCBpbiBmcm9udCBvZiB0aGUgcHJpdmF0ZSBDaGF0IFVJIHNlcnZpY2UuIGJjcnlwdCBjb3N0IDEwIGtlZXBzIHRoZQojIHBlciByZXF1ZXN0IGNoZWNrIGNoZWFwICh0aGUgcGFzc3dvcmQgaXMgYSBnZW5lcmF0ZWQgMjQgY2hhcmFjdGVyIHNlY3JldCkuCnNldCAtZQo6ICIke1BPUlQ6P1BPUlQgaXMgcmVxdWlyZWR9Igo6ICIke1VJX1VTRVJOQU1FOj9VSV9VU0VSTkFNRSBpcyByZXF1aXJlZH0iCjogIiR7VUlfUEFTU1dPUkQ6P1VJX1BBU1NXT1JEIGlzIHJlcXVpcmVkfSIKOiAiJHtVUFNUUkVBTTo/VVBTVFJFQU0gaXMgcmVxdWlyZWR9IgpIQVNIPSIkKGNhZGR5IGhhc2gtcGFzc3dvcmQgLS1hbGdvcml0aG0gYmNyeXB0IC0tYmNyeXB0LWNvc3QgMTAgLS1wbGFpbnRleHQgIiRVSV9QQVNTV09SRCIpIgpwcmludGYgJyVzXG4nIFwKICAneycgXAogICcgIGF1dG9faHR0cHMgb2ZmJyBcCiAgJyAgYWRtaW4gb2ZmJyBcCiAgJyAgc2VydmVycyB7JyBcCiAgJyAgICBwcm90b2NvbHMgaDEgaDJjJyBcCiAgJyAgfScgXAogICd9JyBcCiAgIjokUE9SVCB7IiBcCiAgJyAgaGFuZGxlIC9nYXRld2F5LWhlYWx0aCB7JyBcCiAgJyAgICByZXNwb25kICJvayIgMjAwJyBcCiAgJyAgfScgXAogICcgIGhhbmRsZSB7JyBcCiAgJyAgICBiYXNpY19hdXRoIHsnIFwKICAiICAgICAgJFVJX1VTRVJOQU1FICRIQVNIIiBcCiAgJyAgICB9JyBcCiAgIiAgICByZXZlcnNlX3Byb3h5ICRVUFNUUkVBTSB7IiBcCiAgJyAgICAgIGZsdXNoX2ludGVydmFsIC0xJyBcCiAgJyAgICAgIGhlYWRlcl91cCAtQXV0aG9yaXphdGlvbicgXAogICcgICAgfScgXAogICcgIH0nIFwKICAnfScgPiAvZXRjL2NhZGR5L0NhZGR5ZmlsZQpleGVjIGNhZGR5IHJ1biAtLWNvbmZpZyAvZXRjL2NhZGR5L0NhZGR5ZmlsZSAtLWFkYXB0ZXIgY2FkZHlmaWxlCg== | base64 -d > /tmp/start.sh && exec sh /tmp/start.sh'`
- **Health check:** /gateway-health
- **Public domain:** Yes

### Chat UI https://raw.githubusercontent.com/huggingface/chat-ui/90b4c8625698678092808ef4e6567eb3547e11fc/static/chatui/icon-256x256.png

- **Image:** ghcr.io/huggingface/chat-ui:sha-90b4c86
- **Health check:** /healthcheck

## Documentation

# Deploy and Host Hugging Face Chat UI on Railway

Chat UI is the open source app that powers HuggingChat. It is a fast SvelteKit chat interface for any OpenAI-compatible API, with conversation history, file attachments, shareable conversations and MCP tool support. Bring a Hugging Face token, an OpenAI key, or point it at your own LiteLLM or Ollama endpoint.

## About Hosting Hugging Face Chat UI

Hosting Chat UI means running the app next to MongoDB, which stores conversations, settings, sessions and uploaded files. This template uses the official `ghcr.io/huggingface/chat-ui` image pinned to a fixed build, a dedicated MongoDB service with its own volume and generated credentials, and a small Caddy gateway.

The gateway matters: Chat UI has no login of its own unless you connect an OpenID Connect provider, so an exposed instance lets anyone chat on your API key. Here the Chat UI service has no public domain. The gateway is the only public service, asks for a generated username and password, and streams model responses through without buffering.

## What's Included

- **Chat UI** (`ghcr.io/huggingface/chat-ui:sha-90b4c86`): the app, private, healthcheck on `/healthcheck`
- **MongoDB** (`mongo:8.0.34`): private, authentication on, one volume at `/data/db`
- **chat-ui-gateway** (`caddy:2.11-alpine`): public, basic auth with a generated password

## First Steps After Deploy

1. Open the `chat-ui-gateway` service and copy `UI_USERNAME` and `UI_PASSWORD` from its Variables tab.
2. Open the gateway's public domain and sign in with those values.
3. Set `OPENAI_API_KEY` on the Chat UI service. With the default Hugging Face router this is a Hugging Face access token that has the Inference Providers permission. The app boots and lists models without it, but messages fail until it is set.
4. Optional: point `OPENAI_BASE_URL` at another OpenAI-compatible provider. Set the URL and the key in the same change, because Chat UI loads the model list at startup and exits if that request is refused.

## Common Use Cases

- **Private ChatGPT style interface** for a team, on models you choose
- **Front end for an LLM gateway** such as LiteLLM, Bifrost or OpenRouter
- **Chat with open models** through Hugging Face Inference Providers
- **MCP tools in chat**: connect MCP servers and let tool capable models call them

## Key Environment Variables

```env
# Chat UI
OPENAI_BASE_URL=https://router.huggingface.co/v1
OPENAI_API_KEY=                 # your provider key, needed to chat
MONGODB_URL=${{MongoDB.MONGO_URL}}
PUBLIC_ORIGIN=https://${{chat-ui-gateway.RAILWAY_PUBLIC_DOMAIN}}
MCP_OAUTH_ENCRYPTION_KEY=${{secret(48)}}
PORT=3000
HOST=::

# MongoDB
MONGO_INITDB_ROOT_USERNAME=chatui
MONGO_INITDB_ROOT_PASSWORD=${{secret(32)}}

# chat-ui-gateway
UI_USERNAME=admin
UI_PASSWORD=${{secret(24)}}
```

Optional on Chat UI: `TASK_MODEL` (model used for titles), `MODELS` (per model overrides), `MCP_SERVERS` (default MCP servers), and `OPENID_CLIENT_ID`, `OPENID_CLIENT_SECRET`, `OPENID_PROVIDER_URL`, `OPENID_SCOPES` for per user login through OpenID Connect.

## Dependencies for Hugging Face Chat UI Hosting

- **MongoDB**: required, included
- **An OpenAI-compatible provider key**: optional at boot, required to get answers
- **OpenID Connect provider**: optional, for per user accounts

### Deployment Dependencies

- [Chat UI documentation](https://huggingface.co/docs/chat-ui)
- [Chat UI GitHub repository](https://github.com/huggingface/chat-ui)
- [Hugging Face access tokens](https://huggingface.co/settings/tokens)

### Implementation Details

Without OpenID Connect, each browser gets its own anonymous session, kept in a cookie for two weeks. Conversations belong to that session, so a different browser starts with an empty history. Configure OpenID Connect if several people need their own accounts.

MongoDB's root password is applied on the first boot only. A custom domain belongs on the `chat-ui-gateway` service, and `PUBLIC_ORIGIN` on Chat UI should then be updated to match.

## Why Deploy Hugging Face Chat UI on Railway?

Railway is a singular platform to deploy your infrastructure stack. Railway will host your infrastructure so you don't have to deal with configuration, while allowing you to vertically and horizontally scale it.

By deploying Hugging Face Chat UI on Railway, you get the HuggingChat interface with a private MongoDB, generated credentials, a password gateway, health checks and managed SSL, ready for the provider key of your choice.


## Similar templates

- [Chat Chat](https://railway.com/deploy/-WWW5r) — Chat Chat, your own unified chat and search to AI platform.
- [Weaviate](https://railway.com/deploy/weaviate-1) — Vector database with hybrid search and an API key-protected API
- [Möbius Personal AI OS](https://railway.com/deploy/mobius-v01-personal-ai-os) — Self-hosted AI agent that builds and runs apps for you, with memory.

Open this page in a browser: https://railway.com/deploy/hugging-face-chat-ui-mongodb-password-pr