🚀 AstronRPA Quick Start Guide

Fast, Simple, Powerful RPA Automation Platform Deployment Guide

Quick Start · Server Deployment · Client Deployment · FAQ

📋 Table of Contents

System Requirements
Environment Setup
Deployment Architecture
Server Deployment (Docker)
Client Deployment (Local)
Development Environment
FAQ

💻 System Requirements

Operating System

OS	Version	Support Status
Windows	10/11	✅ Primary Support

Hardware Configuration

Component	Minimum	Recommended
CPU	2 cores	4 cores+
Memory	4GB	8GB+
Disk	10GB available	20GB+
Network	Stable internet connection	-

Environment Dependencies

Tool	Version	Description
Node.js	>= 22	JavaScript runtime
Python	3.13.x	RPA engine core
Java	JDK 8+	Backend service runtime
pnpm	>= 9	Node.js package manager
UV	0.8+	Python package manager
7-Zip	-	Create deployment archives
SWIG	-	Connect Python with C/C++

🛠️ Environment Setup

1️⃣ Python (3.13.x)

🐍 Core Dependency · AstronRPA requires Python 3.13.x as the RPA engine core

📦 Installation Methods (Click to expand)

Method 1: Official Download (Recommended)

# Visit https://www.python.org/downloads/
# Download and install Python 3.13.x

Method 2: Using Winget

winget install Python.Python.3.13

Method 3: Using Chocolatey

choco install python --version=3.13.x

📍 Python Installation Path

After installation, remember your Python installation path for later configuration:

Installation Method	Typical Path
🟢 Official Installer	`C:\Users\{username}\AppData\Local\Programs\Python\Python313\`
🔵 Chocolatey	`C:\Python313\` or `C:\tools\python3\`

💡 Important Note:

✓ Python executable: {installation_directory}\python.exe
✓ Example: C:\Users\{username}\AppData\Local\Programs\Python\Python313\python.exe

2️⃣ UV (0.8+)

⚡ Fast Package Management · Next-generation Python package manager, 10-100x faster than pip

📦 Installation Methods (Click to expand)

# Method 1: Official installation script (Recommended)
powershell -c "irm https://astral.sh/uv/install.ps1 | iex"

# Method 2: Using pip
pip install uv

# Method 3: Using Chocolatey
choco install uv

✅ Verify Installation

uv --version
# ✓ Should display something like: uv 0.8.x (xxxxx)

📖 Learn More: UV Official Documentation

3️⃣ pnpm (9+)

📦 Efficient Package Management · Disk space-saving Node.js package manager

📦 Installation Methods (Click to expand)

# Method 1: Using npm (Recommended)
npm install -g pnpm@latest

# Method 2: Windows PowerShell
iwr https://get.pnpm.io/install.ps1 -useb | iex

# Method 3: macOS/Linux
curl -fsSL https://get.pnpm.io/install.sh | sh -

# Method 4: Homebrew (macOS)
brew install pnpm

✅ Verify Installation

pnpm --version
# ✓ Should display 9.x.x or higher

📖 Learn More: pnpm Official Documentation

4️⃣ Docker

🐳 Containerization Platform · For rapid server deployment

📥 Download & Install (Click to expand)

Platform	Download Link
🪟 Windows/Mac	Docker Desktop
🐧 Linux	Docker Engine

✅ Verify Installation

docker --version
docker compose --version
# ✓ Confirm both Docker and Docker Compose are installed correctly

5️⃣ 7-Zip

📦 Compression Tool · For creating deployment archive files

📥 Download & Install (Click to expand)

Official Website: https://www.7-zip.org/

Download and install to system, or extract to a custom directory

✅ Verify Installation

# If installed to system path
7z

# Or use full path
"C:\Program Files\7-Zip\7z.exe"

6️⃣ SWIG

🔗 Interface Generator · For connecting Python with C/C++ programs

📥 Installation Steps (Click to expand)

Step 1: Download SWIG

Visit http://www.swig.org/download.html
Download swigwin-x.x.x.zip and extract to any directory

Step 2: Add to System Environment Variables

Add the directory containing swig.exe to PATH environment variable
For example: C:\swig\swigwin-4.1.1

Step 3: Verify Installation

swig -version
# ✓ Confirm SWIG is installed correctly

🏗️ Deployment Architecture

AstronRPA adopts a Server-Client architecture:

Deployment Overview

Server Deployment - Quick deployment using Docker
- Web management interface
- Backend API services
- Database and cache
- AI services
Client Deployment - Deploy using packaging scripts
- RPA execution engine
- Desktop management application
- Connect to server for task execution

🌐 Server Deployment (Docker)

Quick Deployment · Launch all server components with Docker Compose in one command

The server provides web management interface, API services, database and other core services.

📦 Deployment Steps

Step 1️⃣: Clone Repository

git clone https://github.com/iflytek/astron-rpa.git
cd astron-rpa

Step 2️⃣: Start Server

# Enter Docker directory
cd docker

# Copy .env file
cp .env.example .env

# Modify casdoor service configuration in .env
CASDOOR_EXTERNAL_ENDPOINT="http://{YOUR_SERVER_IP}:8000"

# 🚀 Start all services
docker compose up -d

# 📊 Check service status
docker compose ps

💡 Expected Output Example

NAME                STATUS              PORTS
robot-service       Up 30 seconds       0.0.0.0:8080->8080/tcp
ai-service          Up 30 seconds       0.0.0.0:8001->8001/tcp
openapi-service     Up 30 seconds       0.0.0.0:8002->8002/tcp
mysql               Up 30 seconds       0.0.0.0:3306->3306/tcp
redis               Up 30 seconds       0.0.0.0:6379->6379/tcp

Step 3️⃣: Verify Server Deployment

# 📝 View service logs
docker compose logs -f

🔧 Server Management Commands

# 🛑 Stop services
docker compose down

# 🔄 Restart services
docker compose restart

# 📋 View specific service logs
docker compose logs -f robot-service

# ⬆️ Update images
docker compose pull
docker compose up -d

📖 Detailed Configuration: Server Deployment Guide

💻 Client Deployment (Local)

Local Deployment · Deploy engine and desktop application on machines running RPA tasks

The client includes RPA execution engine and desktop management application, needs to be deployed on machines executing RPA tasks.

🎯 One-Click Packaging Deployment

Suitable for production environments and end users.

🪟 Windows Environment

Step 1️⃣: Prepare Python Environment

Ensure Python 3.13.x is installed to a local directory (e.g., C:\Python313).

Environment Directory Structure:

Python313/
├─ DLLs/
├─ Doc/
├─ include/
├─ Lib/
├─ libs/
├─ Scripts/
├─ tcl/
│
├─ LICENSE.txt
├─ NEWS.txt
├─ python.exe
├─ python3.dll
├─ python313.dll
├─ pythonw.exe
├─ vcruntime140.dll
└─ vcruntime140_1.dll

⚠️ Important Note: Use a clean Python installation without additional third-party packages to reduce package size.

Step 2️⃣: Run Packaging Script

Basic Usage

Execute the build script from the project root directory:

# 🚀 Full build (engine + frontend)
./build.bat --python-exe "C:\Program Files\Python313\python.exe"

# Or use default configuration (if Python is in default path)
./build.bat

# ⏳ Wait for operation to complete
# ✅ Build successful when console displays "Full Build Complete!"

Execution Flow:

✅ Detect/copy Python environment to build/python_core
✅ Install RPA engine dependencies
✅ Compress Python core to resources/python_core.7z
✅ Install frontend dependencies
✅ Build desktop application

Advanced Options

View all available parameters:

./build.bat --help

Common Parameter Combinations:

# 🔧 Specify Python path
./build.bat --python-exe "D:\Python313\python.exe"

# 🔧 Specify 7-Zip path
./build.bat --sevenz-exe "D:\7-Zip\7z.exe"

# ⏭️ Build engine only, skip frontend
./build.bat --skip-frontend

# ⏭️ Build frontend only, skip engine
./build.bat --skip-engine

# 🔀 Combine with short options
./build.bat -p "D:\Python313\python.exe" -s "D:\7-Zip\7z.exe"

Parameter Description:

Parameter	Short	Description
`--python-exe <path>`	`-p`	Specify Python executable path
`--sevenz-exe <path>`	`-s`	Specify 7-Zip executable path
`--skip-engine`	-	Skip engine (Python) build
`--skip-frontend`	-	Skip frontend build
`--help`	`-h`	Display help message

Manual Frontend Build

If you need to manually build the frontend separately, you can execute the following steps:

Click to expand manual build steps

cd frontend

# 📦 Install dependencies
pnpm install

# ⚙️ Configure environment variables
pnpm set-env

# 🖥️ Build desktop application
pnpm build:desktop

Tip: Use build.bat --skip-engine to automatically complete the frontend build steps above.

Step 3️⃣: Install Exe Package

Package completion path:

/frontend/packages/electron-app/dist/

Double-click the Exe file to install.

Step 4️⃣: Configure Server Address

Modify the server address in resources/conf.yaml under the installation directory:

# 32742 is the default port, modify if changed
remote_addr: http://YOUR_SERVER_ADDRESS:32742/
skip_engine_start: false

💡 Tip: Replace YOUR_SERVER_ADDRESS with your actual server address

🌐 Development Server Addresses

Service	Address	Description
🖥️ Desktop App	Auto-launch window	Desktop client
🔌 Backend Service API	http://localhost:32742	Backend Gateway Service Nginx
🔑 Casdoor Service API	http://localhost:8000	Authentication Service Casdoor

🔍 Complete Deployment Verification

✅ Step 1: Server Check

# 📊 Check Docker service status
docker compose ps

# 🔍 Verify API response
# Open in browser: http://{YOUR_SERVER_IP}:32742/api/rpa-auth/user/login-check (32742 is default port, modify if changed)
# If returns {"code":"900001","data":null,"message":"unauthorized"} then deployment is correct and connected

✅ Step 2: Casdoor Service Check

# 🔍 Verify Casdoor service
# Open http://localhost:8000 in browser
# Casdoor authentication page should appear

Follow-up Verification:

✓ Check client node status in web interface
✓ Create simple test task to verify execution

❓ FAQ

🌐 Server Related

Q: Docker service fails to start?

# 🔍 Check port usage
netstat -tulpn | grep :8080

# ✅ Check Docker status
docker --version
docker compose --version

# 📋 View detailed error logs
docker compose logs

Common Causes:

❌ Ports occupied (8080, 3306, 6379)
❌ Docker service not started
❌ Insufficient resources (memory/disk space)

Q: Database connection failed?

# 📊 Check MySQL container status
docker compose ps mysql

# 📝 View MySQL logs
docker compose logs mysql

# 🔄 Restart database service
docker compose restart mysql

💻 Client Related

Q: Python environment copy failed?

# 🔍 Check Python installation path
where python  # Windows
which python  # Linux/macOS

# 🔍 Make sure to pass the Python executable file

✖️ ./build.bat -p "C:\\Python313"
✔️ ./build.bat -p "C:\\Python313\\python.exe"

Solutions:

✓ Ensure Python directory exists and is readable
✓ Run script with administrator privileges
✓ Check sufficient disk space

Q: Packaging script execution failed?

# ✅ Check all dependencies in preparation phase are fully installed

# 💾 Check disk space
dir  # Windows check available space

🔌 Connection Related

Q: Client cannot connect to server?

# 🌐 Check network connectivity
# Open the following URL in your browser to see if there's a response
# http://localhost:32742 can be replaced with your deployed server address+port
http://localhost:32742/api/rpa-auth/user/login-check

# 🛡️ Check firewall settings
# Windows: Control Panel > System and Security > Windows Defender Firewall
# Linux: ufw status

# ✅ Check server health status
curl http://localhost:32742/health

Common Causes:

❌ Server not started
❌ Firewall blocking
❌ Network unreachable
❌ Incorrect address in config file

Q: WebSocket connection failed?

# 🔌 Check WebSocket endpoint
curl -i -N -H "Connection: Upgrade" -H "Upgrade: websocket" \
     http://localhost:8080/ws

# 🔍 Check proxy settings
echo $http_proxy
echo $https_proxy

Solutions:

✓ Confirm server WebSocket service is running
✓ Check if proxy affects connection
✓ Verify firewall rules

🏗️ Build Related

Q: Frontend build failed?

# 🧹 Clear cache
pnpm store prune
rm -rf node_modules pnpm-lock.yaml

# 📦 Reinstall
pnpm install

# ✅ Check Node.js version
node --version  # Requires 22+

Common Causes:

❌ Node.js version not meeting requirements
❌ Dependency version conflicts
❌ Cache corruption

Q: pywinhook installation fails with swig.exe not found error?

Error Message:

error: Microsoft Visual C++ 14.0 is required
or
swig.exe not found

Solution Steps:

1️⃣ Download SWIG

Visit http://www.swig.org/download.html
Download swigwin-x.x.x.zip and extract to any directory

2️⃣ Add to System Environment Variables

Add the directory containing swig.exe to PATH environment variable
For example: C:\swig\swigwin-4.1.1

3️⃣ Verify Installation

swig -version

4️⃣ Reinstall pywinhook

pip install pywinhook

📞 Get Help

Having issues? We're here to help!

Channel	Link	Description
📧 Technical Support	cbg_rpa_ml@iflytek.com	Contact technical team directly
💬 Community Discussion	GitHub Discussions	Exchange ideas with community
🐛 Issue Report	GitHub Issues	Submit bugs and feature requests
📖 Full Documentation	Project Documentation	View detailed usage documentation

🎯 Next Steps

✨ Congratulations on completing deployment! Now start your RPA automation journey ✨

Step	Content	Link
1️⃣	📚 Learn to Use	Read User Guide to learn how to create RPA processes
2️⃣	🔧 Component Development	Refer to Component Development Guide to develop custom components
3️⃣	🤝 Contribute	Check Contributing Guide to participate in project development
4️⃣	📱 Production Deployment	Refer to Production Deployment Guide for production deployment

🎉 Deployment Complete!

You have successfully deployed AstronRPA server and client

Now you can start creating powerful RPA automation workflows!

Happy Automating! 🤖✨

Uh oh!

FilesExpand file tree

BUILD_GUIDE.md

Latest commit

History

BUILD_GUIDE.md

File metadata and controls

🚀 AstronRPA Quick Start Guide

📋 Table of Contents

💻 System Requirements

Operating System

Hardware Configuration

Environment Dependencies

🛠️ Environment Setup

1️⃣ Python (3.13.x)

Method 1: Official Download (Recommended)

Method 2: Using Winget

Method 3: Using Chocolatey

📍 Python Installation Path

2️⃣ UV (0.8+)

✅ Verify Installation

3️⃣ pnpm (9+)

✅ Verify Installation

4️⃣ Docker

✅ Verify Installation

5️⃣ 7-Zip

✅ Verify Installation

6️⃣ SWIG

Step 1: Download SWIG

Step 2: Add to System Environment Variables

Step 3: Verify Installation

🏗️ Deployment Architecture

Deployment Overview

🌐 Server Deployment (Docker)

📦 Deployment Steps

Step 1️⃣: Clone Repository

Step 2️⃣: Start Server

Step 3️⃣: Verify Server Deployment

🔧 Server Management Commands

💻 Client Deployment (Local)

🎯 One-Click Packaging Deployment

🪟 Windows Environment

Basic Usage

Advanced Options

Manual Frontend Build

🌐 Development Server Addresses

🔍 Complete Deployment Verification

✅ Step 1: Server Check

✅ Step 2: Casdoor Service Check

❓ FAQ

🌐 Server Related

💻 Client Related

🔌 Connection Related

🏗️ Build Related

📞 Get Help

🎯 Next Steps

🎉 Deployment Complete!