This article contains step-by-step instructions for updating MikoPBX to a newer version.
Updating MikoPBX installed on a virtual machine
We recommend updating sequentially, without skipping releases and versions.
This guide is intended for MikoPBX installed as a full-fledged virtual machine in VMware, VirtualBox, Hyper-V, KVM, Proxmox VE, and other hypervisors.
Two update methods are available for this type of installation:
through the web interface — the primary and most convenient method;
from an ISO image — a fallback method if the web interface is unavailable or the system needs to be recovered.
Before updating, be sure to create a backup of the MikoPBX settings. Additionally, it is recommended to create a virtual machine snapshot using the hypervisor's tools.
Make sure you have access to the web interface and the virtual machine console. Create a backup of the MikoPBX settings and call recordings.
Create a virtual machine snapshot. If the hypervisor allows, take it with the virtual machine powered off.
Make sure at least 400 MB is free on the system disk.
Schedule a maintenance window: during the update, MikoPBX will reboot, and current calls will be dropped.
Open the MikoPBX web interface.
Go to Maintenance → PBX update.
In the "Online updates available" table, find the version you need. Review the list of changes and click the update button next to the selected version.
Wait for the image to download. Do not close the page until the confirmation dialog appears. Enter the phrase "Yes, I have a backup". Click Update.
MikoPBX will prepare the update and reboot the virtual machine automatically.
This method is suitable if the required version is not in the list of online updates or the file has already been downloaded in advance.
Download the .img file of the required version from the page.
In the web interface, open Maintenance → PBX update.
In the file selection field, specify the downloaded .img.
Click Apply update.
Enter the phrase "Yes, I have a backup". Confirm the update and wait for the reboot.
Use this option if the PBX does not boot normally, the web interface is unavailable, or you need to perform the update from Recovery mode.
Download the ISO image of the required version from the page.
Power off the virtual machine. In the hypervisor settings, connect the ISO to the virtual CD/DVD drive and set booting from the virtual CD/DVD before the system disk.
Start the virtual machine and open its console.
Wait for the message about booting in recovery mode — System booted in recovery mode (Live CD).
Press any key to open the console menu. Then open "[4] Install or recover".
Select "Update to version..."
After the operation is complete:
Power off the virtual machine if the ISO was not disconnected automatically.
Disconnect the ISO from the virtual drive.
Restore booting from the system disk as the first boot device.
Start the virtual machine.
Do not power off the virtual machine and do not perform a forced reset while the update is being written.
Do not select the Install option. It starts a new installation and warns that data on the selected disk will be erased. To update while keeping the settings, use the Update to version... option.
Updating MikoPBX in a Proxmox VE LXC container without copying call recordings
This guide is intended for MikoPBX installed in a Proxmox VE LXC container. All operations are performed through the Proxmox and MikoPBX web interfaces.
We recommend updating sequentially without skipping releases or versions. If a release description specifies an intermediate version, update to that version first.
In LXC, the MikoPBX system files and user data are stored on separate volumes:
Root Disk
To update, create a new container from the current lxc.tar.gz template. The existing /storage and /cf volumes are not copied: Proxmox reassigns them to the new container using Reassign Owner.
As a result, the new MikoPBX version gets a new root file system while continuing to use the existing settings, history, and call recordings.
Schedule a maintenance window. After the old CT is stopped, telephony will remain unavailable until the new container starts.
Make sure you have:
administrator access to Proxmox VE;
administrator access to MikoPBX;
a backup stored outside the container being updated.
Open the old CT in Proxmox and record its settings.
Resources — CPU, RAM, Swap, and Root Disk size.
Network — bridge, IPv4/IPv6, VLAN, MAC address, and Proxmox Firewall status.
DNS — DNS servers.
Options — whether the container is privileged or unprivileged.
Under Resources, find the entries containing:
mp=/storage — the volume with recordings and user data;
mp=/cf — the volume with the configuration.
Record their identifiers. They are usually mp0 and mp1, but the order may differ.
Open Modules → Module marketplace.
Make sure the is installed and enabled.
Open the module and click Create backup copy.
Create the archive and download it to the administrator's computer or external storage.
In Proxmox, open the old container (CT) → Backup and click Backup now.
Select external or separate backup storage. Start the backup and wait for the TASK OK message.
Open the page.
Find the required version and copy the link to the file whose name ends with lxc.tar.gz.
In Proxmox, select the local storage → CT Templates and click Download from URL.
Paste the link into the URL field and click Query URL. Verify the file name and click Download.
Wait for the TASK OK message.
Click Create CT in the upper-right corner of Proxmox.
Select the same Proxmox node that hosts the old CT:
Specify a new CT ID. Do not use the ID of the old container.
Enter a different name, such as mikopbx-update-test.
Set Unprivileged container to the same value as on the old CT.
Click Next.
Select the downloaded lxc.tar.gz template for the new version and click Next.
Create a new Root Disk (rootfs). Select suitable storage and set the system disk size to 1 GB.
Click Next.
Specify the same number of CPU cores and the same Memory and Swap values as on the old container.
Reproduce the network settings of the old CT. For testing, we recommend using an available temporary IP address and a new MAC address to avoid a conflict with the old container.
If DHCP is used, the new CT may obtain a different address automatically. If the DHCP server reserves the address by MAC address, create a separate reservation for the new MAC address in advance.
Reproduce the DNS settings of the old CT:
Carefully review the settings on the Confirm page.
Clear the Start after created checkbox. The new container must not be started before /cf and /storage are attached. Click Finish and wait for the TASK OK message.
Open the new CT → Resources. At this stage, the list must contain the new Root Disk, but it must not contain /cf or /storage mount points.
Open the old CT → Resources. Select the Mount Point entry whose settings contain mp=/storage. Click Volume Action → Reassign Owner.
In the Target field, select the new CT. Leave Mount Point selected in the Add as field. Proxmox suggests an available mount point number, such as mp0. Make sure the selected number is not already in use.
Click Reassign Volume.
After the operation, the volume disappears from the old CT's Resources section and appears under the new CT. Proxmox changes the volume owner and, if necessary, renames it for the new CT ID. The contents of the disk are neither copied nor formatted.
Repeat the same procedure for the Mount Point whose settings contain mp=/cf:
Open the old CT → Resources. Select the Mount Point entry whose settings contain mp=/cf. Click Volume Action → Reassign Owner.
Select the new CT. Leave Add as → Mount Point selected. Choose the next available number, such as mp1, and click Reassign Volume.
Open the new CT → Resources and check the final configuration:
Root Disk belongs to the new CT;
one Mount Point contains mp=/storage;
the other Mount Point contains mp=/cf;
The mp0 and mp1 numbers may be in a different order. The mp=/storage and mp=/cf paths are what matter.
Select the new CT and click Start. Open the Console tab.
Wait for MikoPBX to finish booting and display the web interface address.
Open this address in a browser and sign in with the previous MikoPBX login and password.
If the new CT received the previous production IP address immediately, skip this step.
If a temporary address was used for testing:
Stop the new CT.
Make sure once again that the old CT is stopped.
Open the new CT → Network and select the net0 interface.
Enter the previous MikoPBX IPv4/IPv6 address.
The same IP or MAC address may be used only when the old container is completely stopped.
Do not delete the old CT until all checks have been completed.
Verify in the web interface that the new MikoPBX version is displayed.
Check the extensions, SIP accounts, providers, and inbound and outbound routes.
Open Telephony → Call history and make sure the previous call history is available.
Play several old call recordings from different dates.
If the new version does not work correctly:
Stop the new CT.
Under its Resources, select the /storage Mount Point.
Select Volume Action → Reassign Owner and return the volume to the old CT.
Return the /cf
Keep the old CT stopped and retain the backups for several days. Delete the old container only after:
the new version has been running reliably;
inbound and outbound calls have been tested;
new call recordings are created and can be played;
MikoPBX has rebooted successfully;
Before deleting the old CT, open its Resources once more and make sure that /cf and /storage have actually been reassigned to the new container. The old Root Disk can then be deleted together with the old CT.
/storage and /cf sizes match the sizes of the old volumes.If the address is reserved on the DHCP server, move the reservation to the new MAC address or assign the old MAC address to the new CT.
Check the bridge, VLAN, gateway, and Proxmox Firewall settings.
If necessary, switch external NAT, DNS, and firewall rules to the new address.
Start the new CT.
Check the installed modules, their licenses, and settings.
Make sure the phones and providers are registered or have the expected status.
Make an internal, outbound, and inbound test call.
Check that the new call appears in the history and that its recording can be played.
Reboot the new CT through Proxmox.
After the reboot, check the web interface, network, registrations, and a test call again.
Verify that mp=/storage and mp=/cf are present on the old CT again.
Restore the old IP, MAC, DNS, and NAT settings.
Start the old CT and verify its operation.
a new backup of the updated PBX has been created.
System files for the current MikoPBX version
Remains attached to the old CT
/storage
Call recordings, call history, modules, audio files, and logs
Reassigned to the new CT
/cf
MikoPBX settings and the main database
Reassigned to the new CT
Do not update an LXC container with an .img file under Maintenance → PBX update, and do not attach an ISO image. These methods are intended for a full system disk in a virtual or physical machine. For LXC, use a new lxc.tar.gz template.
Reassign Owner does not create a backup. It only changes the owner of an existing volume. An administrator error, storage failure, or incompatible database change may require restoring from a backup.
The new version may have changed the database structure on /cf. Returning the volumes therefore does not guarantee compatibility with the old MikoPBX version. If the old CT does not start correctly, restore it from the Proxmox backup or restore the settings from the MikoPBX archive created before the update.
With this update method, years of call recordings remain on the original /storage disk. The switchover time does not depend on the volume of recordings because Proxmox changes the volume owner instead of copying its contents.
Updating MikoPBX running in Docker or Docker Compose
We recommend updating sequentially, without skipping releases and versions.
A MikoPBX Docker container is not updated with .img or .iso files. To move to a new version, you need to download the new Docker image and recreate the container, preserving the /cf and /storage directories, network settings, and environment variables.
Create a backup of the MikoPBX settings. If the backup module is unavailable in the unprivileged container, prepare backup of the directories or volumes on the Docker host side.
Write down the name and version of the current image:
Save the current container configuration:
Check the /cf and /storage mounts:
Write down the ports in use, network_mode, hostname, and environment variables. If the container is started via Compose, save the current docker-compose.yml and the .env file.
End active calls and schedule a maintenance window.
For the latest stable version, run:
If a fixed tag is used, specify the same registry and the tag of the required version instead of latest.
Stop the container:
Create a consistent backup of /cf while the container is stopped. For the bind mount from the example above, you can run:
In addition to /cf, it is worth backing up the CDR database before the new version — it is located in /storage and may also be migrated on first start. /cf contains only mikopbx.db (the settings), while the call history is a separate cdr.db (and recording_storage.db) in /storage/usbdisk1/mikopbx/astlogs/asterisk/.
The backup must be made with the container stopped (as for /cf) so that the database is in a consistent state:
When rolling back, restore both archives: first /cf, then the CDR — otherwise the call history and the link between recordings and calls may get out of sync with the settings.
Rename the old container instead of deleting it immediately:
Start a new container with the same parameters. Example for an installation with host network and bind mounts:
Monitor the startup:
To exit the log view, press Ctrl+C — the container will keep running.
Go to the directory containing docker-compose.yml.
If user IDs are passed through the environment, set them the same way as on first launch:
Download the new image:
Recreate the container:
Check the status and logs:
Docker Compose will recreate the container but keep the bind mounts and named volumes specified in docker-compose.yml.
Make sure the container is running:
Open the web interface and check the MikoPBX version.
Check that the settings and call recordings are in place.
Make sure the phones and SIP providers have registered.
Make a test inbound and outbound call.
If the new container does not start:
Save its logs:
Stop and rename the new container:
Restore the /cf backup created before the update. The restoration method depends on whether a bind mount, a named volume, or a storage snapshot is used.
Give the old container its previous name back and start it:
To roll back a Docker Compose installation, specify the previous image tag in docker-compose.yml, restore the previous state of /cf, and run again:
After successful verification, you can delete the old container:
Check the publishing of web, SIP, and RTP ports if a bridge network is used.
The example must not be copied without verification. Repeat all the parameters of your exact previous installation: network type, volumes, ports, hostname, capabilities, and environment variables.
On first start, the new version may have upgraded the database in /cf. Therefore, a reliable rollback must rely not only on the old container image but also on the /cf backup created before the update.
sudo docker inspect mikopbx --format '{{.Config.Image}}'sudo docker inspect mikopbx > mikopbx-container-before-update.jsonsudo docker inspect mikopbx --format '{{range .Mounts}}{{println .Source "->" .Destination}}{{end}}'sudo docker pull ghcr.io/mikopbx/mikopbx:latestsudo docker stop mikopbxsudo tar -C /var/spool/mikopbx -czf mikopbx-cf-before-update.tar.gz cfsudo docker stop mikopbx
# backup of /cf (settings)
sudo tar -C /var/spool/mikopbx -czf mikopbx-cf-before-update.tar.gz cf
# backup of the CDR + recording metadata
sudo tar -C /var/spool/mikopbx/storage/usbdisk1/mikopbx \
-czf mikopbx-cdr-before-update.tar.gz astlogs/asterisksudo docker rename mikopbx mikopbx-before-updatesudo docker run --net=host --name mikopbx --hostname mikopbx \
-v /var/spool/mikopbx/cf:/cf \
-v /var/spool/mikopbx/storage:/storage \
-e SSH_PORT=23 \
-e ID_WWW_USER="$(id -u www-user)" \
-e ID_WWW_GROUP="$(id -g www-user)" \
-it -d --restart always ghcr.io/mikopbx/mikopbx:latestsudo docker logs -f mikopbxexport ID_WWW_USER=$(id -u www-user)
export ID_WWW_GROUP=$(id -g www-user)sudo docker compose pullsudo docker compose up -dsudo docker compose ps
sudo docker compose logs -f mikopbxsudo docker ps --filter name=mikopbxsudo docker logs mikopbx > mikopbx-update-error.log 2>&1sudo docker stop mikopbx
sudo docker rename mikopbx mikopbx-failed-updatesudo docker rename mikopbx-before-update mikopbx
sudo docker start mikopbxsudo docker compose up -dsudo docker rm mikopbx-before-updateUpdating MikoPBX installed on a dedicated physical computer
We recommend updating sequentially, without skipping releases and versions.
This guide is intended for a dedicated computer or server running MikoPBX.
The primary method is updating through the web interface. If the PBX does not boot normally or the web interface is unavailable, use an ISO image written to a separate USB drive.
Before updating, be sure to create a backup of the settings and store it on another device. Also save a copy of the call recordings.
Make sure you have physical access to the server or a working console. Create a backup of the MikoPBX settings and call recordings.
Make sure at least 400 MB is free on the Storage.
End active calls and schedule a maintenance window for the telephony system.
In the web interface, open "Maintenance" → "PBX update".
Select the desired version in the list. Review the list of changes and start the update process.
Once the download is complete, enter the phrase Yes, I have a backup. Click Update.
Download the .img file of the required version from the page.
Open Maintenance → PBX update.
Select the downloaded .img file.
Click Apply update.
Enter the phrase Yes, I have a backup and confirm the operation.
Wait for the PBX to reboot automatically after the update.
This method is suitable for restoring and updating the PBX from the local console.
Download the ISO of the required version from the page.
Connect a separate USB drive with a capacity of at least 1 GB.
Write the ISO in disk image mode using Rufus, balenaEtcher, or dd. Instructions for writing an ISO image can be found .
Connect the prepared USB drive to the server. In the BIOS/UEFI or Boot Menu, select booting from USB.
Wait for MikoPBX to start in Recovery mode.
Press any key to open the console menu. Then open "[4] Install or recover".
Select "2) Update to version..."
Wait for the writing to finish and the reboot. Remove the USB drive or restore the system disk as the first boot device.
Writing the ISO will erase all data on the selected USB drive. Double-check the selected device.
Updating MikoPBX deployed as a virtual machine in the cloud
We recommend updating sequentially, without skipping releases and versions.
This guide is intended for MikoPBX running as a full-fledged cloud virtual machine: from a Marketplace or from an imported RAW, VHD, or other disk image.
The primary method for updating a cloud PBX is through the web interface using an .img image. The ability to boot from an ISO depends on the particular cloud provider and is not universal.
Before updating, create two independent recovery points: a backup of the MikoPBX settings and a snapshot of the system disk or the entire virtual machine in the cloud provider's control panel.
Make sure you have access to the cloud management panel and the MikoPBX web interface. Save a backup of the MikoPBX settings and call recordings outside the virtual machine being updated.
Create a snapshot of the system disk. If there is a separate disk with recordings, create a snapshot for it as well or use storage backup.
Write down the current external and internal IP addresses, Security Group rules, attached disks, and network settings.
Make sure at least 400 MB is free on the system disk with MikoPBX.
Schedule a maintenance window: active calls will be dropped.
Log in to the MikoPBX web interface.
Open "Maintenance" → "PBX update".
Find the version you need in the "Online updates available" table. Review the list of changes and start the download.
Once the download is complete, enter the phrase "Yes, I have a backup". Click Update.
Do not perform Restart or Stop from the cloud panel: MikoPBX will prepare the update and reboot on its own. During the reboot, the connection to the web interface will be interrupted. It is safer to monitor the process via the cloud provider's serial console or web console.
Use a local file if the version is not in the list or the cloud VM does not have direct access to the update server.
Download the .img of the required version from the page.
Verify that the image architecture matches the VM architecture.
Open Maintenance → PBX update.
Select the downloaded .img and click Apply update.
Enter the phrase "Yes, I have a backup" and confirm the operation.
Wait for the automatic reboot and the services to start again.
Updating via ISO is possible only when the cloud platform simultaneously allows you to:
upload or attach a custom ISO;
change the VM boot order;
open an interactive console;
after the update, disconnect the ISO and boot from the system disk again.
If all the conditions are met (for example, as ), the procedure is the same as for a regular virtual machine:
Download and attach the ISO image of the required version from the page.
Start the machine and open its console. Wait for the message about booting in recovery mode - System booted in recovery mode (Live CD).
Press any key to open the console menu. Then open "[4] Install or recover".
Select "Update to version..."
When finished, disconnect the ISO and boot from the system disk.
If the provider does not support ISO, do not try to imitate this method by replacing the system disk. Use the web update or restore from a snapshot.
Do not select the Install option. It starts a new installation and warns that data on the selected disk will be erased. To update while keeping the settings, use the Update to version ... option.