# Sherpa Orchestrator Update Process (Local Version)

### General Update Information

Updating Sherpa Orchestrator includes the following components:

* Application file updates
* Database structure updates
* Node.js dependency updates (if required)
* Service restarts

### Backup Before Update

**Always create backups before updating!**

#### Database Backup

```bash
# Create a database dump
mysqldump -u root -p orchestrator > orchestrator_backup_$(date +%Y%m%d_%H%M%S).sql

# Create a dump of the archive database (if used)
mysqldump -u root -p orchestrator_archive > orchestrator_archive_backup_$(date +%Y%m%d_%H%M%S).sql
```

#### Configuration Files Backup

```bash
# Create a backup of the configuration
cp -r /opt/SherpaOrchestrator/backend/config /opt/SherpaOrchestrator/backend/config_backup_$(date +%Y%m%d_%H%M%S)

# Create a backup of SSL certificates
cp -r /opt/SherpaOrchestrator/backend/config/certs /opt/SherpaOrchestrator/backend/config/certs_backup_$(date +%Y%m%d_%H%M%S)
```

#### Logs and Data Backup

```bash
# Create a backup of the logs
cp -r /opt/SherpaOrchestrator/backend/logs /opt/SherpaOrchestrator/backend/logs_backup_$(date +%Y%m%d_%H%M%S)
```

### Downloading Update Files

```bash
# Navigate to the /opt directory and download the file as in the preparation step
cd /opt

# Download the update archive
orchestrator_local_update_*.tgz
```

### Stopping Services Before Update

```bash
# Stop PM2 processes
sudo pm2 stop all
sudo pm2 delete all

# Stop Nginx
sudo systemctl stop nginx

# Stop PHP-FPM
sudo systemctl stop php8.5-fpm

# Stop MySQL/MariaDB (optional, for complete shutdown)
sudo systemctl stop mariadb
```

### Creating a Backup of the Current Installation

```bash
# Rename the current directory
sudo mv /opt/SherpaOrchestrator /opt/SherpaOrchestrator_backup_$(date +%Y%m%d_%H%M%S)
```

### Extracting and Installing the Update

```bash
# Create a new directory
sudo mkdir /opt/SherpaOrchestrator

# Find and extract the update archive (the latest version is automatically selected)
tar -xvzf "$(ls orchestrator_local_update_*.tgz | sort -V | tail -n 1)"

# Navigate to the application directory
cd /opt/SherpaOrchestrator

# Make scripts executable
sudo find ./*.sh -type f | xargs chmod +x
```

### Restoring Configuration

```bash
# Restore configuration files from backup
sudo cp -r /opt/SherpaOrchestrator_backup_*/backend/config/* /opt/SherpaOrchestrator/backend/config/

# Restore SSL certificates
sudo cp -r /opt/SherpaOrchestrator_backup_*/backend/config/certs/* /opt/SherpaOrchestrator/backend/config/certs/

# Set correct permissions
sudo chown -R www-data:www-data /opt/SherpaOrchestrator
sudo chmod -R 775 /opt/SherpaOrchestrator
```

**Important:** After restoration, check that the database passwords in `backend/config/phinx.php` match those in `config.ini` (the `'pass'` parameter in the `environments` section). Otherwise, migrations during the database update will fail.

### Database Update

```bash
# Check connection settings in phinx.php (passwords must match config.ini)
sudo nano backend/config/phinx.php

# Run database migrations
sudo ./migrate.sh
```

### Updating Node.js Dependencies (if required)

```bash
# Navigate to the websocket directory
cd /opt/SherpaOrchestrator/backend/app/websocket/

# Update dependencies
sudo npm install

# Return to the main directory
cd /opt/SherpaOrchestrator
```

### Starting Services After Update

```bash
# Start MySQL/MariaDB (if stopped)
sudo systemctl start mariadb

# Start PHP-FPM
sudo systemctl start php8.5-fpm

# Start Nginx
sudo systemctl start nginx

# Start WebSocket service
cd /opt/SherpaOrchestrator/backend/app/websocket/
sudo pm2 start index.js --name "Websockets"
sudo pm2 save

# Return to the main directory
cd /opt/SherpaOrchestrator
```

### Checking Functionality After Update

```bash
# Check the status of services
sudo systemctl status nginx
sudo systemctl status php8.5-fpm
sudo systemctl status mariadb

# Check PM2 processes
sudo pm2 list
sudo pm2 logs Websockets --lines 20

# Check the availability of the web interface
curl -I https://your-domain-or-ip

# Check Nginx logs for errors
sudo tail -f /var/log/nginx/error.log
```

### Cleanup After Successful Update

```bash
# After successful testing, delete old backups
# (only perform after confirming functionality!)

# Remove old update files
rm -f /opt/orch_local_update_*.tgz

# Remove old backups (if confident in functionality)
# rm -rf /opt/SherpaOrchestrator_backup_*
```

### Possible Issues During Update

#### Database Issues

* Check the correctness of settings in `config.ini` and `phinx.php`
* Ensure the database user has sufficient privileges
* Check migration logs

#### Web Server Issues

* Check Nginx configuration syntax: `sudo nginx -t`
* Check logs: `/var/log/nginx/error.log`
* Check paths to PHP-FPM socket

#### WebSocket Issues

* Check PM2 logs: `sudo pm2 logs Websockets`
* Check Node.js dependencies: `npm list`
* Check port availability

#### Rollback on Failed Update

If the update fails:

```bash
# Stop all services
sudo pm2 stop all
sudo systemctl stop nginx php8.5-fpm

# Restore from backup
sudo rm -rf /opt/SherpaOrchestrator
sudo mv /opt/SherpaOrchestrator_backup_* /opt/SherpaOrchestrator

# Restore permissions
sudo chown -R www-data:www-data /opt/SherpaOrchestrator
sudo chmod -R 775 /opt/SherpaOrchestrator

# Start services
sudo systemctl start php8.5-fpm nginx
cd /opt/SherpaOrchestrator/backend/app/websocket/
sudo pm2 start index.js --name "Websockets"
```

### Update Recommendations

1. **Always make backups** before updating
2. **Test the update** in a testing environment, if possible
3. **Update during off-hours** to minimize downtime
4. **Document the update process** for your team
5. **Check logs** after the update for errors


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.sherparpa.ru/en/sherpa-rpa/sherpa-orchestrator/ustanovka-sherpa-orchestrator/bez-ispolzvaniya-docker/process-obnovlenie-sherpa-orchestrator-lokalnaya-versiya.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.