ageerle/ruoyi-web: the user-facing Vue 3 frontend for a RuoYi-AI stack

What ruoyi-web actually is, and who it is built for

This repository is a frontend, not a platform. The README describes it as the "RuoYi-AI user frontend for AI conversations, agent interactions, and knowledge-base Q&A", and the page links out to two sibling repositories: the backend service (ageerle/ruoyi-ai) and the admin panel (ageerle/ruoyi-admin). That split defines the audience. You are meant to arrive here already running, or planning to run, the RuoYi-AI backend. A team that wants a chat surface with retrieval over uploaded documents, plus agent-style interactions, gets one without writing the Vue layer themselves.

The people this suits are teams standardising on the RuoYi ecosystem. RuoYi is a long-running Chinese admin framework family, and the related searches around it (RuoYi-Vue, RuoYi Plus, RuoYi admin) show that the surrounding vocabulary is already familiar to that audience. If your organisation already runs RuoYi-based services, this frontend slots into a stack you understand. If you do not, you are adopting three repositories at once, and the frontend is the least self-sufficient of the three.

Vue 3, TypeScript, Pinia and a nginx proxy in front of the API

The declared stack is Vue 3 with TypeScript, Ant Design Vue for components, Pinia for state and Vite as the build tool. The package.json tells a slightly different story: it lists element-plus, vue-element-plus-x and @element-plus/icons-vue as dependencies, and the package description calls itself a "ruoyi-web open-source PC AI template". The README's Ant Design Vue line and the dependency list disagree, so treat the installed packages, not the prose, as the source of truth. That discrepancy is worth knowing before you plan a theme or component override.

The deployment mechanism is the more interesting part. The Dockerfile.frontend build is paired with nginx.conf, and the compose file passes a single environment variable, UPSTREAM_URL, described in the file as the backend API address proxied at runtime through nginx. That means the API host is not baked into the JavaScript bundle. You can build one image and point it at different backends by changing one value, which is the right call for a frontend that has to ship against staging and production. The compose comment in the repository gives http://host.docker.internal:26039 as the standalone value and notes that in a full compose setup it should be http://backend:6039.

Installing ruoyi-web and getting a first conversation running

There are two documented paths. The recommended one starts every service from pre-built images out of the backend repository, and the README states the user frontend then answers on port 25137 with the account admin / admin123. Note that this port differs from the separately deployed frontend port, 5137. The README lists both without explaining the difference, which is the kind of detail that costs an afternoon if you assume they are the same.

The one-command route:

git clone https://github.com/ageerle/ruoyi-ai.git
cd ruoyi-ai
docker-compose -f docker-compose-all.yaml up -d

After this, the README says to open http://localhost:25137 and log in with admin / admin123. If the login page loads but conversations fail, the backend is the suspect, not the frontend.

For local work on the frontend itself, the README gives the pnpm flow:

pnpm install
pnpm dev
pnpm build

pnpm install pulls the dependency set above, pnpm dev starts the Vite dev server, and pnpm build runs vue-tsc type checking before the Vite production build. That type-check step means a type error fails the build rather than being stripped, which is a deliberate constraint.

To deploy this repository alone against an existing backend, use its own compose file and set the upstream:

services:
  frontend:
    build:
      context: .
      dockerfile: Dockerfile.frontend
    ports:
      - "5137:5137"
    environment:
      UPSTREAM_URL: http://host.docker.internal:26039

The container listens on 5137, and nginx forwards API calls to whatever UPSTREAM_URL names. If the page loads and the API calls 502, that variable is the first thing to inspect.

The frontend-only boundary and the port confusion

The clearest limitation is structural. This repository contains no backend, no database and no vector store. The README's service table lists MySQL on 23306, Redis on 6379, Weaviate on 28080 and MinIO on 9000/9090, but those belong to the wider RuoYi-AI deployment, not to this codebase. Cloning ruoyi-web alone gives you a user interface that cannot answer a question. Knowledge-base Q&A in particular depends on Weaviate and MinIO being present upstream, and nothing in this repository substitutes for them.

The second issue is documentation drift. The README says Ant Design Vue; package.json says Element Plus. The README shows 25137 for the all-in-one deployment and 5137 for the standalone frontend. The README's troubleshooting entry for a frontend that cannot reach the backend names UPSTREAM_URL as the fix, which is correct but thin: it does not cover CORS, TLS, or the case where the proxy target resolves but the API path does not. The README does not document rollback, version pinning between frontend and backend, or what happens when the two are upgraded independently. Given that v3.0.0 landed in April 2026 and v3.1.0 in August 2026, that upgrade path is a real question the documentation leaves open.

How it compares with building on a component library directly

The obvious alternative is not another chat product; it is assembling your own interface from vue-element-plus-x or Ant Design X, the component libraries that provide chat bubbles, streaming message rendering and input boxes. The difference in approach is scope. A component library gives you parts and leaves routing, authentication, conversation state, agent selection and knowledge-base upload to you. ruoyi-web gives you those assembled, but only in the shape the RuoYi-AI backend expects. You trade control for a working default.

A second alternative is the admin panel in the same family, ageerle/ruoyi-admin. If your need is configuring models, managing users and inspecting knowledge bases rather than holding a conversation, the admin panel is the correct piece, and the README treats it as optional alongside the user frontend. Choosing between them is a question of who the user is, not which one is better. Teams that want a chat product for end users take ruoyi-web; teams that want an operations console take ruoyi-admin.

Maintenance, licence and what an upgrade costs you

The repository is not archived, and the last push was on 2026-09-08. Two releases are listed: v3.0.0 on 2026-04-13 and v3.1.0 on 2026-08-04. The commit tooling in the repository (husky, commitlint, cz-git, changesets) suggests the maintainers intend a structured release process, and the presence of CLAUDE.md indicates AI-assisted development is part of the workflow.

The licence is MIT, stated in both the README and package.json. MIT permits commercial use, modification and redistribution provided the copyright notice and permission notice are retained; the license file in the repository root is the authoritative text. That is a permissive position, but it covers this frontend only. The backend, admin panel and the bundled services (MySQL, Redis, Weaviate, MinIO) carry their own licences, and a production deployment inherits all of them. Nothing here is legal advice; read the license file and the licences of the services you actually run.

The upgrade cost is the unresolved part. Because the frontend talks to a separately versioned backend, a frontend release can require a backend release. The README does not state a compatibility matrix, and package.json carries version 0.0.0 while the release tags read v3.1.0, so the package version tells you nothing about which backend it matches. Pin both sides and test the pairing before upgrading either.

Editorial conclusion

Adopt ruoyi-web if you already run the ageerle/ruoyi-ai backend and want a ready-made chat and knowledge-base client rather than building one. Do not adopt it as a standalone product: the repository ships a frontend only, and the README's own troubleshooting entry makes the backend connection the first thing to check. Before committing, verify that your backend exposes the API this build expects, that UPSTREAM_URL points at a reachable host from inside the container, and that the MIT licence terms in the license file match how you intend to redistribute the built assets.

Frequently asked questions

Official sources

1. ageerle/ruoyi-web on GitHub
2. License: MIT
3. Project website
4. README
5. Releases