# Updating

***

## One Command Update (Recommended)

{% hint style="info" %}
**Command Name Update (v0.6+):** Starting with version 0.6, this command is now `pteroca:system:update`. The old name `app:update-system` is deprecated but still works until v1.0.0.

**Version Requirement:** This command is available starting from **version 0.4.3**. If you are on an earlier version, you'll need to follow the [manual update instructions](#manual-update) first before you can use this command.
{% endhint %}

Updating your PteroCA installation has never been easier. Simply run the following command inside your project directory:

```bash
# Recommended (v0.6+)
php bin/console pteroca:system:update

# Deprecated (still works until v1.0.0)
# php bin/console app:update-system
```

This command automates the most common update steps for you by:

* Pulling the latest version of the code (if applicable).
* Installing and updating dependencies (Composer, etc.).
* Running any necessary database migrations.
* Adjusting file permissions for your web server, if needed.

**Optional:** After running the update, you may also [update the Pterodactyl plugin](#updating-pterodactyl-plugin-optional) by following any specific instructions outlined in its documentation or by running the relevant update command.

***

## Manual Update

If you need more control over the update process, you can manually update PteroCA. Choose the method that matches your installation approach:

***

### Option A - Update via Git

{% hint style="info" %}
This method is for installations that were set up using Git. If you installed from a GitHub release archive, use [Option B](#option-b-update-from-github-releases) instead.
{% endhint %}

Ensure that your local repository is synchronized with the latest versions while preserving any local changes.

```bash
git stash            # Save local modifications
git pull             # Fetch and merge latest changes from the remote repository
git stash apply      # Reapply the stashed changes
```

***

### Option B - Update from GitHub Releases

{% hint style="info" %}
**When to use this method:**

This update method is for users who installed PteroCA using [Option B from the Manual Installation guide](https://docs.pteroca.com/installation/installation/manual-installation#option-b-download-from-github-release), or when Git is not available on your server.

If you installed via Git (Option A), use the [Git-based update method](#option-a-update-via-git) instead.
{% endhint %}

{% hint style="warning" %}
**Backup Recommendation:**

Before updating, it's highly recommended to create a backup of your current installation, especially your `.env` file and database. This allows you to restore your system if something goes wrong during the update.
{% endhint %}

If you installed PteroCA from a GitHub release archive (without Git), follow these steps to update to the latest version:

1. **Visit the releases page:** Navigate to <https://github.com/PteroCA-Org/panel/releases> and identify the latest stable version.
2. **Download the latest release:** Download the `.zip` or `.tar.gz` archive under **Assets** for the version you want to update to.
3. **Upload to your server:** Transfer the downloaded archive to your server using SFTP, SCP, or your preferred method.
4. **Backup your configuration (optional but recommended):**

   ```bash
   # Create a backup of your .env file
   cp /var/www/pteroca/.env /var/www/pteroca/.env.backup

   # Optionally backup the entire installation directory
   tar -czf /var/backups/pteroca-backup-$(date +%Y%m%d).tar.gz -C /var/www pteroca
   ```
5. **Extract the new files:** Navigate to your PteroCA directory and extract the archive, overwriting existing files:

   ```bash
   cd /var/www/pteroca

   # For .tar.gz:
   tar -xzf /path/to/pteroca-release.tar.gz --strip-components=1

   # For .zip:
   unzip -o /path/to/pteroca-release.zip -d .
   ```
6. **Verify configuration files:** Ensure your `.env` file and other custom configuration files were not overwritten:

   ```bash
   # Check that your .env file is still present and correct
   cat .env | grep APP_SECRET
   ```

After extracting the files, proceed with the following shared update steps below.

***

### Managing Project Dependencies

Regular updates to dependencies are critical for maintaining compatibility and performance. This includes removing development-only packages and optimizing the autoloader.

```bash
composer install --no-dev --optimize-autoloader    # Update and optimize production dependencies
```

***

### Database Migration

To align your database schema with the latest project updates, perform a migration using the framework's built-in tools.

```bash
php bin/console doctrine:migration:migrate    # Execute new database migrations
```

***

### Refreshing the Cache

Post-update, clearing the cache is essential to prevent old data from affecting the functionality of the updated system.

```bash
php bin/console cache:clear    # Clear system cache to ensure fresh data usage
```

***

### Adjusting File Permissions

Correct file permissions are essential for secure and uninterrupted operation of the server environment, especially after updates that might alter file structures.

```bash
# NGINX or Apache on Ubuntu/Debian (or similar):
chown -R www-data:www-data /var/www/pteroca/var/ /var/www/pteroca/public/uploads/

# NGINX on CentOS:
chown -R nginx:nginx /var/www/pteroca/var/ /var/www/pteroca/public/uploads/

# Apache on CentOS:
chown -R apache:apache /var/www/pteroca/var/ /var/www/pteroca/public/uploads/
```

***

## Updating Pterodactyl Plugin (Optional)

If you have installed the [PteroCA Plugin for Pterodactyl](https://docs.pteroca.com/core-configuration/pterodactyl-integration/addon-installation), you may want to update it as well.

Navigate to your Pterodactyl directory and simply run the following command to update the Composer package:

```
composer update pteroca-com/pterodactyl-addon
```

This command will update the PteroCA Plugin package and ensure that everything continues to work smoothly.

***

## Troubleshooting Update Issues

### `pteroca:system:update` Fails

If the update command exits with an error (e.g. during cache clearing, migrations, or dependency installation), follow these manual recovery steps from the PteroCA project root:

**1. Pull the latest code:**

```bash
git pull
```

**2. Update dependencies:**

```bash
composer install --no-dev --optimize-autoloader
```

**3. Run database migrations:**

```bash
php bin/console doctrine:migration:migrate
```

**4. Clear the cache:**

```bash
php bin/console cache:clear
```

**5. Fix file permissions if needed:**

```bash
chown -R www-data:www-data /var/www/pteroca/var/ /var/www/pteroca/public/uploads/
```

***

### Errors or 500 Pages After Update

If the panel shows errors immediately after a successful update, the most common cause is a stale cache or an incomplete schema refresh. Try clearing the cache first:

```bash
php bin/console cache:clear
```

If the error persists, also run migrations to ensure the database schema is up to date:

```bash
php bin/console doctrine:migration:migrate
php bin/console cache:clear
```

If the issue remains, check `var/log/prod.log` for the specific error and refer to [Runtime Issues](https://docs.pteroca.com/help-and-maintenance/troubleshooting/runtime-issues) for further guidance.

***

## Need help? Join our Discord!

If you encounter any issues or need assistance, feel free to join our **Discord community**, where we’ll be happy to help! 🚀

🔗 [**Join here!**](https://discord.com/invite/Gz5phhuZym)