Skip to content
On this page

Deploying Convoy


Convoy is not free software. Production use of Convoy is prohibited. You will need an active subscription or explicit permission from Performave.


  • Basic knowledge about Docker commands, specifically Docker compose.
    • docker compose build
    • docker compose up -d
      • add a --build flag to combine the first and second command.
    • docker compose down
    • docker compose restart
    • docker compose stop <container>
  • Basic Convoy maintenance commands
    • Clear cache - docker compose exec workspace php artisan optimize:clear
    • Cache - docker compose exec workspace php artisan optimize


Supported Operating Systems


Do not install Convoy in a container. If you can't install Convoy on bare metal, use KVM but please do not install Convoy in a container.

Operating SystemSupportedNotes
Debian 11This OS is known to have issues with Convoy, including resource hogging to the point that the system freezes, networking issues, etc.
Ubuntu 20.04
Ubuntu 22.04The development server for Convoy runs on Ubuntu, so it's known to work
Proxmox VEDocker, which Convoy relies on, doesn't work properly on the host Proxmox system

Supported Proxmox Versions

ProxmoxVE VersionConvoy VersionNotes
7.2-7 & 7.3-4v1.1.0-beta to v2.0.3-beta
7.3-4 & laterv3.0.0-beta & later

Minimum System Requirements

CPU2 Core
Memory4 GiBSwap also works but not recommended
Disk10 GiB

Install Docker


We do not provide support for methods of deployment other than our official Docker configuration.


Do not install Convoy/Docker on your host Proxmox system. This includes even containers as it's not complete isolation from the Proxmox OS. If you install Convoy in a KVM container in Proxmox, make sure it doesn't have Cloudinit installed because anything can interfere with Docker's networking.

Convoy uses Docker for everything. The source code comes with a Docker configuration that will ensure that everything works.

curl -fsSL | sh


Make sure Docker installed correctly with ZERO error messages. Do not proceed if the command above resulted in a non-zero exit code, install Docker manually. For example, if you are using Ubuntu, you can try this official guide from Docker

Download Files

First, create the folder where the panel will be stored in and change your current directory to that newly created folder.

mkdir -p /var/www/convoy
cd /var/www/convoy

Once you've created the directory and moved into it, you'll need to download the panel. Then, you'll need to unpack the archive. Next, you'll need to set the correct permissions on the storage/ and bootstrap/cache/ directories.

curl -Lo panel.tar.gz
tar -xzvf panel.tar.gz
chmod -R o+w storage/* bootstrap/cache/


If you receive file permission errors like in this picture, try running docker compose exec workspace chmod -R o+w storage/* bootstrap/cache/


Now you have all the files, it's time to configure Convoy.

First, we'll create a copy a new environment file.

cp .env.example .env

Environment Configuration

First up, let's configure the display information and where this panel will be hosted. To determine what to use for APP_URL, first determine where you are hosting this panel. If you are hosting it on your IP address or locally, leave it as http://localhost. If you are hosting it on a domain, put Additionally, if you want SSL automatically generated, replace http:// with https:// and make sure that your domain points to the IP address that's hosting Convoy. Please note that automatic SSL does not work with Cloudflare proxy.


Next, we'll need to add credentials for the DB_DATABASE, DB_USERNAME, DB_PASSWORD, and DB_ROOT_PASSWORD fields. You can define alphanumeric values or have a combination of special characters too. If you want to use any special characters at all, you have to wrap the value in single quotation marks. Also, set the DB_USERNAME field anything other than root or else your database won't start. In addition, you have to define a DB_ROOT_PASSWORD too for your database to start. Finally, leave DB_HOST as is.

DB_PASSWORD='Use special characters by wrapping the password with quotation marks :)'

After, we need to configure the cache driver, queue driver, and the session driver for authorization.


Now, we need to configure the Redis server that'll store key value pairs in its in-memory storage, which provides performance benefits especially if you want low latency requests. Also note again, if you want to use special characters on top of alphanumeric characters, you have to wrap the value in single quotation marks. Finally, leave REDIS_HOST and REDIS_PORT as is.


Building the Dockerfiles

Awesome! You've completed the configuration step of deploying Convoy. Next, we need to build the Docker images that'll run Convoy.

docker compose up -d


If you come across errors like "unable to locate package" like this, then make sure your host system has updated package lists and is connected to the internet. Also, check if this is an issue with your network or DDoS provider. Combahton DDoS protection is known to have issues.

Installing & Building Dependencies

We now have to install the core dependencies that Convoy depends on.

docker compose exec workspace bash -c "composer install --no-dev --optimize-autoloader && \
                                       npm install && \
                                       npm run build"

Setting an Application Key

We also have to generate an application key for Convoy. This key will be used for password hashes and other parts of Convoy that depends on cryptography. This command will also cache the current configuration for performance improvements. If any changes are ever made to Convoy, either the code or any configuration, it's good to rerun php artisan optimize to make sure the new values are cached.

# Only run the command below if you are installing this panel for
# the first time and do not have any data in the database.
docker compose exec workspace bash -c "php artisan key:generate --force && \
                                       php artisan optimize"


Back up your encryption key (APP_KEY in the .env file). It is used as an encryption key for all data that needs to be stored securely (e.g. api keys). Store it somewhere safe - not just on your server. If you lose it all encrypted data is irrecoverable -- even if you have database backups.

Database Setup

Now we need to scaffold the tables for Convoy in the database. The command below may take a while to run depending on your machine. Please do not exit the process until it is completed.

docker compose exec workspace php artisan migrate --force

Preparing for Production


Make sure to check if Convoy is running properly by visiting the panel in your browser before preparing for production as you will not get any debug information in production.

Go back in your .env file you've copied while following the steps for Environment Configuration. Edit APP_ENV and APP_DEBUG. Making the following changes for APP_ENV will enable caching in PHP-FPM to serve requests faster. Editing APP_DEBUG will disable verbose error messages from emitting (it's also for security purposes as sometimes these verbose logs will dump your environment file).


Then, rebuild the Dockerfiles and fully restart the containers.

docker compose build
docker compose down
docker compose up -d

Adding a User

docker compose exec workspace php artisan c:user:make


What happens if I restart the machine running Convoy?

Convoy is configured to automatically start up upon reboots or from any crashes the application may encounter. In case if it doesn't restart, run the following commands to bring up the Docker containers.

cd /var/www/convoy
docker compose up -d

My performance isn't as expected

If Convoy isn't able to keep up with the demand of your users, you can try tweaking the settings of PHP-FPM. In /var/www/convoy/dockerfiles/php/Dockerfile, there is this specific line below. Tweak 100 to any number. This number dictates how many concurrent requests PHP-FPM can handle. We don't recommend putting a million or a sextillion because in times of heavy traffic, Convoy can consume too many resources and crash your system.

RUN echo 'pm.max_children = 100' >> /usr/local/etc/php-fpm.d/zz-docker.conf

You can also tweak the PHP OPCache settings that will provide performance improvements for both heavy traffic and even light traffic—by decreasing the latency of each request. I'd recommend searching how to optimize PHP OPCache on Google and make sure the article was posted in the last two years (and not 7 years). Then, you can tweak the OPCache settings in /var/www/convoy/dockerfiles/php/php.ini-production or /var/www/convoy/dockerfiles/php/php.ini-development if your APP_ENV is set to local.

After you make the necessary changes, you can make them live with the following commands.

docker compose build
docker compose up -d

My changes in the .env or environment file isn't going live or persisting

If you made changes to your environment file, Convoy won't pick it up until the configuration cache is cleared. Run the commands below to recache the configuration.

docker compose exec workspace bash -c "php artisan optimize:clear && \
                                       php artisan optimize"

Created by Eric Wang