A Usability Guy’s Journey to Creating his First KDE Tool – Part 1: Baby Steps


I, psychologist by education, human-centered interaction designer by trade – my only completed software project so far being a web-based Advent calendar I made years ago – have embarked on a journey to write my first KDE tool. How did it come to this?

It all started with me wanting two things:

  1. To change the speed of Plasma animations on my system
  2. To have proper AppStream metadata for KDE software

These two may sound completely unrelated at first, but they both were key in sending me down this path. This article will tell the story behind 1, which is about my very first code commit to KDE. I will go into quite some detail because I feel that my journey may provide some insights for KDE.

This story started on April 6th. I was discussing with Aleix Pol about actual vs. perceived performance in Plasma and other KDE software. One thing we agreed on was that animation speed has a big impact on perceived performance. During that discussion, we found out that the setting for the animation speed is almost impossible to find in System Settings, because it sits in a module where you would not expect it to be (Display and Monitor > Compositor), and searching for “animation speed” points you to the wrong module (this was due to an oversight when the “Desktop Effects” module was split in two and the search keywords were not adapted). The “it sits in an unexpected module” problem is about to be fixed by moving it into the “Workspace behavior” module, but first I wanted the actual bug with the search pointing to the wrong module to be fixed.

At first, as usual, I wrote a bug report about it. Then, Aleix, being a cunning little Spaniard (*scnr*, I know you’re Catalonian), said these fateful words: “You could fix this one yourself!”. Now the cunning part was that he knew I could not defend myself by saying “But I don’t know C++ …” because the search keywords are defined in .desktop files, easily read- and writable for mere mortals like me. So, without any good argument why I couldn’t, I set out to fix it myself.

The first obstacle on my journey was that even after years of being a KDE contributor, I still did not have a KDE developer account. The reason is simple: My contributions usually come in the form of text and mockups, not code. I describe my ideas in wiki pages, emails, forum posts, chats, review requests, bug reports, blog posts, …, but not in repositories. For this simple patch, I could have just put it up on Reviewboard or Phabricator and have someone else commit it, but if I was going to contribute code, I wanted to do it properly™.

Besides, I saw an opportunity in this exercise: We often hear that while new contributors perceive KDE as a very friendly and welcoming community, they perceive the organizational process of becoming a KDE contributor as relatively difficult, and now I could experience that process first-hand and see what could be improved. So I wanted to go all the way.

Now first of all, I needed to get a developer account. I know that community.kde.org is supposed to be the place where every information for the community can be found, so I looked there. The “Get Involved/development” page looked promising. And indeed, this had a link to the “Get a Contributor Account” page. Here I found the first inconsistency: On the page, it was called a “contributor account” whereas in the actual application process it’s called “developer account”. I have fixed that now, changing (hopefully) all of it to “developer account”. “Developer account” made more sense to me, because – as evidenced by for example by me – not all contributors need such an account. Apart from that, though, the documentation there was pretty straightforward.

With that and Aleix’s blessing, I had my Developer account created the next day. Now the more difficult part was setting up Git.

The “Get a Contributor Account” page (which will hopefully soon be renamed by someone with the necessary privileges) had a link to a “next tutorial” in the “And now?” section which in turn was just linking back to the page you came from, along with something about me having to adapt my local copy to a new server (without further specification). I did not understand that part, so I asked Aleix what it meant and now we have made it more specific.

Olivier Churlaud, our new Master of the Wikis, then pointed out to me that the best pages for further information would be the Git or Subversion pages, depending on the project one wants to contribute to, so I’ve now linked to those from the “And now?” section.

So, next step, setting up Git. I followed the steps in the “Git Configuration” page, which involved a tedious amount of “git config –global” commands. I wonder if maybe we should provide a template .gitconfig file to make this easier, at least for things that are ideally the same for anyone, anyway? One of the instructions in there told me to enter

git config --global user.name <Your Real Name>

so what I entered was

git config --global user.name Thomas Pfeiffer

Following the instructions by the letter bit me in the behind later on when I tried to commit, because of course Git ignored the last name after the space and then the server could not identify me. Without Aleix’s help, I’d never have been able to identify the problem, let alone fix it.

This may all be obvious for seasoned shell users, but it clearly wasn’t obvious for me, so I changed the instructions on the wiki to

git config --global user.name "<Your Real Name>"

just to remind people to put their name in quotes.

The page also recommended to use the Git commit template from kdelibs. This sounded  outdated to me given that kdelibs is long deprecated by now, but since I wasn’t aware of any other commit template, I went ahead and used the one from kdelibs, anyway. I’ve now started a discussion on the kde-devel mailing list regarding where we should put that template in the future.

Aleix suggested that I’d use Arcanist to link my commit to a review on Phabricator, but since I didn’t want to install another tool just for my one commit (and Arcanist was never mentioned in the pages I’d come across on the wiki, either), I decided to skip that for the time being. So I manually created a Diff on Phabricator (like the “Get Involved/development” page had told me), which was reasonably simple.

Now it was time to actually commit and push my changes. For that, the page “Infrastructure/Git/Simple Workflow” sounded like the most fitting one to follow. I did what I was told there to add and commit my change. Now for the commit message. Following the link trail from the Simple Workflow page lead me (through one unnecessary hoop which I’ve now cut out) to the “Special keywords in GIT and SVN log messages” section of the “Commit Policy” page.

There I found what I was looking for, except for how to link to the Diff on Phabricator (I’ve added that now). With my commit message complete, I could finally push. I was asked whether I should add the server with the fingerprint SHA256:75pLvlr+9A0ki9YlWAz+il4UPI+N81uMvcocs42d0wU to my list of trusted servers. I remembered that the Git Configuration page had also mentioned server fingerprints, but unfortunately, those did not match the fingerprint Git presented to me. Aleix told me that the server was okay and the page was just outdated. Accepting a fingerprint which does not match the one you find in the documentation of course defeats the purpose of putting fingerprints in the documentation in the first place, so we have to either remove them from the wiki (I did that for now) or find a way to keep them up to date.

Now, finally, my first commit was pushed! Closing the bug automatically failed, unfortunately, because I had not heeded the advice in the page about getting a developer account which said “Also note that this email address should be the same one that you use on bugs.kde.org“. This one’s on me, then.

So, this is the story of my very first commit to KDE! I learned a lot along the way, uncovered some slight shortcomings in our documentation and fixed most of them. I can say that trying to relive the first contribution experience first-hand is a good lesson for anyone who cares about improving it.

In the next posts of this series I will expand on that by creating my own little tool for making the creation and updating of AppStream metadata for KDE applications easier, and I will be doing it in the way I know best: the user-centered way.

Have you started contributing to KDE recently, or know someone who has? If so, please let us know about your experience! What went well, where could we improve our onboarding process in KDE? Tell us in the comments!

Tagged with:
Posted in KDE

Do Plasma users know all the useful shortcuts?


“keyboard shortcut bulletin board” by arvind grover

Dear reader,

when Heiko Tietze and I discussed the usefulness of a user assistance feature that is being considered, we realized that we had very different assumptions about how well users know the keyboard shortcuts that KWin and Plasma offer.

Although I know that the readership of my blog is not exactly representative of the Plasma and KWin user base, I’d like to get at least a rough feeling about whose perception might be closer to the truth. For that, I need your help: I’d like to ask you to do the following:

  1. Go to System SettingsShortcutsGlobal Keyboard Shortcuts
  2. Select “KWin” in the “KDE component” dropdown
  3. Go through the shortcuts which have a “Default” value set and count those which you did not know by heart (or not at all) but think could be useful to you.
  4. Do the same for the “Plasma” component
  5. Add the two numbers
  6. Select the appropriate option in the poll below.

If you know any Plasma users who don’t read Planet KDE / my blog, it would be great if you could link them to this.

Thank you!

P.S.: Sorry for the confusion I might have caused with the picture above. It has nothing to do with Plasma or KWin, actually. I just wanted a nice picture, and I explicitly did not want to show any Plasma or KWin shortcuts in order to not influence the experiment.

Tagged with: ,
Posted in KDE

Plasma Mobile’s Vision

We’re currently in the process of designing the first phone user interfaces for KDE applications, applying the KDE Mobile Human Interface Guidelines (a set of soft rules and recommendations for designing user interfaces for mobile applications by KDE). Therefore, the third part of my blog series about the HIG creation still has to wait a bit.

In the meantime, I’d like to talk a bit about another foundation on which Plasma Mobile is built: Its vision. As I’ve already laid out in my blog post about creating a vision for the KDE PIM Framework, a vision is very important to align the work in a project towards a common goal, and to inspire those contributing it. Inspired by the talk Andrew Lake and I had just given at Akademy about product/ project visions, it did not take much convincing to get the Plasma Mobile team to start working on a vision.

Shortly after Akademy, I met online with Sebastian Kügler, Ivan Čukić and Jens Reuterberg to draft a first proposal for the vision, along with potential target personas. The result was then presented to the Plasma mailing list, where it was well received, and consequently adopted with only with minor revisions.

And here it is, our vision for the future which guides the design and development of Plasma Mobile (this does not say when Plasma Mobile will meet these goals):

Plasma Mobile aims to become a complete software system for mobile devices. It is designed to give privacy-aware users back the full control over their information and communication. Plasma Mobile takes a pragmatic approach and is inclusive to 3rd party software, allowing the user to choose which applications and services to use. It provides a seamless experience across multiple devices. Plasma Mobile implements open standards and it is developed in a transparent process that is open for the community to participate in.

These are the four key elements:

1. Control over your data and communication


With most current mobile operating systems and applications, users can only trust those who create them that they will not abuse the detailed and sensitive information that is stored on their devices, and the communication that happens through them.

When installing an app, we can see the – vaguely defined – permissions that the app requires, and – depending on the operating system and version – we can either decide whether to take it as it is or to leave it, or we can block certain permissions. But beyond that, we can never tell what exactly happens with their information and communication. Which files or records are accessed? Where is information stored, and who or what may access it in the future? Where is information sent? Is the communication secure and private? We simply cannot tell. We can only trust others that they do what they say they’re doing.

In Plasma Mobile, we want to change that. We want users to be able to see what happens to their information and communication, to the degree of detail that they prefer. They should be able to allow an application to access some files, but not others, and they should be able to control when and where their information is sent.

We do not want to overburden users with feedback and choices they cannot handle, though. Our aim is to present the information and choices as clearly as possible, and give users a choice only when they want to have one.

2. Pragmatic and inclusive


We are realists. We know that a mobile operating system is nothing without apps. And we know that we, as a community, cannot provide applications for everything that users may want an app for. We aim to provide our own apps for the most common tasks (e.g. browsing the web, viewing common file types, email, calendaring, instant messaging, …) in order to create the most seamless experience possible across them, but the more specialized a task or service, the less likely we’ll be able to provide an app for it ourselves.

For that reason (and because we believe that choice is a good thing), Plasma Mobile won’t exclude any application as long as it’s technically possible to run it (and it’s not malware), whether it was written for Plasma Mobile, Android, Ubuntu Touch, desktop Linux, Sailfish or whatever. If it can be made to run on Plasma Mobile, it’s welcome there!

Pragmatism also means that we won’t keep users from giving up part of the control the system offers them again, by running proprietary applications or accessing services on it which invade their privacy. We will strive to keep those applications as sand-boxed as possible, but we won’t keep users from doing something with their device which we wouldn’t do.

3. Seamless cross-device experience


When using Plasma on multiple devices, we want those devices to feel really integrated. KDE Connect already offers impressive integration between a Linux desktop and an Android mobile device, but with a platform that we fully control, we can still go beyond that (users could fully control their phone from their desktop, for example, or tethering could be made a one-click experience). Your selection of applications or certain settings could be synchronized between your desktop or tablet and phone (yes, that one is not new, other mobile OSes can do that already), or a desktop application can suggest to automatically install the corresponding mobile application on your Plasma Mobile devices (for example when an office suite offers a mobile “companion” for controlling presentations).

“Seamless experience across multiple devices” also refers to the same application binary offering an optimized experience on different form factors through interaction-shifting components (user interface elements which change their look and behavior depending on the type of device) and adapted QML files. For example, while contextual actions are offered using a side-drawer or “slide to reveal” controls on a touch device, the good ol’ right mouse button is much more convenient when using a mouse. Another example is scrolling: On a touch-based device flicking is the best way to scroll, whereas with a mouse, the combination of scroll wheel and a traditional scroll bar still works best. The general layout of content or the navigation structure, on the other hand, can often be kept the same across devices, allowing the user to transfer their knowledge from one type of device to the next.

4. Openness


Yes, we do realize that Plasma Mobile is not the only open source mobile shell. The Android Open Source Project is, as the name implies, open source. Yet, most of its development happens behind closed doors at Google. That means that even though anybody can do anything they want with the end result, people outside Google cannot freely contribute to it or influence any decisions. Sailfish OS has a fully open base, but the user interface layer is still proprietary. Tizen or Ubuntu Touch are perhaps more open, but still mostly in the hands of commercial entities.

Plasma Mobile wants to be different. Even though Blue Systems initiated the development, it is explicitly not a Blue Systems product (otherwise it would probably be called Netrunner Mobile). Blue Systems of course will only contribute their resources to efforts that are in line with their goals for Plasma Mobile, but they will not keep anyone from working towards their personal goals for Plasma Mobile in their own time.

Plasma Mobile was, is and always will be a community project. All of its development happens in KDE repositories where everyone with a KDE developer account has write access, and all commits can be reviewed by the community. All of its components are Free Software.

An equally important aspect of Plasma Mobile is that it uses open standards. Android is Linux, but one only realizes how important the “GNU” part of “GNU/Linux” is to the actual experience of a regular GNU/Linux distribution once that isn’t there.  Other mobile operating systems are closer to the stack we’re used to, but still diverge from standards that are or will be well established in the desktop world, like Wayland Display Servers. Plasma Mobile aims to make it as easy as possible for developers who have previously worked in the desktop area to transfer their knowledge (and code).

Concluding remarks

So this is what Plasma Mobile aims for. Whenever we make important decisions, we will check whether they are in line with the vision. People are of course free to spend their time on things which do not necessarily get us closer to these goals, but we would not allow things which work against them.

Now, I’d love to hear whether these goals are in line with what you’d expect from Plasma Mobile or what we might have missed.


Tagged with: ,
Posted in KDE

Behind the scenes of the KDE Phone HIG – Part Two: The HIG creation process

Plasma Mobile HIG Process

As I wrote in part one of this series, we are currently creating Human Interface Guidelines (HIG) for phone user interfaces for KDE applications.

In this part, I want to tell a bit more about the process of creating these guidelines. This is rougly the process we’re planning to follow from the first idea brainstorming to a finished guideline:

Step 1: Identify which guidelines are needed

First of all, we have to find out where guidelines are needed. There are different sources for this. One source are the already existing, desktop-specific KDE HIG. There we can identify the cases where what we suggest for desktop applications can’t be transferred 1:1 to phone user interfaces, and then write the phone-specific guidelines accordingly.

Another source are of course the HIG users, i.e. mostly developers and interaction designers. From time to time, we explicitly ask them where they need guidelines the most, or they come to us telling us what they need. A third source are other phone HIGs, like for example the Material Design Guidelines. They’ve been written based on past experience with what mobile app designers and developers need, so it makes sense to check out what they define, as it’s likely our designers and developers will need the same information.

Step 2: Brainstorm

The extent of this step depends on the specific topics. Things like defining how checkboxes should be used involve more “dull” work and less creativity, whereas more innovative parts like navigation patterns involve more creative ideation. Our brainstorming usually happens on a Telegram group we have created for that purpose. There everyone can present their ideas, we discuss them, weigh the pros and cons.

Then we have to think about edge cases to prevent bad surprises later on. Once we think our ideas are solid, we can go to the next step

Step 3: First draft

Now it is time to write a first draft of the HIG. If it is an addition to an existing HIG page which just details phone-specific guidelines, the existing page has to be separated into global and desktop-specific parts and then the phone-specific parts are added. This is mostly work on the details. If the HIG is completely phone-specific, it has to be created from scratch. The challenge is to find the sweet spot of “as long as necessary, as short as possible”. Too many details, and it risks becoming too long for people to want to read it. Too few details, and we risk a lack of consistency between applications because everyone interprets it differently. A good HIG of course also has to be understandable and to feel useful for its readers.

Step 4a: Discussion on the mailing list

The draft is then sent to the KDE Guidelines mailing list (you’re invited to subscribe to it here if you’re interested) where everyone interested can give feedback. Particularly (but not only) developers are invited to give feedback on technical feasibility here. In this step, the HIG is iterated until no more suggestions for improvements are coming in.

Step 4b: Creating a library implementation of the HIG

If the HIG describes a specific part of a user interface (which most of them do, except for very generic ones such as wording or icon usage), a developer creates a library implementation (for example a shared QtQuick Component) which allows developers to easily implement the HIG without starting from scratch. This happens ideally in parallel with the discussion on the mailing list. Creating a library implementation is very important because the HIGs are much more likely to be followed correctly – and much more likely to be followed at all – if following them makes a developer’s life easier, not harder.

The library implementation is at the same time also a first test case for both the clarity of the HIG and the technical feasibility of implementing it, often resulting in valuable feedback from the developer creating them.

Stop 5: Finalizing and publishing the HIG

When all the designers and developers involved are happy with the state of the HIG, it is time to put it on the HIG Wiki. This is the point where the HIG is ready for use by designers and developers.

HIGs as living documents

That does not mean it’s set in stone yet, however. While the API of the components should be kept as stable as possible, the HIG itself has only existed in a vacuum up to that point. It still has to see implementation in real application user interfaces, where we can test prototypes with real users and see how our ideas which were sound in theory hold up in practice. Based on the feedback from these tests and experience with implementing it in general, the HIG may still be refined later on.

On the one hand, we don’t want to force developers to continuously adapt their user interfaces to ever-changing HIGs, but on the other hand, setting a HIG in stone and refusing to update it with new knowledge would prevent us from providing users the best experience we can.

The next (and probably last) part of the series will describe the application of the HIGs in the design of a KDE application’s phone user interface. You will have to be a bit patient for that one, though, because we’re only just starting the design work which the post is going to talk about.

Tagged with: ,
Posted in KDE

Behind the scenes of the KDE Phone HIG – Part One: Basic Assumptions

Example of column-based navigation on different screen sizes

The Task

Right after Plasma Mobile was first announced at Akademy 2015, the team put me in charge of the creation of a crucial pillar of the ecosystem: The Human Interface Guidelines for KDE phone applications. This means guidelines for “applications made by KDE for phones”, not “applications made for KDE Phone”, because

  1. There is no “KDE Phone”, just the phone UI of Plasma Mobile
  2. KDE applications for phones do not only run on Plasma Mobile, but may also run on e.g. Android, Ubuntu Touch or Sailfish OS

Of course third parties who design applications for Plasma Mobile should follow these guidelines as well.
Fortunately, I wasn’t alone with the herculean task of writing the HIG. Alex L. and Andrea del Sarto, two designers who started posting amazing Plasma Mobile mockups on Google+ right after it was announced, joined the effort right away.

We met in a Telegram group to discuss our ideas, and I started putting whatever we agreed upon on the Wiki, accompanied by mockups from Alex.

A HIG is not written in a day, though. The first step is thinking about some basic assumptions from which to derive basic interaction principles that some or all KDE phone applications will likely have in common. These assumptions and basic principles take the longest to come up with, because if they are to be used across most or all of KDE’s apps, they have to be very robust and applicable very generally.

So here are some of the assumptions we made so far and user interface patterns we derived from them:

1. Convergence is the goal, but each device gets its optimized UI

Calligra Gemini as an example for a converged application

Calligra Gemini as an example for a converged application

We live in a world where barriers between different device classes become more and more blurred. Tablets become laptops by attaching hardware keyboards and pointing devices, smartphones can be put into docking stations that turn them into desktop PCs, a smartphone can turn a TV into a mediacenter.

One approach to deal with such a converging world is to simply scale user interfaces to fit the screen, but this is far from ideal. A smartphone isn’t just a laptop with a smaller screen where the mouse is replaced by your finger, and even tablets and smartphones are used differently.

A device used with keyboard and mouse can use interaction methods like mouse-over, right-/middle-click or keyboard shortcuts, which are not available on a touchscreen. A touchscreen, on the other hand, can use all kinds of gestures which are unavailable on a mouse.

The input method is not the only important difference, however. For another example, a phone is mostly used in portrait mode and often interacted with using only one hand (with the other hand either holding the phone or not touching it at all) , whereas a tablet is mostly used in landscape mode with both hands available. These differences may seem superficial at first, but if you want to create user interfaces that feel truly comfortable, you can’t just ignore them and simply scale your UI to the target screen size and pixel density.

One HIG to rule them all

Therefore, KDE approaches convergence by designing optimized user interfaces for each device class the application targets, often even with different task priorities: As you can see in the screenshots above, Calligra Gemini Stage focuses on creation or fundamental editing of presentations in desktop mode, whereas tablet mode is focused on interactive presentations and minor touch-ups.

Nevertheless, we want designers/ developers to keep all target device classes in mind when designing a UI, which is why I decided against completely separating phone, tablet and desktop Human Interface Guidelines. Instead, currently the guidelines for different form factors are just different sections on the same page, with guidelines that apply to all device classes at the beginning. We might adjust that organization in the future, but there will always be just one central HIG document which only branches out where the guidelines for different device classes actually diverge.

2. Phones are more for communication and content consumption than for content creation

As already seen in the example of Calligra Gemini, different devices have their strengths for different tasks. Phones are great for checking news or emails on the go, but writing a book or even just creating a presentation on a phone isn’t much fun. Following this assumption, the phone HIG emphasizes patterns for browsing and viewing content over those for creating it.

3. Users prefer to interact with the center of the screen

A typical way of holding a phone, making the center of the screen the easiest to reach

A typical way of holding a phone, making the center of the screen the easiest to reach

As research shows, smartphones are predominantly held upright (portrait mode) and in one hand, simply because that is the most convenient way to use it and it leaves one hand free e.g. to hold onto something while standing in a bus.

If we want an application to be used conveniently with one hand, we have to make sure that everything that is needed often can be reached with that hand’s thumb without having to reposition the hand (although the aforementioned research also shows that people do switch how they hold their phone whenever needed).

Regardless of the way users hold their phone, research shows they generally are more precise in interacting with – and prefer to interact with – the center of the screen.

Based on these findings, the HIG recommends interaction patterns which do not require users to reach for the far ends of the screen (mostly the top), but give them on-demand controls near the center of the screen.

4. Space is limited, and content is king.

Although smartphone screens have been getting bigger and bigger over time, they are still very small compared to laptop or desktop screens. Since neither readability nor comfortable interaction should be sacrificed by just making things smaller, we have to find other ways to save space compared to desktop or tablet user interfaces.

In combination with assumption 2) that most phone applications are used more for viewing than for manipulating content, this leads us to the approach that the limited screen space should be mostly reserved for content, with controls only exposed when needed.

5. Content often has a hierarchical structure

Column-based navigation according to the HIG

Column-based navigation according to the HIG

We have found that often the content to be browsed through has an inherent hierarchical structure. Whether it’s files in a folder hierarchy, emails in (sub)folders in accounts, news items in feeds (optionally) in folders or tracks in albums by artists, one often has several levels of hierarchy to browse through to get to the object one wants to see.

And since navigating through that hierarchy is often one of the tasks the user performs most often with these applications, optimizing the interaction for that task will make using the application overall more efficient and a more pleasant experience.

What’s next?

With these assumptions in mind, we set out to create the actual Human Interface Guidelines. In part 2 of this series, I will talk about the process of we write the HIGs while Marco Martin is working on creating components to help developers create HIG-compliant applications easily.

Now I’d like to know, dear reader: Do you agree with our assumptions, or do you disagree with some of them? I’d love to hear your opinion in the comments!

Tagged with: ,
Posted in KDE

This is what we do if someone offers us some constructive criticism

A whiteboard at the "Phoronix BoF" at Akademy

In July, Eric Griffith wrote an article at Phoronix where he compared Plasma and KDE Applications to GNOME and detailed where they do things better than us and what he finds annoying about our software. We don’t react to angry ranting, but Eric took the time to point out in detail where exactly we could do better, and I found that in many regards, he had a point.

We in KDE don’t ignore constructive feedback, so at Akademy, we set out to find solutions to the issues he pointed out. In order to maximize the reach of our efforts’ documentation, I decided to write a two-part series about it over at Linux Veda, a “web-magazine to share and spread knowledge about Linux and Open Source technologies” which has always been very interested in – and generally supportive of – KDE.

So far I’ve finished the first part, which covers the login screen, KWallet and media player applications.

Tagged with: , ,
Posted in KDE

How to install ArangoDB on Arch Linux or Manjaro Linux

Arango on Manjaro

After J Patrick Davenport told me all about the advantages of ArangoDB during my Interview with him, it’s now time to get my hands dirty with the software.

Yes, I know, a rolling-release distribution such as Arch Linux isn’t exactly a common choice for production servers, but

  1. Arch-based distros are great for trying things out because it’s so easy to get the hottest and newest stuff on them
  2. I run the Arch-based Manjaro Linux on all my computers and I don’t need a dedicated server just to get familiar with a new piece of software

and therefore I’m just going to install ArangoDB on my Manjaro machine first. Ha! And while I’m at it, I’ll document what I did so you can easily repeat the steps.

While ArangoDB offers packages for all major operating systems (even including Raspbian, which is awesomely geeky) in their download section, there isn’t one for Arch. This makes sense, because a) Arch isn’t commonly used on servers and b) the common way to get third-party software on Arch isn’t pre-built packages, but the Arch User Repository (AUR), which is basically just a site that hosts build scripts for users to compile software automatically on their own machines.

The downside, of course, is that the burden of compiling is transferred to the user, but the advantage of that system is that it makes maintaining an AUR package as easy as writing a build script and updating it when new versions of the software come out or the source code URL changes. That – and the fact that the Arch community is just hyperactive – are probably the reasons why you have to try really hard to find a piece of software for which no AUR package exists. And since Manjaro Linux is fully compatible with Arch, it is also fully compatible with pretty much any AUR package (the only exception would be if the AUR package depended on other packages which have only just arrived in the Arch repos and therefore still needed some time to arrive in Manjaro).

So, if you run an Arch-based distro and in case you have yaourt installed, normally what you’d do in order to get ArangoDB would be

yaourt -S arangodb

if you wanted the latest stable release or

yaourt -S arangodb-git

if you’d like to compile directly from the development repository (for example if you’d like to become an ArangoDB  contributor).

I say “normally” because unfortunately, at the time of writing, the stable AUR package is out of date (it is at version 2.6.0 while the latest stable release is 2.6.2). The problem is that 2.6.0 does not compile correctly with current GCC, so the compilation of the current version of the AUR package will exit at some point with an error. I have already commented on the AUR package asking for it to be updated, but until that happens, you can use my patched PKGBUILD file from my Dropbox. Just download the file, put it somewhere with enough space (I haven’t measured, but commenters say that the build takes up to 3.2 GB of space at its peak, but don’t worry, the resulting package takes less than 200MB of space), then run

makepkg -i

in that directory to automatically download the source files and build ArangoDB.

UPDATE: By now, the AUR package has been updated to version 2.6.2, so you can now use it directly.

Whichever route you take, both yaourt and makepkg will automatically install any unmet dependencies (on my machine I had everything except Go), compile ArangoDB and offer you to install it.

The post-install script will ask you to run a database upgrade if you have an existing ArangoDB database, and enable and start the ArangoDB systemd service. If you’re installing ArangoDB for the first time, you can safely ignore the first instruction.

Since I’ve installed ArangoDB on my machine only for taking my first steps in it and not to run an actual server, I didn’t enable the service so that it won’t auto-start with every boot. I just started it manually with

sudo systemctl start arangodb.service

After that, to see if ArangoDB runs properly, you can direct your browser to


and you should be greeted by its web interface.

The ArangoDB web interface

The ArangoDB web interface

However, after reboot, ArangoDB wouldn’t start anymore on my system. “systemctl status” told me that it had exited with “FATAL cannot write pid-file ‘/var/run/arangodb/arangod.pid'”. If you’re running into the same problem, create a file “arangodb.conf” in /lib/tmpfiles.d/ with the following content:

d /var/run/arangodb 0755 arangodb arangodb -

This tells systemd to create a folder on startup if the service is enabled, which is writeable by the arangodb user (and readable by everyone else).

To create the needed directory immediately instead of after the next restart, run

sudo systemd-tmpfiles --create arangodb.conf


sudo systemctl start arangodb.service

should work again.

Congratulations, you should now have a working ArangoDB installation!

As the next step, if you haven’t already done so, I’d recommend checking out the First Steps section of the ArangodB documentation to make yourself familiar with the database. In the chapter Collections you will learn how to create your first collection with some documents in it and query for them. This also shows you if your installation really works.

If you’d like to try out ArangoDB on an Arch-based distro, I hope you will find this little how-to helpful. If there is anything unclear or not working, please comment and I’ll be glad to help ypu!

Posted in ArangoDB