Deploying October CMS with the Deploy Plugin

Tutorial

Published on Sep 22, 2022 · Updated on Nov 8, 2026

# Deploying October CMS with the Deploy Plugin

If you don't have SSH access to the server or can't run Composer commands for any reason, you can deploy an October CMS project using the official [Deploy plugin](https://octobercms.com/plugin/rainlab-deploy). It suits hosting where shell access is limited, such as shared hosting, and it can also upgrade or repair an installation without command line access.

## How It Works

The Deploy plugin uses a local installation of October CMS to run Composer commands on your own computer. The locally generated files are deployed to your server based on this installation.

The plugin creates a secure channel between your local developer environment and your hosting server. Plugins, themes and core files are compressed and sent securely to your server, and then installed remotely. This approach is similar to an update gateway, except files are pushed to the server instead.

From there, October CMS has a one-click updater that can be used to update the installation directly on the server. If the one-click update fails, the Deploy plugin can be used to repair the installation without command line access.

For safety, the Deploy plugin never deletes files. It only overwrites and creates files, so if you need to delete something, do it directly on the server.

[Watch the Deploy Tutorial](https://www.youtube.com/watch?v=Lx9X3CfXwfw) to see how to deploy your project to a remote server without Composer.

## Requirements

- October CMS 4.0 or above
- PHP cURL extension
- PHP openssl extension
- PHP eval function

The plugin is an official extension of the October CMS platform and is free to use if you have a platform license.

Before starting, set up a new site in your hosting manager, ideally with an empty database. You can also apply these instructions to an existing website, including legacy versions of October CMS, but make sure you have taken a complete backup in case something goes wrong.

## Installing the Plugin

Install the plugin on your local October CMS installation.

```bash
php artisan plugin:install rainlab.deploy
```

## Setting Up the Server

In the admin panel of your local installation, navigate to **Settings → Deploy** and click **Create Server**.

1. Enter the web address for your site, for example `https://mycpanelwebsite.tld/`.
2. Generate a new RSA private key, or enter an existing one to set up an existing server.
3. Download the Beacon ZIP files.

## Uploading the Beacon

The Beacon ZIP file contains the following files:

- index.php
- bootstrap/app.php
- bootstrap/autoload.php
- bootstrap/beacon.php

You can upload these files anywhere on your server, using FTP or the file manager in your hosting control panel, and that location becomes a target for deploying October CMS.

> **Warning**: The directory where the files are uploaded must be writable by your web server (for example, permission 755 for Apache).

## Running Your First Deployment

Once the Beacon is installed remotely and the server is set up locally, you are ready to perform your first deployment from **Settings → Deploy**, or from the command line with the `deploy:server` command described below.

## Troubleshooting the Beacon

Sometimes you may see an error that a valid response from a beacon was not found.

First, use the **Check Beacon** link to make sure the beacon is **Active**. If it says **Unreachable**, try downloading the beacon files and uploading them to your server again.

For more advanced troubleshooting, capture the raw response from the server or beacon:

1. Add `?debug=1` to the end of the URL in the backend.
2. Click **Check Beacon** or perform the deployment action again.
3. Check the log file in **storage/logs** to see what the server is responding with.

## Console Commands

The Deploy plugin provides console commands as an alternative to the backend interface. They are useful for automating deployments, or when building large archives (such as vendor packages) that may time out in the browser.

Use the `deploy:list` command to see all configured deployment servers.

```bash
php artisan deploy:list
```

Use the `deploy:test` command to check if a server's beacon is reachable. The server can be specified by name or ID.

```bash
php artisan deploy:test "My Server"
php artisan deploy:test 1
```

Use the `deploy:build` command to build deployment archives locally without transmitting them. This is useful for verifying that large archives, especially vendor packages, can be built successfully.

```bash
php artisan deploy:build --vendor
php artisan deploy:build --core --config
php artisan deploy:build --all
php artisan deploy:build --plugins=Acme.Blog --plugins=Acme.Pages
php artisan deploy:build --themes=demo
php artisan deploy:build --all --output=/path/to/output
```

Use the `deploy:server` command to perform a full deployment to a remote server. This mirrors the deployment workflow available in the backend interface.

```bash
php artisan deploy:server "My Server" --all
php artisan deploy:server "My Server" --core --config
php artisan deploy:server "My Server" --plugins=Acme.Blog --themes=demo
php artisan deploy:server "My Server" --all --force
```

If no options are specified, the command prompts interactively for what to deploy.

```bash
php artisan deploy:server "My Server"
```

## Ignoring Files with .deployignore

To keep specific files out of a deployment, such as the `node_modules` directory used in plugins and themes, create a `.deployignore` file in the base directory of the plugin or theme. It works the same as a `.gitignore` file.

The following `.deployignore` file excludes the **node_modules** directory. This is also the default when no file exists.

```
node_modules/
```

The file must be located in the base directory of the theme or plugin, for example:

- **themes/demo/.deployignore**
- **plugins/acme/demo/.deployignore**

## Upgrading Older Versions of October CMS

The Deploy plugin can also upgrade a website to a newer version of October CMS, for example from v1 to v2. Always **take a complete site backup** before performing these steps.

1. Install or upgrade to the latest October CMS version locally on your machine.
2. Deploy the Beacon files to the older site you want to upgrade.
3. The Deploy plugin attempts to upgrade the site during its first deployment.

If you need support with this process, [send an email to the helpdesk](https://octobercms.com/contact).

## See Also

- [Deployment](https://docs.octobercms.com/4.x/setup/deployment.html)
- [Production Configuration](https://docs.octobercms.com/4.x/setup/configuration.html#production-configuration)
- [Installation](https://docs.octobercms.com/4.x/setup/installation.html)
- [Deploy Plugin](https://octobercms.com/plugin/rainlab-deploy)
- [Installing October CMS with DDEV](https://octobercms.com/support/article/installing-october-cms-with-ddev)
- [Installing October CMS with Laravel Sail](https://octobercms.com/support/article/installing-october-cms-with-laravel-sail)
- [Installing October CMS with Laragon](https://octobercms.com/support/article/installing-october-cms-with-laragon)

On this page

How It Works
Requirements
Installing the Plugin
Setting Up the Server
Uploading the Beacon
Running Your First Deployment
Troubleshooting the Beacon
Console Commands
Ignoring Files with .deployignore
Upgrading Older Versions of October CMS
See Also

If you don't have SSH access to the server or can't run Composer commands for any reason, you can deploy an October CMS project using the official Deploy plugin. It suits hosting where shell access is limited, such as shared hosting, and it can also upgrade or repair an installation without command line access.

How It Works

The Deploy plugin uses a local installation of October CMS to run Composer commands on your own computer. The locally generated files are deployed to your server based on this installation.

For safety, the Deploy plugin never deletes files. It only overwrites and creates files, so if you need to delete something, do it directly on the server.

Watch the Deploy Tutorial to see how to deploy your project to a remote server without Composer.

Requirements

October CMS 4.0 or above
PHP cURL extension
PHP openssl extension
PHP eval function

The plugin is an official extension of the October CMS platform and is free to use if you have a platform license.

Installing the Plugin

Install the plugin on your local October CMS installation.

php artisan plugin:install rainlab.deploy

Setting Up the Server

In the admin panel of your local installation, navigate to Settings → Deploy and click Create Server.

Enter the web address for your site, for example https://mycpanelwebsite.tld/.
Generate a new RSA private key, or enter an existing one to set up an existing server.
Download the Beacon ZIP files.

Uploading the Beacon

The Beacon ZIP file contains the following files:

index.php
bootstrap/app.php
bootstrap/autoload.php
bootstrap/beacon.php

You can upload these files anywhere on your server, using FTP or the file manager in your hosting control panel, and that location becomes a target for deploying October CMS.

Warning: The directory where the files are uploaded must be writable by your web server (for example, permission 755 for Apache).

Running Your First Deployment

Once the Beacon is installed remotely and the server is set up locally, you are ready to perform your first deployment from Settings → Deploy, or from the command line with the deploy:server command described below.

Troubleshooting the Beacon

Sometimes you may see an error that a valid response from a beacon was not found.

First, use the Check Beacon link to make sure the beacon is Active. If it says Unreachable, try downloading the beacon files and uploading them to your server again.

For more advanced troubleshooting, capture the raw response from the server or beacon:

Add ?debug=1 to the end of the URL in the backend.
Click Check Beacon or perform the deployment action again.
Check the log file in storage/logs to see what the server is responding with.

Console Commands

Use the deploy:list command to see all configured deployment servers.

php artisan deploy:list

Use the deploy:test command to check if a server's beacon is reachable. The server can be specified by name or ID.

php artisan deploy:test "My Server"
php artisan deploy:test 1

Use the deploy:build command to build deployment archives locally without transmitting them. This is useful for verifying that large archives, especially vendor packages, can be built successfully.

php artisan deploy:build --vendor
php artisan deploy:build --core --config
php artisan deploy:build --all
php artisan deploy:build --plugins=Acme.Blog --plugins=Acme.Pages
php artisan deploy:build --themes=demo
php artisan deploy:build --all --output=/path/to/output

Use the deploy:server command to perform a full deployment to a remote server. This mirrors the deployment workflow available in the backend interface.

php artisan deploy:server "My Server" --all
php artisan deploy:server "My Server" --core --config
php artisan deploy:server "My Server" --plugins=Acme.Blog --themes=demo
php artisan deploy:server "My Server" --all --force

If no options are specified, the command prompts interactively for what to deploy.

php artisan deploy:server "My Server"

Ignoring Files with .deployignore

To keep specific files out of a deployment, such as the node_modules directory used in plugins and themes, create a .deployignore file in the base directory of the plugin or theme. It works the same as a .gitignore file.

The following .deployignore file excludes the node_modules directory. This is also the default when no file exists.

node_modules/

The file must be located in the base directory of the theme or plugin, for example:

themes/demo/.deployignore
plugins/acme/demo/.deployignore

Upgrading Older Versions of October CMS

The Deploy plugin can also upgrade a website to a newer version of October CMS, for example from v1 to v2. Always take a complete site backup before performing these steps.

Install or upgrade to the latest October CMS version locally on your machine.
Deploy the Beacon files to the older site you want to upgrade.
The Deploy plugin attempts to upgrade the site during its first deployment.

If you need support with this process, send an email to the helpdesk.