Skip to main content

Migrate to Docker

Chef Infra Client, the configuration system Chef Omnibus relies on, has been scheduled for End-of-Life in 2024. As such, Omnibus-based deployments will be deprecated in a future version of Firezone.

Follow this guide to migrate from an Omnibus-based deployment to a Docker-based deployment. In most cases this can be done with minimal downtime and without requiring you to regenerate WireGuard configurations for each device.

Estimated time to complete: 2 hours.

Steps to Migrate

  1. Back up your server. This ensures you have a working state to roll back to in case anything goes wrong. At a bare minimum you'll want to back up the file and directories Firezone uses , but we recommend taking a full snapshot if possible.
  2. Ensure you're running the latest version of Firezone. See our upgrade guide if not.
  3. Install the latest version of Docker and Docker Compose for your OS. Docker Compose version 2 or higher is required. We recommend using Docker Server for Linux. Docker Desktop will work too, but is not preferred for production use cases at this time because it rewrites packets under some conditions and may cause unexpected issues with Firezone.
  4. Download and run the migration script:
bash <(curl -fsSL

This will ask you a few questions, then attempt to migrate your installation to Docker. If all goes well, your Firezone instance should be running with Docker, data intact.

Rolling Back

If anything goes wrong, you can abort the migration by simply bringing the Docker services down and the Omnibus ones back up:

docker-compose down
sudo firezone-ctl start

If you've found a bug, please open a GitHub issue with the error output and any steps needed to reproduce.

Get Help

If you need help migrating from Omnibus to Docker, check our community support options:

  1. Discussion Forums: Ask questions, report bugs, and suggest features.
  2. Public Slack Group: Join live discussions, meet other users, and get to know the contributors.

If you'd like dedicated support migrating your installation from Omnibus to Docker, consider contacting us about our paid support plan .