🚀 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

Hardware Configuration

Environment Dependencies

🛠️ Environment Setup

1️⃣ Python (3.13.x)

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

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:

💡 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

# 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

# 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

✅ 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

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

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

1. Server Deployment - Quick deployment using Docker

   • Web management interface
   • Backend API services
   • Database and cache
   • AI services

2. 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

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

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.

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:

1. ✅ Detect/copy Python environment to build/python_core
2. ✅ Install RPA engine dependencies
3. ✅ Compress Python core to resources/python_core.7z
4. ✅ Install frontend dependencies
5. ✅ 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:

Manual Frontend Build

If you need to manually build the frontend separately, you can execute the following 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.

Package completion path:

/frontend/packages/electron-app/dist/

Double-click the Exe file to install.

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

🔍 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

# 🔍 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)

# 📊 Check MySQL container status
docker compose ps mysql

# 📝 View MySQL logs
docker compose logs mysql

# 🔄 Restart database service
docker compose restart mysql

💻 Client Related

# 🔍 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

# ✅ Check all dependencies in preparation phase are fully installed

# 💾 Check disk space
dir  # Windows check available space

🔌 Connection Related

# 🌐 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

# 🔌 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

# 🧹 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

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!

🎯 Next Steps

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

🎉 Deployment Complete!

You have successfully deployed AstronRPA server and client

Now you can start creating powerful RPA automation workflows!

Happy Automating! 🤖✨