Beta
Convoy 5 is in beta. Use it for test installs and to rehearse your upgrade, and keep production panels on Convoy 4 until 5.0 is released.
Convoy 5 is the same panel as Convoy 4, with the same pages, API, and data, packaged differently: it runs from a ready-made container image on Postgres, and one command installs it. You no longer download the source, build containers, or run Composer yourself.
If you already run Convoy 4, don't install from scratch. Follow Upgrading from v4 instead, which carries your data across.
You'll need to be comfortable on a Linux command line: connecting over SSH, running commands as root, and editing a file. Convoy expects a host of its own. It takes ports 80 and 443 and assumes nothing else on the machine uses them.
Compatibility
Operating Systems
These are the systems the installer is tested on. Others that run Docker may work, but we can't help with problems that only happen on them.
Operating System Supported Notes Debian 12 and 13 ✅ Ubuntu 22.04 and 24.04 ✅ AlmaLinux and Rocky Linux 9 and 10 ✅ Proxmox VE ❌ Proxmox's networking interferes with Docker's, which causes confusing network errors in Convoy. Install the panel in a virtual machine instead. Proxmox VE
VE Version Panel Version 7.3-4 and newer v3.x and newer Minimum Hardware Requirements
Notes CPU 2 Core x86_64orarm64. Upgrading from v4 needsx86_64.Memory 2 GiB 4 GiB is recommended. Disk 20 GiB Installing the Panel
Run the installer as root:
Terminalcurl -fsSL https://install.convoypanel.com/5 | sudo bash -s -- --version 5.0.0-beta.1
It asks for two things: the hostname your customers will reach the panel on (such as
panel.example.com), and an email address for the first administrator. Then it installs Docker if it's missing, writes the install to/opt/convoy, installs theconvoycommand, starts the panel, and prints its address with a temporary password:Convoy is installed. URL https://panel.example.com Email [email protected] Password Kd8vQ2mXbR!t7LwPz3Na
Sign in and change that password. It isn't stored anywhere else.
To install without being asked anything, for example from a provisioning script, pass the answers up front:
Terminalcurl -fsSL https://install.convoypanel.com/5 | sudo bash -s -- --version 5.0.0-beta.1 \ --domain panel.example.com --email [email protected] --yes
Choosing a Version
--versiondecides what you install, and the choice is saved, so updating never moves you past it:5.0.0-beta.1installs exactly that release. Until 5.0 is released, this is the only way in.- Once 5.0 is released,
5(the default, when you leave--versionout) follows the newest 5.x release, and5.1follows the newest 5.1.x.
Updating the Panel explains how to change it later.
Securing the Panel with HTTPS
If the hostname you gave the installer is a domain that points at the host, the panel gets a certificate from Let's Encrypt by itself and renews it before it expires. This needs ports 80 and 443 reachable from the internet. If you use Cloudflare or another proxy in front of the domain, turn it off until the first certificate is issued.
If you gave it an IP address instead, the panel uses a self-signed certificate, because certificate authorities don't issue certificates for IP addresses. Browsers will warn on the first visit. To fix it later, point a domain at the host and set it as described in Changing Settings.
Running Behind Your Own Proxy or Load Balancer
If nginx, Nginx Proxy Manager, Cloudflare, or a load balancer already handles HTTPS for the domain, follow Running Behind a Reverse Proxy instead. It takes a few settings in
/opt/convoy/.env, with examples for the common proxies.Changing Settings
Every setting lives in one file,
/opt/convoy/.env. After editing it, apply the change:Terminalconvoy up
This recreates the containers that use the file.
convoy restartis not enough, because a restarted container keeps the settings it started with.To move the panel to a different hostname, change both
APP_DOMAIN(the bare hostname) andAPP_URL(the same hostname withhttps://), then runconvoy up. The panel requests a certificate for the new name.Managing the Panel with the
convoyCommandThe installer adds a
convoycommand for the everyday jobs:convoy ps status of every container convoy logs web follow the panel's logs convoy upgrade back up, update, restart, and check the panel convoy backup save a copy of the database to /opt/convoy/backups convoy artisan <command> run an Artisan command convoy shell open a shell in the panel's container convoy horizon check the queue worker convoy export-activity export the activity log as CSV convoy support send logs to the Convoy team
It's a thin wrapper around Docker Compose. If you already know Docker,
cd /opt/convoyand usedocker composedirectly; nothing breaks.To create another administrator from the command line:
Terminalconvoy artisan users:create
Backing Up the Database
convoy backupsaves a compressed copy of the database to/opt/convoy/backups.convoy upgraderuns it before every update, but nothing runs it on a schedule. To keep a nightly copy, add it to root's crontab:0 3 * * * /usr/local/bin/convoy backup >/dev/null
Copy the backups somewhere off the host as well. Keep
/opt/convoy/.envwith them: itsAPP_KEYis what decrypts the node credentials and two-factor secrets in the database, and a backup without it can't restore those.Deployment FAQ
What if I restart my machine?
The panel starts again by itself once Docker is up. If it doesn't, start it with:
Terminalconvoy up
What is actually running?
Five containers, all defined in
/opt/convoy/compose.yml:Container What it does webServes the panel and handles HTTPS. workerRuns queued jobs. Every action on a server goes through it, so nothing happens on Proxmox without it. schedulerRuns the timed jobs, such as syncing server usage. postgresThe database. redisThe queue, cache, and sessions. The first three run the same image and read the same
.env.Can I use my own database or Redis?
Yes. Point the
DB_andREDIS_settings in/opt/convoy/.envat your servers, then remove thepostgresandredisservices from/opt/convoy/compose.yml, along with thedepends_onblocks that mention them and their entries undervolumes. Apply it withcd /opt/convoy && docker compose up -d --remove-orphans.convoy backuponly covers the bundled database, so back up your own with your provider's tools. Updates leave your editedcompose.ymlalone and save each release's ascompose.yml.new, so compare the two after updating.The panel won't start
Its startup checks stop it on purpose when something is wrong, and say what:
Terminalconvoy logs web
The usual causes are a missing
APP_KEY, anAPP_URLstill set tolocalhost, or a certificate that can't be issued because port 80 isn't reachable or the domain points somewhere else. If the logs don't make it clear, Getting Help explains how to send them to us.