Installing Pythmata¶

This guide walks you through the process of installing and setting up Pythmata for local development.

Prerequisites¶

Python 3.11 or higher
Node.js 18 or higher
Docker and Docker Compose
Git

System Requirements¶

Memory: 4GB RAM minimum, 8GB recommended
Storage: 1GB free space
OS: Linux, macOS, or Windows with WSL2

Installation Steps¶

1. Clone the Repository¶

git clone https://github.com/yourusername/pythmata.git
cd pythmata

2. Environment Setup¶

Backend Setup¶

Install Poetry (Python dependency manager):

curl -sSL https://install.python-poetry.org | python3 -

Install backend dependencies:
```
cd backend
poetry install
```

Set up environment variables:

cp .env.example .env
# Edit .env with your configuration

Frontend Setup¶

Install frontend dependencies:
```
cd frontend
npm install
```

Set up environment variables:

cp .env.example .env
# Edit .env with your configuration

3. Database Setup¶

Start the required services using Docker Compose:

docker-compose up -d postgres redis rabbitmq

Run database migrations:

cd backend
poetry run alembic upgrade head

Running the Application¶

Development Mode¶

Start the backend server:

cd backend
poetry run uvicorn pythmata.main:app --reload

Start the frontend development server:
```
cd frontend
npm run dev
```

The application will be available at: - Frontend: http://localhost:3000 - Backend API: http://localhost:8000 - API Documentation: http://localhost:8000/docs

Docker Deployment¶

To run the entire application using Docker:

docker-compose up -d

This will start: - Frontend on http://localhost:3000 - Backend on http://localhost:8000 - PostgreSQL on localhost:5432 - Redis on localhost:6379 - RabbitMQ on localhost:5672 (Management: 15672)

Extending with Plugins¶

Pythmata supports a plugin system that allows you to extend the workflow engine with custom service tasks.

Creating a Plugin¶

Create a directory for your plugin in the plugins directory:
```
mkdir -p plugins/my_plugin
```

Create the necessary files:

# Service task implementation
touch plugins/my_plugin/my_task.py

# Plugin initialization
touch plugins/my_plugin/__init__.py

# Optional dependencies
touch plugins/my_plugin/requirements.txt

Implement your service task and register it in the __init__.py file.

For detailed instructions, see the Custom Service Tasks documentation.

Using Plugins with Docker¶

When using Docker, plugins are automatically discovered and loaded from the plugins directory. The plugin directory is mounted as a volume in the Docker container:

volumes:
  - ./plugins:/app/plugins

Plugin dependencies are automatically installed at startup if the PYTHMATA_INSTALL_PLUGIN_DEPS environment variable is set to true.

Verification¶

Check service health:
```
curl http://localhost:8000/health
```
Access the frontend:
Open http://localhost:3000 in your browser
You should see the Pythmata dashboard
Verify API documentation:
Open http://localhost:8000/docs in your browser
You should see the Swagger UI documentation

Common Issues¶

Database Connection¶

If you encounter database connection issues: 1. Ensure PostgreSQL is running:

docker-compose ps

2. Check database credentials in .env 3. Verify database migrations are up to date

Redis Connection¶

If Redis connection fails: 1. Verify Redis is running:

docker-compose ps

2. Check Redis connection settings in .env 3. Ensure Redis port is not in use

Frontend Build Issues¶

If you encounter frontend build problems: 1. Clear node_modules and reinstall:

cd frontend
rm -rf node_modules
npm install

2. Verify Node.js version compatibility 3. Check for environment variable configuration

Next Steps¶

After successful installation: 1. Review the Basic Concepts Guide 2. Explore Example Workflows

Support¶

If you encounter any issues: 1. Check our GitHub Issues 2. Search existing GitHub issues 3. Create a new issue with: - Detailed description - Environment information - Steps to reproduce - Error messages/logs