FreedomBox is a pure blend of Debian. This means that all the work on FreedomBox is available in Debian as packages. It also means that any machine running Debian can be turned into a FreedomBox.
This page describes the process of installing FreedomBox on a Debian system. Currently, FreedomBox works in Debian Stable (trixie), Testing (forky), and Unstable (sid).
Important: Read general advice about hardware before building a FreedomBox with this approach.
Use a fresh Debian installation
Installing FreedomBox changes your Debian system in many important ways. This includes installing a firewall and regenerating server certificates. It is hence recommended that you install FreedomBox on a fresh Debian installation instead of an existing setup.
During installation of Debian, it is recommended that you choose btrfs as the filesystem for the root partition. Btrfs filesystem is needed for the Snapshots feature to work.
Check the Troubleshooting section below, for any tips or workarounds that might help during the install.
Install Debian 13 (Trixie) or newer on your hardware. During installation choosing "Btrfs" for root filesystem type is recommended as FreedomBox uses it take regular snapshots of the system.
Update your package list.
$ sudo apt-get update
Install freedombox package.
$ sudo DEBIAN_FRONTEND=noninteractive apt-get install freedombox
The "DEBIAN_FRONTEND=noninteractive" will avoid several configuration prompts that would otherwise appear during the install.
During the installation, you will be provided a secret key that needs to be entered during the initial configuration process. Note this down. The secret can also be read at a later time from the file /var/lib/plinth/firstboot-wizard-secret.
You can start using FreedomBox. During initial wizard, you will need to enter the secret noted above.
Following are the differences between setup using a FreedomBox image vs. installing FreedomBox using a Debian package on an existing Debian installation:
Filesystem: The disk images have btrfs as the filesystem. When installing a Debian package, the existing filesystem is not altered. The snapshots feature is currently only available if btrfs is the filesystem. So, for those wanting to install freedombox .deb package, it is recommended that they install Debian on a btrfs filesystem first.
First Wizard: When installing from a Debian package, FreedomBox will ask for a secret (stored at a path on the disk) during first wizard. The secret is for security and has no relevance after the first wizard is completed. This secret is not asked if first wizard is run from a disk image (as hardware is expected to be in possession of the user and the user won't be able to easily peak the secret on the disk without running the first wizard first).
Networking: When disk image is booted, all the Ethernet and Wi-Fi devices are automatically configured to be managed by Network Manager. When FreedomBox is installed from Debian package, existing network connections are not reconfigured. These network interfaces can later be reconfigured (by commenting out entries in /etc/network/interfaces) to be managed by Network Manager.
FreedomBox uses NetworkManager to manage network configuration. If you have configured your network interfaces using Debian installer or by editing /etc/network/interfaces, FreedomBox will not manage those interfaces. (See bug #797614.) To let FreedomBox/NetworkManager manage your network interfaces, edit the /etc/network/interfaces manually and ensure that it contains only the following:
auto lo iface lo inet loopback
If you have already completed the setup process without doing this step, you will need to clear out the /etc/network/interfaces file keeping only the above lines. Then perform a reboot. Network interfaces will then be in the internal or external firewall zone. This is essential for the FreedomBox's web interface to be reachable from other machines in the network. You can tweak network manager connections with the nmtui command if you wish.
FreedomBox will use an automatically configured IP address by default. You can assign a static IP address if necessary. Network configuration changes can be done using FreedomBox web interface or by using the nmtui or nmcli commands. nmcli can be used as follows:
nmcli con mod "Ethernet connection 1" \ ipv4.addresses A.A.A.A/X \ ipv4.gateway G.G.G.G \ ipv4.dns N.N.N.N \ ipv4.dns-search somedomain.com \ ipv4.method "manual" \ ipv4.ignore-auto-dns yes \ ipv6.method ignore
...with the block capitals and somedomain.com replaced with your actual address, mask description, gateway and dns server details.