Build a new appliance with TKLDev

The TKLDev docs are great, but they are also a big read. The aim of this page is to create a simple overview of creating a new appliance.

This assumes that you have read through the TKLDev docs, have an instance of TKLDev running and have confirmed that everything works as it should by building a Core ISO.

Prerequisites

Commandline usage will be required, but of particular relevance are:

  • apt; e.g. apt-get; apt-cache etc - essential for installing packages
  • git; e.g. git clone; git commit; git push - essential for working with git version control
  • GitHub - Get a free GitHub account if you don't already have one.
  • If you are new to git/GitHub, set up your TKLDev for GitHub:
  • Setup git on your TKLDev server by setting a username and email (ideally use the same email as your GitHub account).
  • Then you have 2 options for authentication; the urls you use for your GitHub repo will depend on which choice you make:

Go!

This process works for developing a new appliance. Although it's not the only workflow.

git clone https://github.com/turnkeylinux-apps/<base-appliance-name>.git
mv <base-appliance-name> <new-appliance-name>
cd <new-appliance-name>
rm -rf .git
git-init
  1. Research your software and install it on a clean install of the appliance that is best starting point. Get it working as it should, while carefully documenting every step. I do this in a VM and my documentation is usually bash commands.
  2. Decide on a name for your new appliance. Often this will be self evident; other times not so much...
  3. In your TKLDev appliance, clone the base appliance (that you decided in step 1) and rename the resulting directory (as per your decision in step 2) to your the new appliance name (no spaces). Then (re)initialise it as a git repo.
  4. Create a new repo on GitHub named the same as your new appliance name; i.e. the name of the new repo.
  5. Sync your local repo and your GitHub (remote) one (and commit).
  6. Note that packages that install from the default repos (i.e. TurnKey and Debian default stable repos) should be added to the plan; e.g. LAMP plan (and commit)
  7. Create an install script from the documentation made in step 1 and put it in a script in the conf.d directory; e.g. LAMP main conf.d (and commit).
  8. And/or files can be added to the overlay directory; e.g. LAMP overlay (and commit).
  9. Update readme (e.g. LAMP README.rst with info relevant to your new appliance. You can use the existing one as a template, but you'll probably want to do a major overhaul.
  10. Update changelog (e.g. LAMP changelog. Again you may want to use some of what is there as a template (although get rid of all the old info as this will be the first release of a new appliance). If you want to track the progress of your work don't use the changelog, create another file for that.
  11. You can use the issues section of your GitHub repo for bugs and planned features if you want. This works extra well if multiple people are working together.
  12. Develop your init hooks. All unique factors such as passwords should either be auto generated (e.g. application MySQL user password) or interactive (e.g. a user password). Note though that interactive inithooks require the ability to be preseeded.
  13. I initially make root.patched'then 'fab-chroot build/root.patched' for testing and tweaking. Keep working on the appliance until it builds unattended and without error. and works as expected in the sandbox (committing as you make changes).
  14. Final build ('make') and test ISO (in a VM).
  15. Celebrate! :)

     

I suggest committing often. Then it's easy to see what has been done and in what order. You can clean the git history up later if you want. Usually I only push to GitHub every so often (once a session). Although sometimes using the GitHub WebUI to view your code can be a handy way to see everything in one place.