# 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](/installation/installation/manual-installation.md#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](/core-configuration/pterodactyl-integration/addon-installation.md), 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](/help-and-maintenance/troubleshooting/runtime-issues.md) 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)


---

# 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.pteroca.com/help-and-maintenance/updating.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.