Installation and Setup¶

🚀 Get Started with PyAutomation

Quick Setup Guide for Development and Production

This comprehensive guide covers the installation and configuration of PyAutomation for both development and production environments. Follow these steps to get PyAutomation up and running in minutes!

📋 Prerequisites¶

Before installing PyAutomation, ensure you have the following installed on your system:

🐍 Python

Version 3.10 or higher

📦 pip

Python package installer

🔧 Virtualenv

Optional but recommended

🔀 Git

Version control system

⚡ Installation Steps¶

Step 1: Clone the Repository¶

Start by cloning the PyAutomation repository to your local machine:

git clone https://github.com/know-ai/PyAutomation.git
cd PyAutomation

Step 2: Set Up a Virtual Environment¶

It is best practice to run Python applications in a virtual environment to avoid dependency conflicts.

🐧 Linux/macOS

python3 -m venv venv
source venv/bin/activate

🪟 Windows

python -m venv venv
.\venv\Scripts\activate

Step 3: Install Dependencies¶

Install the required Python packages using pip:

pip install --upgrade pip
pip install -r requirements.txt

💡 Tip: If you are developing documentation or running tests, you might also want to install additional requirements:

pip install -r docs_requirements.txt

⚙️ Configuration¶

Environment Variables¶

🔐 Configure Your Environment

PyAutomation uses environment variables and configuration files to manage settings. Create a .env file in the root directory to configure the application.

Example .env file:

# Web Server Configuration  
AUTOMATION_PORT=8050                  # default 8050         
AUTOMATION_VERSION=2.0.0             # default latest
AUTOMATION_OPCUA_SERVER_PORT=53530    # default 53530
AUTOMATION_HMI_PORT=5000
AUTOMATION_APP_SECRET_KEY="12DFW7HJHJWER6W73338343-FEDF94-EF9EF-EFR9ER"
AUTOMATION_SUPERUSER_PASSWORD="super_ultra_secret_password"
AUTOMATION_DB_TYPE=postgresql
AUTOMATION_DB_HOST=xxx.xxx.xxx.xxx
AUTOMATION_DB_PORT=5432
AUTOMATION_DB_USER=xxxxxxxx
AUTOMATION_DB_PASSWORD=xxxxxxxxx
AUTOMATION_DB_NAME=xxxxxxx

💾 Database Configuration¶

⚠️ Important: Database Setup Required

PyAutomation requires a database to be set up and running before you can connect to it through the web configuration interface.

1️⃣ Create Database

SQLite: No setup required - auto-created
PostgreSQL/MySQL: Create server/instance manually or using Docker

2️⃣ Connect PyAutomation

PyAutomation automatically creates all necessary tables when you establish the connection

PostgreSQL Setup with Docker¶

# Create PostgreSQL container
docker run -d \
  --name postgres-automation \
  -e POSTGRES_DB=automation_db \
  -e POSTGRES_USER=automation_user \
  -e POSTGRES_PASSWORD=your_password \
  -p 5432:5432 \
  -v postgres_data:/var/lib/postgresql/data \
  postgres:15

# Wait for PostgreSQL to be ready, then connect PyAutomation

MySQL Setup with Docker¶

# Create MySQL container
docker run -d \
  --name mysql-automation \
  -e MYSQL_DATABASE=automation_db \
  -e MYSQL_USER=automation_user \
  -e MYSQL_PASSWORD=your_password \
  -e MYSQL_ROOT_PASSWORD=root_password \
  -p 3306:3306 \
  -v mysql_data:/var/lib/mysql \
  mysql:8.0

# Wait for MySQL to be ready, then connect PyAutomation

Database Must Be Created Before Connection

You must create and configure the database server/instance before attempting to connect through the web configuration interface.

The database server must be running and accessible
The database instance must exist (for PostgreSQL/MySQL)
Connection credentials (host, port, user, password, database name) must be available
PyAutomation will automatically create all required tables when you establish the connection

If you try to connect before the database is ready, you will encounter connection errors in the web interface.

🏃 Running the Application¶

Development Mode¶

💻 Development Setup

To run the application locally for development:

python wsgi.py

Or simply:

./docker-entrypoint.sh

The application will start and be accessible at http://localhost:8050

Database Connection Process

When you connect PyAutomation to a database through the web interface:

PyAutomation establishes the connection to your pre-configured database server
Tables are created automatically - PyAutomation will create all necessary tables if they don't exist
Default data is initialized - Roles, variables, units, and data types are set up automatically
System is ready to use - You can now configure tags, alarms, and other components

No manual table creation is required - PyAutomation handles all schema initialization automatically upon connection.

🐳 Production (Docker)¶

🚀 Production Deployment

For production deployments, Docker is the recommended approach for reliability, scalability, and ease of management.

Docker Compose Configuration¶

Create a docker-compose.yml file in your project root with the following configuration:

services:
  automation:
    container_name: "Automation"
    image: "knowai/automation:${AUTOMATION_VERSION:-latest}"
    restart: always
    ports:
      # Backend API (Flask/Gunicorn)
      - ${AUTOMATION_PORT:-8050}:${AUTOMATION_PORT:-8050}
      # HMI frontend served by Nginx inside the container (listen 3000)
      - ${AUTOMATION_HMI_PORT:-3000}:3000
    volumes:
      - automation_db:/app/db
      - automation_logs:/app/logs
    logging:
      driver: "json-file"
      options:
        max-size: "10m" # Rota cuando llega a 10MB
        max-file: "3" # Guarda máximo 3 archivos (30MB total)
    environment:
      AUTOMATION_OPCUA_SERVER_PORT: ${AUTOMATION_OPCUA_SERVER_PORT:-53530}
      AUTOMATION_APP_SECRET_KEY: ${AUTOMATION_APP_SECRET_KEY:-073821603fcc483f9afee3f1500782a4}
      AUTOMATION_SUPERUSER_PASSWORD: ${AUTOMATION_SUPERUSER_PASSWORD:-super_ultra_secret_password}
      AUTOMATION_DB_TYPE: ${AUTOMATION_DB_TYPE:-postgresql}
      AUTOMATION_DB_HOST: ${AUTOMATION_DB_HOST:-127.0.0.1}
      AUTOMATION_DB_PORT: ${AUTOMATION_DB_PORT:-5432}
      AUTOMATION_DB_NAME: ${AUTOMATION_DB_NAME:-app_db}
      AUTOMATION_DB_USER: ${AUTOMATION_DB_USER:-postgres}
      AUTOMATION_DB_PASSWORD: ${AUTOMATION_DB_PASSWORD:-postgres}
    tmpfs:
      - /tmp:size=500k
    deploy:
      resources:
        limits:
          cpus: "0.5"
          memory: 256M
    healthcheck:
      test: ["CMD", "python", "/app/healthcheck.py"]
      interval: 15s
      timeout: 10s
      retries: 3

volumes:
  automation_db:
  automation_logs:

📝 Configuration Notes

Image: Uses the official knowai/automation image. Set AUTOMATION_VERSION environment variable to pin a specific version (defaults to latest).
Ports: Web interface port (default 8050). Override with AUTOMATION_PORT environment variable.
Volumes: Persistent storage for database (automation_db) and logs (automation_logs) to survive container restarts.
Logging: JSON file driver with rotation (10MB per file, max 3 files).
Resources: CPU and memory limits for production stability.
Healthcheck: Automatic health monitoring every 15 seconds.

Environment Variables for Production¶

For production deployments, you can create a .env file in the same directory as docker-compose.yml to customize the Docker Compose template without modifying the docker-compose.yml file itself.

Example `.env` file for production:

# Web Server Configuration  
AUTOMATION_PORT=8050                  # default 8050         
AUTOMATION_VERSION=2.0.0             # default latest
AUTOMATION_OPCUA_SERVER_PORT=53530    # default 53530
AUTOMATION_HMI_PORT=5000
AUTOMATION_APP_SECRET_KEY="12DFW7HJHJWER6W73338343-FEDF94-EF9EF-EFR9ER"
AUTOMATION_SUPERUSER_PASSWORD="super_ultra_secret_password"
AUTOMATION_DB_TYPE=postgresql
AUTOMATION_DB_HOST=xxx.xxx.xxx.xxx
AUTOMATION_DB_PORT=5432
AUTOMATION_DB_USER=xxxxxxxx
AUTOMATION_DB_PASSWORD=xxxxxxxxx
AUTOMATION_DB_NAME=xxxxxxx

💡 Best Practices:

Never commit .env files to version control if they contain sensitive information
Use different .env files for different environments (.env.production, .env.staging)
Document required variables in your deployment guide
Use .env.example as a template that can be safely committed to version control

Running with Docker Compose¶

1️⃣ Start

Start the container

docker compose --env-file .env up -d

2️⃣ Logs

View logs

docker compose logs -f Automation

3️⃣ Stop

Stop the container

docker compose down

4️⃣ Backend Logs

Detailed Backend Logs

docker exec -it Automation tail -n 100 /var/log/supervisor/backend.out.log

Database Setup for Docker Deployment

For Docker deployments, ensure your database server is running before starting PyAutomation:

SQLite: No additional setup needed - database file is created automatically in the volume
PostgreSQL/MySQL: You must have a database server running (either in a separate container or external)

Example docker-compose.yml with PostgreSQL:

services:
  postgres:
    image: postgres:15
    container_name: "PostgreSQL"
    environment:
      POSTGRES_DB: automation_db
      POSTGRES_USER: automation_user
      POSTGRES_PASSWORD: your_password
    volumes:
      - postgres_data:/var/lib/postgresql/data
    ports:
      - "5432:5432"

  automation:
    # ... your automation service configuration ...
    depends_on:
      - postgres
    environment:
      # Database connection will be configured through web interface
      # or via API after containers are running

Connection Process: 1. Start the database container: docker compose up -d postgres 2. Wait for database to be ready 3. Start PyAutomation: docker compose up -d automation 4. Connect to PyAutomation web interface and configure database connection 5. PyAutomation will automatically create all tables upon successful connection

✅ Verify Installation¶

🎉 Installation Complete!

Once running, navigate to the following endpoints to verify your installation:

API Documentation: http://localhost:8050/api/docs

Config Wbesite: http://localhost:{AUTOMATION_HMI_PORT}/hmi

Health Check: http://localhost:8050/api/healthcheck/

You should see a JSON response indicating the service is healthy. ✅

🎯 Next Steps: Complete Configuration¶

Ready to Configure PyAutomation?

After successfully installing and starting PyAutomation, you need to configure the system to make it fully operational. The following configuration steps are essential:

💾 Database

Set up database connections for data persistence

🏷️ Tags

Create and configure process variables

🔌 Communications

Configure OPC UA servers and clients

🚨 Alarms

Define alarm conditions and thresholds

📖 Explore User Guide →

For detailed step-by-step instructions on completing these configurations, please refer to the User Guide. The User Guide provides comprehensive documentation on:

Database Configuration: Connecting to SQLite, PostgreSQL, or MySQL databases
Tags Management: Creating, updating, and managing process tags
OPC UA Communications: Setting up OPC UA server and client connections
Alarms Setup: Configuring alarm conditions, thresholds, and states

Follow the User Guide modules in sequence to ensure a complete and properly configured PyAutomation deployment.