Deploy PandaWiki in 10 Minutes: Complete Guide

For the pursuit of data autonomy and control of the team, PandaWiki open source version of the local deployment is the optimal solution – no need for complex technical background, relying on Docker containerization technology, follow the steps step by step operation, you can quickly have their own intelligent knowledge base. This article integrates the deployment process, environment configuration details and common problem troubleshooting, the whole process without obscure terminology, zero basis can easily get started.

I. Preparation before deployment: confirm the environment and resources

1. hardware configuration requirements

• Recommended configuration: 2-core CPU + 4GB RAM + 20GB free disk (support stable use by a team of up to 10 people)
• Minimum configuration: 1-core CPU + 2GB RAM + 5GB free disk (only suitable for personal testing or temporary use by 2-3 people)
• Storage Recommendation: If you need to store a large number of documents, attachments, it is recommended to reserve more than 50GB of disk space to avoid the trouble of later expansion.

2. Software environment requirements

• Operating system: Linux kernel 3.10 or above, recommended Ubuntu 20.04+/CentOS 7+ (x86_64 architecture, ARM architecture is not supported for the time being)
• Kernel dependencies: Docker 20.10.x and above + Docker Compose v2.x and above
• Network conditions: the server needs to be able to access the Internet for pulling Docker images and project dependency packages

3. Pre-inspection points

After logging in to the server, execute the following commands to check the environment first to avoid stepping on potholes in the deployment:

# Check the Docker version (needs to be ≥ 20.10.x)
docker --version
# Check the Docker Compose version (must be ≥v2.x)
docker compose version
# Check server architecture (needs to return x86_64)
uname -m

If Docker is not installed or the version is too low, you need to complete the environment configuration first (detailed installation steps are attached below).

Step-by-step deployment process: from environment setup to system startup

1. Install Docker and Docker Compose (a must for newbies)

Take the Ubuntu system as an example, execute the following commands to complete the environment installation with one click, copy and paste:

# 1. Update system packages to avoid dependency conflicts
sudo apt-get update && sudo apt-get upgrade -y

# 2. Install the required Docker dependencies
sudo apt-get install -y apt-transport-https ca-certificates curl software-properties-common

# 3. Add the official Docker GPG key to secure the installation package
curl -fsSL https://mirrors.aliyun.com/docker-ce/linux/ubuntu/gpg | sudo apt-key add -

# 4. Add domestic Docker repositories to increase the download speed
sudo add-apt-repository "deb [arch=amd64] https://mirrors.aliyun.com/docker-ce/linux/ubuntu $(lsb_release -cs) stable"

# 5. Install the Docker Engine core components
sudo apt-get update && sudo apt-get install -y docker-ce docker-ce-cli containerd.io

# 6. Start the Docker service and set it to start on boot
sudo systemctl enable --now docker

# 7. Configure domestic mirror acceleration to solve the problem of slow pulling mirrors
sudo mkdir -p /etc/docker
sudo tee /etc/docker/daemon.json <<-'EOF'
{
  "registry-mirrors": ["https://docker.mirrors.ustc.edu.cn"]
}
EOF
sudo systemctl daemon-reload && sudo systemctl restart docker

# 8. Install Docker Compose (v2.x version)
sudo curl -L "https://github.com/docker/compose/releases/download/v2.27.0/docker-compose-$(uname -s)-$(uname -m)" -o /usr/local/bin/ docker-compose
sudo chmod +x /usr/local/bin/docker-compose

CentOS users can replace the corresponding yum command with the same core steps, focusing on ensuring that the Docker service starts properly.

2. Two deployment methods: one-click installation vs. manual customization deployment

Mode 1: one-click installation (recommended for newbies, completed in 10 minutes)

This is the easiest way to deploy, no need to manually configure files, execute a command to automatically complete all operations:

# Switch root privileges (to avoid deployment failure due to insufficient privileges)
sudo -i

# Execute the official one-click deployment script
bash -c "$(curl -fsSLk https://release.baizhi.cloud/panda-wiki/manager.sh)"

Execute it and follow the terminal prompts:

1. Enter the number 1 to select the “Install” option;
2. There is no need to change the default port (2443), just enter to confirm;
3. Wait for 5-10 minutes (depending on the server’s network speed), during which time it will automatically pull the image and configure the database;
4. SUCCESS” prompt that the deployment is complete, record the terminal output access address, user name (admin) and the default password.

Mode 2: Manual deployment (suitable for users with customization needs)

Suitable for users who need to modify the port and customize the storage path, the steps are as follows:

# 1. Clone the PandaWiki source code to the server
git clone https://gitcode.com/gh_mirrors/pa/PandaWiki.git
cd PandaWiki

# 2. Create and edit the docker-compose.yml configuration file
vim docker-compose.yml

Paste the following base configuration content (ports and storage paths can be modified as required)

version: '3'
services.
  api.
    build: .
      /backend: . /backend
      dockerfile: Dockerfile.api
    ports.
      - "2443:8080" # The left side of 2443 is the external port, which can be customized.
    volumes: .
      - . /data:/app/data # Path to the data store, we recommend keeping the default.
    depends_on: .
      - postgres
    restart: always

  postgres.
    image: postgres:14
    environment.
      POSTGRES_USER: panda
      POSTGRES_PASSWORD: panda123
      POSTGRES_DB: panda_wiki
    volumes: panda_wiki
      - . /pgdata:/var/lib/postgresql/data
    restart: always

After saving the configuration, execute the start command:

# Build and start the service
docker compose up -d
# Check the startup status and make sure all services are running
docker compose ps

3. System access and initialization

1. Open the browser and enter the access address prompted after the deployment is completed (format: http://服务器IP:2443);
2. Enter the default user name admin and the password displayed on the terminal, and change the password for the first login (it is recommended to include upper and lower case letters + numbers to enhance security);
3. After entering the system, first complete the basic configuration: set the site name, upload Logo, configure the time zone (default UTC, it is recommended to change to Asia/Shanghai).

Third, after the deployment must be done: basic configuration and security reinforcement

1. Core configuration optimization

• Storage Configuration: Check whether the data storage path is correct, and ensure sufficient disk space to avoid service anomalies due to insufficient space;
• Port protection: If the server is exposed to the external network, it is recommended to restrict access to port 2443 in the firewall and allow only internal IP access;
• AI Function Configuration: Go to “System Settings – AI Models” and dock the APIs of big models such as Bai Zhi Yun and Tongyi Qianqian to unlock the AI creation and AI search functions.

2. Key points of security settings

• Password change: change the default password immediately after the first login to avoid weak passwords being cracked;
• Permission management: create different role accounts (editors, readers) and assign permissions according to the team’s needs to avoid having administrator permissions for the whole staff;
• Backup strategy: regular backup of data directories (. /data and . /pgdata), you can set up a timed script to automatically backup to prevent data loss.

Fourth, the common problems: to solve the deployment of the pits

1. Deployment script execution failure

• Problem Cause: Network timeout or insufficient privileges;
• Solution: Switch root privileges to re-execute the script. If pulling images is slow, check whether the Docker image acceleration configuration is in effect.

2. Browser can not access the system

• Problem Cause: The port is not open or the service is not started;
• Solution:
  1. Execute docker compose ps to check if the api service is running;
  2. Open port 2443: Ubuntu execute sudo ufw allow 2443, CentOS execute sudo firewall-cmd --permanent --add-port=2443/tcp && sudo firewall-cmd --reload;
  3. Check if the server security group releases port 2443 (cloud servers need to be configured in the console).

3. Wrong password when logging in

• Problem Cause: The default password is incorrectly recorded;
• Solution: Execute docker compose logs api to view the logs, find the line containing “password” and get the correct default password.

4. Frequent crashes after service startup

• Problem Cause: Insufficient server memory (commonly found in 1-core 2GB configurations);
• Solution: Upgrade the server memory to more than 4GB, or close other memory-consuming services to reduce the system load.

V. Daily Maintenance: Upgrade and Backup Guide

1. Version Upgrade

PandaWiki open source version of the frequent iterations, upgrade steps are as follows:

# Enter the project directory
cd PandaWiki
# Pull the latest source code
git pull
# Rebuild and start the service
docker compose down && docker compose up -d

2. Data backup and recovery

• Backup: just pack the data directory directly, command: tar -zcvf panda_backup.tar.gz . /data . /pgdata;
• Restore: upload the backup file to the new server, extract it to the PandaWiki directory, and then execute docker compose up -d.

Follow the above steps to run PandaWiki open source version stably and enjoy the AI-driven intelligent knowledge base service. If you need to dock internal systems (such as Nail, Flybook) or secondary development, you can refer to the official documents for further configuration.