Build and customize your own Sage Debian Live USB

It is possible to build and customize your own Sage Debian Live. You should run Debian stable. Derivatives whose version of live-build package is 4.x should work as well but are not tested.

Download sources

Install git package, go to a directory you want the sources to be cloned to and type

git clone --branch master
cd sagedebianlive

Install dependencies

To install required packages before your first build (you are assumed to be sudoer), go to the source directory and type

./ install

Consider using apt-cacher

To save bandwidth, it is advised to use the package apt-cacher-ng

sudo apt-get install apt-cacher-ng

Customize your build

All customizable variables are set by default in the ./config/default file, and some hints are given along the file as comments. To customize your build, you can overwrite some of those variables by creating a custom ./config/<my_config> file that will be run after the default file. It is better not to modify directly the ./config/default file in order to keep your customizations when the default config will be updated.

Select modules

Most existing modules are selected by default. You can unselect some by removing them from the MODULES variable. Available modules are located in the ./modules/ directory. Note that some modules depend on some other modules, so you do not need to add them explicitely (though it does not harm), for example the mathematics/sagemath module depends on the mathematics/latex module.

Deeper customizations

If, compared to what is in the existing modules, you only want to add a few Debian packages, you can do it by adding them to the PACKAGES variable in your custom config file:

PACKAGES+=' <package1> <package2> <package3>'

If you want to do something deeper, you should create your own module. For this, create a custom module, as a directory ./modules/<my_module>/. You can have a look to existing modules to get some hint on how it works.

In this directory, add a file that contains the commands that deploys the module by tuning the config directory of the Debian Live. Some functions may help you in this task:

  • If you want to add some packages that are included in Debian, just add the line

    add_packages "<my_custom_title>" "<package1> <package2> <package3>"
  • If you want to add some localized packages, see for example the add_packages_l10n function used in the packages module.

  • If you want to add an external .deb file (be carefull to also add the required dependencies), just ad the line

    add_deb "<path_to_your_deb_file>"
  • If you want to add a <file_path> to some <target_directory> of the booted key with <chmod> permissions, just add the line

    add_file_path <file_path> <target_directory> <chmod>

    Note that if you want to add some files to the user's directory, you should add them to the /etc/skel directory whose content will be copied to the user's homedir during the first boot of the live system.

  • If you want to add a <file_name> that belongs to your module's directory to some <target_directory> of the booted key with <chmod> permissions, just add the line

    add_file_name <file_name> <target_directory> <chmod>
  • If you want to add a launcher to the desktop whose icon will be stored to <target_directory>, create the <launcher_name>.icon.svg and <launcher_name>.desktop in your module directory, and add the line

    add_launcher <launcher_name> <target_directory>
  • If you want your module to depend on another module, just add the line

    load_module <module>
  • If you want to add a hook script that will be run a root, create a file <hook_file_name> (which must end with either .chroot or .binary wether you want it to be executed during the chroot or binary phase) just add the line

    add_hook <hook_file_name>
  • If you want to add a boot menu entry whose title is <menu title> that uses additional custom boot options <boot option 1> and <boot option 2>, just add the line

    add_boot_menu "<menu title>" "<boot option 1> <boot option 2>"

    Alternatively, you can set the HARDCODED_SYSLINUX_MENU variable to the path of a file that will be used as a live.cfg file. In both cases, you should add syslinux at the end of your modules list.

Then, you can add your module by modifying the MODULES variable as follows in your ./config/<my_config> file:

MODULES+=' <my_module>'

Of course, if your customization improves an existing module, you can modify it and push your changes.

Launch the build

From the source directory, run


If you use a custom ./config/<my_config> file to overwrite some default variables, run

./ <my_config>

Note that config files can be stacked, for example you can customize an existing config by running

./ <existing_config> <my_config>

If you want to work on your custom config that you will build a lot of time, you can use the debug config file that adds the root password to the root user (useful if you can not log in as user and still want to inspect things) and that downloads everything (even releases and security updates) from apt-cacher (do not forget to tune the expire_hours variable of /etc/apt-cacher/apt-cacher.conf), run

./ <my_config> debug

If you want to build a kiosk CD with french support, run

./ kiosk fr

If you want to build a kiosk CD with french and german support that still uses english as default language (the last language config overwrites the boot parameters set in the previous ones), run

./ kiosk fr de en

The image can be found in the BUILD_DIR directory, which by default is /var/opt/live/build/.

Test the image

To test the image you built without having to burn a CD/USB, you can install the package kvm and run

sudo qemu-system-i386 -m 1G <IMG_NAME>

Share your contributions

If you think some of your customization could be of interest to someone else, please do not hesitate to share them by contacting us (you can either send your code on the mailing-list or ask for an account to the git server).