Learnings from Building an AppImage

For some time I am offering an AppImage of Kraft to make installations for users as easy as possible. Unfortunately real linux packages are big effort for the variety of distributions, and having one way to rule them all seems very appealing.

My first AppImage versions were pretty faulty when looking into details. So I spent some time to improve it recently, with the great help of the friendly people from AppImage community.

Here is my little report about what I have learned. If there is something I can do better, please let me know (unless it is use $OTHERTOOL).

How to build an AppImage?

At first, it makes sense to build the AppImage automatically via Github Actions. GH Actions are powerful, and well integrated. I also looked into using the openSUSE Buildserver for that, which works, but Github Actions seemed easier.

I got convinced by @TheAssasin to use AppImageCraft to build the image. That simplifies the process significantly by hiding a lot of auto generating things under the hood. While that leads to very clean and short config files for the AppImage build, it is harder to deal with issues that might come up because things are covered.

If I would not have had help from the dev that I know personally, I probably would not have survived the process. Yet, AppImageCraft is an awesome utility, yet a bit better documentation would help a lot.

Python Components

Kraft has a few Python components that are called from Kraft to do specialized tasks that I did not want to reimplement in C++. For example, it uses the awesome tool weasyprint to generate PDF from html.

While the AppImage can call a weasyprint installation that is installed on the host system that is not a good solution as there is no way to control if the required tool is really installed. So bundled Python is needed with all the dependencies for the external deps.

To achieve that, there is a very useful linuxdeploy-plugin called conda that uses conda to install Python. It installs the required python libs via pip and make them available in the bundle. Very convenient.

Pathes

To be a good citizen in the AppImage world, the app needs to be careful with pathes. When running in the AppImage, it is advisable to not use for example classes like QStandardPath directly or even worse hardcode paths that do any loading of files the app needs. Since the file tree of the AppImage is just mounted somewhere in the host system, the app needs to consider that it is not installed in standard locations.

A good rule of thumb when locating a file to load is to always check relative to the binary path first (ie. ../share/kraft/data/), and if that does not exist, continue to check the standard paths of the host system.

In Kraft there were already utility methods to adjust paths which I could simply extend to work fine in the AppImage. Still, that is kind of fiddly as there are more places to consider than one expects.

Locate translation files

Also a result of the challenge described before is that the app did not find the translation files to load in the filesystem of the AppImage. The translation system (KLocalizedString in Kraft) does obviously not check the correct path inside the AppImage mount.

Setting an additional relative path to look up translations at runtime fixes that problem.

Icons

Another issue that required quite some work were icons. Kraft used icons from the system theme quite a lot. As long these are installed, because the user has the same fitting desktop environment, that is not an issue, and icons are found.

However, if the icon theme is not installed, the app just lacks icons which make it bad looking or even hard to use.

That can be solved by using own icons as fallback in the app. For simplicity and consistency I switched to a complete set of own icons that are now coming with Kraft. They are bundled to the app with the Qt resource system now.

Dependencies to the Outside

Last but not least: When preparing an app for AppImage it needs to be checked if the app has binary dependencies that can (or should) not be packaged into the AppImage for efficiency reasons. Kraft for example uses Akonadi for contacts. With that users can use KAddressbook to manage addresses and Kraft uses the address lists via Akonadi. Life is too short for reinvention of an Addressbook.

Of course one could think of bundling the entire Akonadi and KAddressbook into the AppImage of Kraft. But that seems overkill, as that would mean bundling a lot of stuff, and would bring KDE users two instances of KAddressbook (the one from their desktop installation and the one from the AppImage). Seems not a good idea.

So this seems to be the only downside of the new Kraft AppImage now: It can not use the Akonadi based address management. To fix that, there needs to be a non binary dependant way. There could for example be a way to sync contacts to a local file system and let Kraft pick them up from there. That way, users could use the address management they want (also for example google) and Kraft could still pick addresses from there. That needs more thoughts.

The good news on this that Kraft is still fully functional as the Akonadi integration is great, but optional.

Summary

An AppImage seems to be a great way of distributing desktop applications, because there is only one build to run on all distributions. Well, fingers crossed…

However, building an AppImage that really works flawlessly is not a simple task, as this blog hopefully illustrates a bit.

One thing would have helped me: A simple option to understand when the app loads things from the host system, rather than from within the AppImage, for example as commnd line switch when running the AppImage. That would have eased the path adjustment development described above.

What is next in that area: User friendly updating of the AppImage and a solution to the address management problem.

All changes were merged in Kraft master today, the resulting AppImages can be found here.

Kraft Version 0.98

We are happy to announce the new Kraft version 0.98 that is available for download.

Kraft is software for the Linux desktop to handle quotes and invoices in the small business.

This is a version packed with bugfixes and also new features. The most important fixes were in the area of the catalog handling: Based on bug reports from the community the catalog window was completely reworked. Drag and drop of items in the catalog, the sorting and reordering of items are now working properly and as planned.

Another big addition is the support of . XRechnung is an E-invoicing format more and more mandatory in the governmental area in Germany. We are very proud that Kraft is the first open source office tool that supports that standard in a user friendly way. All invoices can now also exported in the XRechnung-XML format.

Beside these two big improvements, there are lots of others. For example, the user manual was further improved and is available also in Dutch. A lot of other smaller but non the less important improvements and fixes make version 0.98 a valueable release.

We wish a lot of fun with this new improved version of Kraft!

Kraft Version 0.95

The authors are happy to announce the new release 0.95 of Kraft. Kraft is free desktop software for managing office documents like quotes and invoices in the small enterprise for the Linux desktop.

Kraft Version 0.95

With version 0.95 we do a big step forward in the way of generating documents: Until now (more than fifteen years!) Kraft uses the ReportLab python library to create high quality PDF documents.

While this has served us well, it has always been cumbersome to adopt the template for users needs. ReportLab uses a XML format as the template which has a bit of a steep learning curve and is not really easy with syntax.

This changes now: From version 0.95, Kraft supports the cool project WeasyPrint. The principle remains the same: The document is built of a text based template which defines the look of the output document. That gets filled with the document data and gets converted to a PDF document. But unlike ReportLab, Weasyprint is HTML based. Many people know a bit of HTML and thus will have an way easier time to adopt the template to personal needs.

Apart from the ease of use, it is much more simple to do modern report design with Weasyprint, as it supports the wide range of CSS styling.

That is a great improvement, as adopting Krafts output to personal needs is much more intuitive now. For now, Kraft supports both rendering engines, but ReportLab based reports are deprecated now and support will end in future releases of Kraft.

Along with integration of Weasyprint the text templating library Grantlee was added, as it is the standard in the KDE/Qt world, well maintained and widely available. The ctemplate library which was used for that so far will also be deprecated.

The other great improvement in this release is that Kraft now has a user manual embedded which will give new users a guiding help. It will open in the browser once the user clicks on the menu entry in the help menu, also without internet connection. It was started by a community member and it will grow and improve over time.

As usual this new version also ships an amount of bug fixes and small improvements which can be found in the Changelog.

We wish all users big fun with this remarkable new version of Kraft.

Kraft Version 0.90

This blog is to inform that Kraft, the Qt and KDE based desktop software to manage documents like invoices and quotes in your small company was released in version 0.90 recently.

Followup Documents

A great new feature is the completely reworked handling of so called follow-up documents. Kraft has this feature to help dealing with docs that follow on a certain kind of predecessor doc in the business flow, such as an invoice follows on an offer once the work has been finished.

To achieve that and to have all the items of the offer again referenced in the invoice, the Kraft user justs clicks on the menu item “Create Followup Document” on the selected offer, and the new doc is created with all the items of the offer prepared. It is ready to be adjusted to the final invoice details.

Now with version 0.90 this has even improved. Often, the flow is a bit different because a partial invoice is sent while the job is still in progress, for example to cover cost for material. A partial invoice usually has only one item, which is the progress payment the customer should pay.

Kraft users can handle that now very easy: The new UI does not only allow to choose from which predecessor document the final invoice should copy the items (which usually is the offer in the beginning) but it also realises that a partial invoice was sent before, so this amount of payment has to be substracted from the final invoice. Kraft adds an item to the final doc automatically here.

This helps to create high quality documents for your customers even faster, which is exactly the mission of Kraft.

Other Improvements

In addition to that, as usual a lot of other visible and invisible changes have gone into this release. For example, the UI has been simplified again by a clean up of the menu for example. The About Kraft dialog was removed and integrated into the Kraft information page.

Under the hood, we finally added unit tests, which is just a start so far, and ntroduced a new, XML based system to manage the available document types which makes igrations way easier. Last but not least the python based pdf conversion script was ported to python 3 to be ready for the end of python 2.

Community

Last but not least, Kraft got new contributions from the community: A new document type was initiated by a community member, which is a offer like document without showing the price information. Also, the complete app was translated to Dutch by a volunteer, and the translation is now shipped with Kraft by default. Also, other smaller bugfixes went in.

Thank you all for your help to improve Kraft.

Kraft Version 0.82

A new release of Kraft, the Qt- and KDE based software to help to organize business docs in small companies, has arrived.

A couple of days ago version 0.82 was released. It mainly is a bugfix release, but it also comes with a few new features. Users were asking for some new functions that they needed to switch to Kraft with their business communication, and I am always trying to make that a priority.

The most visible feature is a light rework of the calculation dialog that allows users to do price calculations for templates. It was cleared up, superflous elements were finally removed and the remaining ones now work as expected. The distinction between manual price and calculated price should be even more clear now. Time calculations can now not only done in the granularity of minutes, as this was to coarse for certain usecases. The unit for a time slice can now be either seconds, minutes or hours.

New calculation dialog in 0.82

Apart from that, for example sending documents per email was fixed, and in addition to doing it through thunderbird, Kraft can now also utilize the xdg-email tool to work with the desktop standard mail client, such as KMail.

Quite a few more bugfixes make this a nice release. Check the full Changelog! Update is recommended.

Thanks for your comments or suggestions about Kraft!

Kraft Version 0.81 Released

I am happy to announce the release of Kraft version 0.81. Kraft is a Qt based desktop application that helps you to handle documents like quotes and invoices in your small business.

Version 0.81 is a bugfix release for the previous version 0.80, which was the first stable release based on Qt5 and KDE Frameworks5. Even though it came with way more new features than just the port, it’s first release has proven it’s stability in day-to-day business now for a few month.

Kraft 0.81 mainly fixes building with Qt 5.11, and a few other installation- and AppStream metadata glitches. The only user visible fix is that documents do not show the block about individual taxes on the PDF documents any more if the document only uses one tax rate.

Thanks for your suggestions and opinions that you might have about Kraft!

Kraft Version 0.80 Released

I am happy to announce the release of the stable Kraft version 0.80 (Changelog).

Kraft is desktop software to manage documents like quotes and invoices in the small business. It focuses on ease of use through an intuitive GUI, a well choosen feature set and ensures privacy by keeping data local.

After more than a dozen years of life time, Kraft is now reaching a new level: It is now completely ported to Qt5 / KDE Frameworks 5 and with that, it is compatible with all modern Linux distributions again.

KDE Frameworks 5 and Qt5 are the best base for modern desktop software and Kraft integrates seamlessly into all Linux desktops. Kraft makes use of the great KDE PIM infrastructure with KAddressbook and Akonadi.

In addition to the port that lasted unexpectedly over 12 months, Kraft v. 0.80 got a whole bunch of improvements, just to name some examples:

More Flexible Addressbook Integration

As Akonadi is optional now, Kraft can be built without it. Even if it was built with, but Akonadi for whatever reason is not working properly, Kraft still runs smoothly. In that case it only lacks the convenience of address book integration.

The Address book access was also nicely abstracted so that other Addressbook backends can be implemented more easily.

GUI Improvements

Even though the functionality and GUI of Kraft was not changed dramatically compared to the last stable KDE 4 version, there were a few interesting changes in the user interface.

• A new, bigger side bar simplifies navigation.
• In the timeline view, a click on years and month in the treeview show summaries of the selected time span, ie. the number of documents with financial summaries per month or year.
• A filter allows to limit the view on the current week or month.

Reduction of dependencies

Kraft makes broad use of the core Qt5 libraries. The required KDE dependencies were reduced to a bare minimum. Akonadi libraries, which enable KDE PIM integration are now optional. The former dependency on heavyweight web browser components were completely removed and replaced by the far more simple richtext component of Qt.

These changes make it not only easier and more transparent to build Kraft but allow make a port to other platforms like MacOSX more easy in the future.

Under the Hood

A countless number of bugfixes and small improvements went in. Also updates to the newer C++ concepts where applicable make the rather mature code base more modern and better maintainable.

The Reportlab based PDF document creation script was updated and merged with a later version for example.

Deployment

Installing Kraft is still a bit complicated for unexperienced users, and distributions sometimes haven’t made a good job in the past to provide the latest version of Kraft.

To make it easier to test, there is an AppImage of Kraft 0.80 available that should be runable on most modern distributions. Just download a single file that can be started right away after having added the executable permissions.

Linux packages are already built for openSUSE (various versions) or Gentoo.

Kraft’s website will contain a lot more information.

Kraft out of KDE

Following my last blog about Krafts upcoming release 0.80 I got a lot of positive reactions.

There was one reaction however, that puzzles me a bit and I want to share my thoughts here. It is about a comment about my announcement that I prefer to continue to develop Kraft on Github. The commenter reminded my friendly that there is still Kraft code on KDE infrastructure, and that switching to a different repository might waste peoples time when they work with the KDE repo.

That is a fair statement, of course I don’t want to waste peoples time. What sounds a bit strange to me is the second paragraph, that says that if I decide to stay with Github, I should let KDE people know that I wish Kraft to not be a KDE project anymore.

But … I never felt that Kraft should not be a KDE project any more.

A little History

Kraft has come a long way together with KDE. I started Kraft in (probably) 2004, gave a talk about Kraft at the Akademy Dublin 2006, maintained it with the best effort I could contribute until today. There is a small but loyal community around Kraft.

During all the time I got little substancial contribution to the code directly, with the exception of one cool developer who got interested for some time and made some very interesting contributions.

When I asked a for the subdomain http://kraft.kde.org long time ago I got the reply that it is not in the interest of KDE to give every little project a subdomain. As a result I reserved http://volle-kraft-voraus.de and run it since then, happily showing a “Part of the KDE family” logo on it.

Beside the indirect contributions to libraries that Kraft uses, I shipped Kraft with the translations made by the KDE i18n team, for which I always was very grateful. Otherwise I got no other services from KDE.

Why Github?

Githubs workflow serves me well in my day job, and since I have only little time for Kraft, I like to use the tools that I know best and give me the most efficiency.

I know that Github is not free software and I am sceptical about that. But Github also does not lock in, as we still are on git. We all know the arguments that usually come on the table at this point, so I am not elaborating here. One thing I want to mention though is that since I moved to Github publically I already got two little pull requests with code contributions. That is a lot compared to what came in the last twelfe years when living on KDE infrastructure only.

Summary

Kraft is a small project, driven by me alone. My development turnaround is good with Github as I am used to it. Even if no KDE developer would ever look at Github (which I know is not true) I have to say with heavy heart that Kraft would not take big harm by leaving KDEs infra, based on the experience of the last 12 years.

If the KDE translation teams do not want to work with Github, I am fine to accept that, and wonder if there could be a solution rather than switching to Transifex.

One point however I like to make very clear: I did not wish to leave KDE, nor aimed to move Kraft out.
I still have friends in the KDE community, I am still very interested in free software on desktop and elsewhere, and my opinion is still that KDE is the best around.

If the KDE community feels that Kraft must not be a KDE project any longer because it is on Github, ok. I asked KDE Sysadmins to remove Kraft from the KDE git, and it is already done.

Kraft now lifes on on Github.

Kraft Moving to KDE Frameworks: Beta Release!

Kraft is KDE/Qt based desktop software to manage documents like quotes and invoices in the small business. It focuses on ease of use through an intuitive GUI, a well chosen feature set and ensures privacy by keeping data local.

Kraft is around for more than twelve years, but it has been a little quiet recently. However, Kraft is alive and kicking!

I am very happy to announce the first public beta version of Kraft V. 0.80, the first Kraft version that is based on KDE Frameworks 5 and Qt 5.x.

It did not only go through the process of being ported to Qt5/KF5, but I also took the opportunity to refactor and tackle a lot of issues that Kraft was suffering from in the past.

Here are a few examples, a full changelog will follow:

• Akonadi dependency: Earlier Kraft versions had a hard dependency on Akonadi, because it uses the KDE Addressbook to manage customer addresses. Without having Akonadi up and running, Kraft was not functional. People who were testing Kraft without having Akonadi up were walking away with a bad impression of Kraft.

  Because Akonadi and the KDE contacts integration is perfect for this use case, it still the way to go for Kraft, and I am delighted to build on such strong shoulders. But Kraft now also works without Akonadi. Users get a warning, that the full address book integration is not available, but can enter addresses manually and continue to create documents with Kraft. It remains fully functional.

  Also, a better abstraction of the Akonadi-based functionality in Kraft eases porting to platforms where other system address books are available, such as MacOSX.

• AppImage: The new Kraft is available as AppImage.

  There was a lot of feedback that people could not test Kraft, because it was hard to set up or compile, and dependency are missing. The major Linux distributions seem to be unable to keep up with current versions of leaf packages like Kraft, and I can not do that for the huge variety of distros. So AppImage as container format for GUI applications seems to be a perfect fit here.

• A lot more was done. Kraft got simplifications in both the code base and the
  functionality, careful gui changes, and a decreased dependency stack. You should check it out!

Today (on FOSDEM weekend, which could be a better date?) the pre version 0.80 beta10 is announced to the public.

I would appreciate if people test and report bugs at Github: That is where the development is currently happening.

SMB on openSUSE Conference

The annual openSUSE Conference 2017 is upcoming! Next weekend it will be again in the Z-Bau in Nuremberg, Germany.

The conference program is impressive and if you can make it, you should consider stopping by.

Stefan Schäfer from the Invis server project and me will organize a workshop about openSUSE for Small and Medium Business (SMB).

SMB is a long running concern of the heart of the two of us: Both Stefan, who even does it for living, and me have both used openSUSE in the area of SMB for long and we know how well it serves there. Stefan has even initiated the Invis Server Project, which is completely free software and builds on top of the openSUSE distributions. The Invis Server adds a whole bunch of extra functionality to openSUSE that is extremely useful in the special SMB usecase. It came a long way starting as Stefans own project long years ago, evolving as proper maintained openSUSE Spin in OBS with a small, but active community.

The interesting question is how openSUSE, Invis Server and other smaller projects like for example Kraft can unite and offer a reliable maintained and comprehensive solution for this huge group of potential users, that is now locked in to proprietary technologies mainly while FOSS can really make a difference here.

In the workshop we first will introduce the existing projects briefly, maybe discuss some technical questions like integration of new packages in the openSUSE distributions and such, and also touch organizational question like how we want to setup and market openSUSE SMB.

Participants in the workshop should not expect too much presentation. We rather hope for a lively discussion with many people bringing in their projects that might fit, their experiences and ideas. Don’t be shy 🙂