Features

• Blazing Fast — Built on uv for near-instant CLI response times
• Smart Init — Auto-detects and installs dependencies (uv sync / pnpm install), auto-installs uv if missing
• One-Click Deploy — Deploy the full stack (Backend + Frontend + PostgreSQL + Redis + Nginx SSL) with a single hohu deploy
• Source Build — Build Docker images from your modified source code with hohu build, then deploy
• Database Migrations — Run migrations and seed data via hohu migrate
• Context-Aware — Run commands from any subdirectory via .hohu project config
• i18n — Full Chinese & English support with automatic system language detection
• Polished UX — Rich-formatted output with interactive prompts via Questionary

About hohu-admin

hohu-admin is an enterprise-grade full-stack admin management platform built for the AI era. It provides a complete set of production-ready backend infrastructure out of the box — user authentication, RBAC permission control, distributed ID generation, database migration, log monitoring, and API documentation — so developers can focus on business innovation instead of repetitive boilerplate.

Highlights

• Async High Performance — Full async pipeline (FastAPI + SQLAlchemy 2.0 async + PostgreSQL)
• Distributed Snowflake ID — Time-ordered, high-performance primary keys with automatic BigInt → string serialization
• RBAC Permission Model — User-Role-Menu based access control with button-level granularity
• Dual Auth Support — OAuth2 form login (Swagger UI) + JSON login (SPA), with Redis token blacklist
• Unified API Response — Consistent {code, message, data} envelope across all endpoints
• Auto Case Conversion — Backend snake_case ↔ Frontend camelCase via Pydantic alias_generator

Projects

Quick Start

Install

# uv (recommended)
uv tool install hohu

# pip
pip install hohu

Update

# uv
uv tool upgrade hohu

# pip
pip install --upgrade hohu

Create a Project

hohu create my-project

For agents or scripts, select components without interactive prompts:

hohu create my-project --component backend --component web --non-interactive

The default auto source tries GitHub first and switches to the official Gitee mirror on network failure. To use one source explicitly:

hohu create my-project --source gitee
hohu create my-project --source github

Save "source": "gitee" in ~/.hohu/config.json to use Gitee by default, preserving other settings. Explicit sources and custom repositories do not fall back. Official repositories check out main; custom repositories keep their remote default branch. Each completed component's source and commit are recorded in .hohu/project.json.

Creation also generates root AGENTS.md, CLAUDE.md, README.md and .gitignore from bundled templates. Open the project root in your coding assistant; its reading map links the selected components' existing instructions. See project creation for guidance, source priority, component aliases, failure recovery and initialization boundaries.

Confirm each component (Backend / Frontend / App) interactively. Defaults to hohu-admin if no name is given.

Install Dependencies

cd my-project
hohu init

Automatically detects project config and installs all dependencies.

Windows Users: If hohu init fails with EPERM: operation not permitted, symlink, try the following:

1. Enable Developer Mode in Windows Settings: Settings → Update & Security → For developers → Developer Mode. This allows symlink creation without admin privileges.
2. Run your terminal as Administrator.
3. Check your antivirus software (e.g., 360, Huorong) — some may block symlink creation. Try adding the project directory to the exclusion list or temporarily disabling real-time protection.

Install AI Coding Skills

From your business project directory, use either entry point:

hohu skills install
npx skills@latest add aihohu/hohu-skills

The HoHu command uses skills@1.7.0 and requires stable Node.js >=22.20.0 with npm/npx. Select Claude Code, Cursor, Codex, OpenCode, TRAE or another upstream-supported agent. Use repeated --agent flags for explicit targets. See the installation guide and contributor contract.

Switch Language

hohu lang

Development Server

hohu dev launches all services in a single terminal with merged, color-coded log output.

hohu dev          # Start all components
hohu dev -o be    # Backend only
hohu dev -s app   # Frontend + Backend, skip App
hohu dev -t mp    # App in WeChat Mini Program mode

Options

Component aliases (case-insensitive): be / backend, fe / frontend, app

Log Colors

Press Ctrl+C for graceful shutdown — all child processes are terminated cleanly.

Build

Build Docker images from local source code. After building, run hohu deploy to deploy with the locally built images.

hohu build                  # Build all components
hohu build --only=backend   # Build backend only
hohu build --only=frontend  # Build frontend only
hohu build --no-cache       # Build without cache
hohu build --tag=v1.0.0     # Custom image tag
hohu build --reset          # Reset to official GHCR images

Automatically initializes .hohu/deploy/ (config, .env, secrets) on first run — no need to run hohu deploy init separately. Switch back to official images anytime with hohu build --reset.

Deployment

Deploy the full stack to a Linux server with Docker Compose. Includes PostgreSQL, Redis, Nginx (SSL termination), and the application services.

Quick Start

Source build deploy:

hohu build          # Build images (auto-initializes deploy config)
hohu deploy         # Deploy

Official image deploy:

hohu deploy init    # Initialize deployment config and generate .env
hohu deploy         # Pull images and deploy

Edit .hohu/deploy/.env to set passwords, SECRET_KEY, and SSL certificate path before deploying.

Deploy Commands

hohu deploy          # One-click deploy (pull → migrate → start)
hohu deploy init     # Initialize deployment directory and .env
hohu deploy pull     # Pull latest images and restart
hohu deploy ps       # Show service status
hohu deploy logs     # View logs (-f to follow)
hohu deploy restart  # Restart services
hohu deploy down     # Stop all services
hohu migrate         # Run database migrations and synchronize built-in data

Deploy Options

hohu deploy                 # Migrate and initialize/synchronize data automatically
hohu deploy --no-migrate    # Skip migrations and data synchronization

External PostgreSQL / Redis

The initial admin password is generated in .hohu/deploy/.env as HOHU_ADMIN_PASSWORD. It is never printed or reset by subsequent deployments. Core multi-tenant deployments use TENANT_MODE=hosted, TENANT_HOSTED_LOGIN_ENABLED=true, and the full backend RELEASE_BUILD_SHA.

By default, PostgreSQL and Redis run as Docker containers. To use your own instances, edit .hohu/deploy/.env:

# Disable built-in PostgreSQL
ENABLE_POSTGRES=false
DATABASE_URL=postgresql+asyncpg://user:password@your-pg-host:5432/dbname

# Disable built-in Redis
ENABLE_REDIS=false
REDIS_HOST=your-redis-host
REDIS_PASSWORD=your-redis-password

When disabled, the corresponding containers won't start and the application connects to your external instances.

Architecture

Internet → Nginx (SSL) → hohu-admin-web → hohu-admin-api → PostgreSQL + Redis

SSL Certificates

Place your certificate files in .hohu/deploy/ssl/:

ssl/
├── fullchain.pem
└── privkey.pem

For Let's Encrypt, point SSL_CERT_PATH in .env to the certbot output directory.

Command Reference

Tech Stack

Contributing

Issues and Pull Requests are welcome!

Maintainers can mirror the deployment's PostgreSQL, Redis, and Nginx images to public ACR repositories through the infrastructure mirror workflow.

See the contribution guide and testing guide for setup and check commands. During development, run related regressions; commit hooks run Ruff lint and format checks. Run the full suite and coverage at feature acceptance and in CI.