9.9 KiB

Raw Permalink Blame History

Installation Guide

This guide covers the recommended ways to run PaoPao in development, evaluation, and self-hosted deployments. For a project overview, see README.md.

Choose an Installation Path

Scenario	Recommended path
Quick local evaluation	Docker Compose
Container-based deployment	Docker images
Backend or frontend development	Run from source
Desktop client build	Desktop app

Requirements

For source-based development

Go 1.24+
Node.js 20.19+ or 22.12+
Yarn 1.x
MySQL 5.7+ if using the MySQL path
Redis
Meilisearch
Rust and the platform prerequisites required by Tauri if you want to build the desktop client

Helpful repository files

config.yaml.sample - canonical configuration template
scripts/paopao-mysql.sql - MySQL bootstrap schema
scripts/paopao-postgres.sql - PostgreSQL bootstrap schema
scripts/paopao-sqlite3.sql - SQLite bootstrap schema
docker-compose.yaml - local multi-service environment

Option 1: Docker Compose (recommended for quick evaluation)

This is the fastest way to start a local environment with the main dependencies wired together.

git clone https://github.com/rocboss/paopao-ce.git
cd paopao-ce
docker compose up -d

The default compose setup starts these services:

http://localhost:8008 - PaoPao application
http://localhost:7700 - Meilisearch
http://localhost:8001 - RedisInsight
http://localhost:3306 - MySQL

Notes:

The backend container mounts ./config.yaml.sample as its runtime config by default.
Persistent data is stored under ./custom/.
Optional services such as MinIO, OpenObserve, Pyroscope, and phpMyAdmin are present in docker-compose.yaml but commented out by default.

If you want to use a custom config file, replace the mounted file in docker-compose.yaml:

backend:
  volumes:
    - ./config.yaml:/app/paopao-ce/config.yaml
    - ./custom:/app/paopao-ce/custom

Option 2: Docker Images

Backend image

# Default build: embeds the web UI and uses the default API host behavior
docker build -t your/paopao-ce:tag .

# Embed the web UI and set a custom API host
docker build -t your/paopao-ce:tag --build-arg API_HOST=http://api.paopao.info .

# Embed the web UI and keep the API host from local web/.env
docker build -t your/paopao-ce:tag --build-arg USE_API_HOST=no .

# Build with a precompiled local web/dist
docker build -t your/paopao-ce:tag --build-arg USE_DIST=yes .

# Build backend only, without embedded web UI
docker build -t your/paopao-ce:tag --build-arg EMBED_UI=no .

Run a locally built image:

mkdir -p custom
docker run -d -p 8008:8008 \
  -v ${PWD}/custom:/app/paopao-ce/custom \
  -v ${PWD}/config.yaml.sample:/app/paopao-ce/config.yaml \
  your/paopao-ce:tag

Or use the published image:

mkdir -p custom
docker run -d -p 8008:8008 \
  -v ${PWD}/custom:/app/paopao-ce/custom \
  -v ${PWD}/config.yaml.sample:/app/paopao-ce/config.yaml \
  bitbus/paopao-ce:latest

Web image

cd web

# Default build
docker build -t your/paopao-ce:web .

# Build with a custom API host
docker build -t your/paopao-ce:web --build-arg API_HOST=http://api.paopao.info .

# Build with a precompiled local dist
docker build -t your/paopao-ce:web --build-arg USE_DIST=yes .

# Run
docker run -d -p 8010:80 your/paopao-ce:web

All-in-one image

# Build
docker buildx build --build-arg USE_DIST=yes -t your/paopao-ce:all-in-one-latest -f Dockerfile.allinone .

# Run a local image
docker run --name paopao-ce-allinone -d -p 8000:8008 -p 7700:7700 \
  -v ./data/custom:/app/custom \
  -v ./data/meili_data:/app/meili_data \
  your/paopao-ce:all-in-one-latest

# Run the published image
docker run --name paopao-ce-allinone -d -p 8000:8008 -p 7700:7700 \
  -v ./data/custom:/app/custom \
  -v ./data/meili_data:/app/meili_data \
  bitbus/paopao-ce:all-in-one-latest

If you mount a custom config.yaml, make sure Meili.ApiKey matches the container's MEILI_MASTER_KEY. The default key is paopao-meilisearch.

Option 3: Run from Source

Backend

Initialize your database with the matching SQL file for your chosen database engine.
Copy the configuration template.
Adjust only the bootstrap-critical settings for your environment.
Run or build the backend.

cp config.yaml.sample config.yaml
make run

Build a release binary:

make build

The binary is written to release/paopao.

Web frontend

cd web
cp .env .env.local
yarn
yarn dev

Build the web bundle:

yarn build

Embedded web UI

If you want the Go service to serve the web frontend directly, build the frontend assets first and then run with the embed tag:

make build-web
make run TAGS='embed'

Desktop app

The desktop client is built from web/ using Tauri:

cd web
cp .env .env.local
yarn
yarn build
yarn tauri build

Before running the Tauri build, install the platform prerequisites from the official Tauri documentation for your OS.

Common Build Tags

Tag	Purpose
`embed`	Serve the built web frontend from the Go binary
`migration`	Include migration support in the backend binary
`docs`	Enable the developer docs / OpenAPI service

Examples:

make build TAGS='migration'
make run TAGS='docs'
make run TAGS='embed'

Configuration Basics

At startup, PaoPao reads either:

./custom/config.yaml
./config.yaml

The first file found is used.

Important: the external file is no longer expected to carry every runtime knob. PaoPao loads embedded defaults first, then overlays your local config file.

Recommended split:

Bootstrap YAML: ports, feature selection, database, Redis, JWT, AdminSettings.EncryptionKey
Admin UI (/#/admin/settings): most site, search, storage, SMS, payment, and app-behavior settings

If a setting is marked restart required in the admin page, it is persisted immediately but only becomes active after a process restart.

The Features section controls which capability bundles are enabled:

Features:
  Default: ["Web", "Frontend:EmbedWeb", "Meili", "LocalOSS", "MySQL", "BigCacheIndex", "LoggerFile"]
  Develop: ["Base", "MySQL", "BigCacheIndex", "Meili", "Sms", "AliOSS", "LoggerMeili", "OSS:Retention"]
  Demo: ["Base", "MySQL", "Option", "Zinc", "Sms", "MinIO", "LoggerZinc", "Migration"]
  Slim: ["Base", "Sqlite3", "LocalOSS", "LoggerFile", "OSS:TempDir"]

Useful commands:

# Use the default suite
release/paopao serve

# Use only the develop suite
release/paopao serve --no-default-features --features develop

# Add one extra feature on top of default
release/paopao serve --features sms

# Specify features explicitly
release/paopao serve --no-default-features --features sqlite3,localoss,loggerfile,redis

For feature maturity and support status, see features-status.md.

Optional Infrastructure Services

The default modern stack is centered on Meilisearch, Redis, and either LocalOSS, MinIO, or a cloud object store. Optional integrations can be started separately when needed.

Meilisearch (recommended search engine)

mkdir -p data/meili/data
docker run -d --name meili \
  -v ${PWD}/data/meili/data:/meili_data \
  -p 7700:7700 \
  -e MEILI_MASTER_KEY=paopao-meilisearch \
  getmeili/meilisearch:v0.29.0

Matching config example:

Meili:
  Host: 127.0.0.1:7700
  Index: paopao-data
  ApiKey: paopao-meilisearch
  Secure: False

MinIO

mkdir -p data/minio/data
docker run -d --name minio \
  -v ${PWD}/data/minio/data:/data \
  -p 9000:9000 -p 9001:9001 \
  -e MINIO_ROOT_USER=minio-root-user \
  -e MINIO_ROOT_PASSWORD=minio-root-password \
  -e MINIO_DEFAULT_BUCKETS=paopao:public \
  bitnami/minio:latest