diff --git a/ansible/debian.md b/ansible/debian.md
new file mode 100644
index 0000000..e69de29
diff --git a/debian.md b/debian.md
new file mode 100644
index 0000000..70c652b
--- /dev/null
+++ b/debian.md
@@ -0,0 +1,57 @@
+# Creating an upgrade content pack for the butterbox
+
+Butterboxes run [Debian OS](https://www.debian.org/) and can be upgraded using `apt update` and `apt upgrade` commands.
+However, since they are often expected to operate in areas without Internet connectivity,
+the following instructions detail how to create and use a content pack to allow local offline upgrades.
+
+## Requirements
+- A large (min 250GB ) Hard drive or USB Stick, formatted as FAT32 or ext4
+- Internet connectivity
+- A computer running Debian
+
+## Creating a Debian mirror
+
+- Plug in and mount the hard drive into a computer running Debian. The rest of the configuration assumes this is mounted at `/mnt`.
+- Edit the Debian mirror configuration. For this, depending on what kind of butterbox you have (AMD64-based, like an old laptop, or 
+ARM-based, like a Raspberry Pi), edit the file "/etc/apt/mirror.list" (you may wish to back it up beforehand) 
+to contain the following, making sure to uncomment the line corresponding to your box. 
+```angular2html
+############# config ##################
+#
+ set base_path    /mnt # This is where the mirror will be created, ensure it corresponds to where the hard drive is mounted
+#
+ set mirror_path  $base_path/mirror
+ set skel_path    $base_path/skel
+ set var_path     $base_path/var
+ set cleanscript $var_path/clean.sh
+ set postmirror_script $var_path/postmirror.sh
+ set run_postmirror 0
+set nthreads     20
+set _tilde 0
+#
+############# end config ##############
+
+#deb [arch=arm64] http://ftp.us.debian.org/debian stable main contrib non-free # Uncomment for ARM64, e.g. Raspberry Pi 3 or 4
+#deb [arch=amd64] http://ftp.us.debian.org/debian stable main contrib non-free # Uncomment for AMD64
+
+# Note the mirror location, ftp.us.debian.org; you can choose any other online debian mirror to download from, keep a note of its name
+```
+
+- Run the command `apt-mirror`. This will create a Debian mirror on your hard drive, that can then be used to upgrade your butterbox.
+The size of the archive varies, but will utilise somewhere in the region of 150-200GB, depending on architecture.
+
+
+> Careful running this command on any metered connection, as it will attempt download hundreds of GB worth of data!
+
+> Be patient. This command will take a while to run depending on the speed of your Internet connection.
+
+## Updating your Butterbox
+
+- Plug in the hard drive into your butterbox, and mount it. This assumes it is mounted at `/mnt`.
+- Log in via the butterbox console, as the root user.
+- ensure the date is set correctly by running `date -s "30/12/2026 10:29`
+- edit file `/etc/apt/sources.list` to contain the following line: 
+` deb file:/mnt/mirror/ftp.us.debian.org/debian stable main contrib non-free`
+
+Note that the name of the directory might vary depending on the mirror you used in the previous step.
+- Congrats! Now you can run `apt update` and `apt upgrade` to update the box.
\ No newline at end of file