Migrating configuration and data files for sandboxed apps

Hello fellow developers!

I’m sure many of you have read the blog post I wrote about sandboxing. Now that the Sailfish OS 4.3.0 has reached the Early Access stage, you can also move to the next stage with your app: Defining the profile for your app.

Like I mentioned in the blog, we used to have application configuration files in directories named in the format .config/harbour-appname. In the future we no longer want that - the configuration files should instead be located in directories with the format .config/OrganizationName/ApplicationName. So that’s where you should write your configurations from now on. But what about the old configuration files which were already written in .config/harbour-appname? Do we lose access to them? Fear not, that is not the case!

Starting with Sailfish OS 4.3.0, if the .config/harbour-appname directory exists, it will also be visible in the sandbox. So basically, this is what you should do in order to migrate your configuration:

  1. If your configuration files exist in .config/OrganizationName/ApplicationName, use them

  2. If not, check if they exist in .config/harbour-appname, and if they do, read them from there

  3. Write configuration files to .config/OrganizationName/ApplicationName

You can use something like the following code to migrate your configuration from the old location to the new:

void MySettings::migrateSettings()
    // The new location of config file
    QSettings settings(QStandardPaths::writableLocation(QStandardPaths::ConfigLocation) + "/my.domain/MyApp/MyApp.conf", QSettings::NativeFormat);

    if (settings.contains("migrated"))

    QSettings oldSettings(QStandardPaths::writableLocation(QStandardPaths::ConfigLocation) + "/harbour-myapp/harbour-myapp.conf", QSettings::NativeFormat);

    for (const QString& key : oldSettings.childKeys())
        settings.setValue(key, oldSettings.value(key));

    settings.setValue("migrated", "true");

Similar migration strategy could be used also for .local/share and .cache directories - you may also want to consider just copying the files over.


Dear @vige, you might clarify if a fresh installation of extant apps, which are not explicitly updated for the sandboxing yet, will still be able to create their directories ~/{.local/share,.config,.cache}/packagename and files in it on SailfishOS ≥ 4.3.0?

Currently you only address "configuration files which were already written in .config/harbour-appname", which supposedly means “before upgrading to SailfishOS 4.3.0”.

Rereading our conversation at the former thread about the topic “configuration and data files of apps with Jolla’s sandboxing” you did not say that all these directories will be creatable and writeable (just “mounted”):

Mind that many apps in the Jolla Store and at Openrepos are not well maintained or unmaintained, although still well working, and if they are not installable any more on recent SailfishOS releases, this will significantly reduce the already slim set of available apps for SailfishOS.
Hence backward compatibility is crucial.

1 Like

My understanding, which is based on empirical testing on current code (which hopefully becomes release 4.4.0), is that the sailjail implementation creates the harbour-packagename directories for the applications which have not specified their own profiles. For the applications which have specified their profiles, the directories are not created, but are still mounted if they exist.


Thank you very much, that is exactly the clarification / unambiguous wording I wanted to see documented.
Plus WRT its content it is exactly what I hoped for (but became seriously wary).

And as you are the chief designer of SailJail AFAIU, I assume that this also is the intended behaviour, even if the implementation may deviate, right?

P.S.: I am really glad that this is fine on this abstract level, for the more specific / detailed questions and concerns, see the other, older thread.

I’m not the chief designer of sailjail. Your assumption about the intended behaviour is still valid though.

1 Like

Thank you for the code snippet for migration.

Couple of follow-up questions:

  1. Is there a similar “Best Practice” solution for pure QML apps (or QML+Python or other non-Qt/QSettings applications), especially those using JS LocalStorage?

So, if my app currently does something like:

invoker --type=silica-qt5 sailfish-qml my-appname

to launch, which changes are needed apart from making it

sailjail -p my-appname.desktop /usr/bin/sailfish-qml my-appname

E.g. is it required/necessary/recommended/forbidden to do something like

ApplicationWindow {
  Component.onCompleted: {
    Qt.application.name         = "appname";
    Qt.application.organization = "my-orga";

… and if yes, how do Qt.application.XXX values map to the ones in the .desktop files.

  1. In my tests (4.2) sailjail frequently did not accept the .desktop appname as valid. What are the rules for names for application and organisation?

specifically it seems for


foo is not allowed to contain a hyphen?

1 Like

No there isn’t. For the time being, my recommendation for the old pure QML apps is to not define their own profiles, i.e. keep using the old locations. For new apps I’d recommend defining the profiles and using the new locations.

I think the answer to all of these is “no”.

As long as you are using libsailfishapp, the values are set automatically, using the values from the .desktop files.

For ApplicationName: Allowed characters are A-Z, a-z, 0-9, underscore (_) and hyphen(-). The name may not start with a number.
For OrganizationName: Same characters as ApplicationName, and a dot (.), which is used for separating components. Any component may not start with a number. There are some names which are not allowed. Currently the list of disallowed OrganizationNames contains only “com.jolla” and “org.sailfishos”.


Excellent. Thank you.

A funny thing is that i made the exact opposite change to comply to harbour policy when i first published the app to jolla store ( https://github.com/Julien-Blanc-tgcm/kontroller/commit/d9007befef4aff4948820e1e9917ede0b3c621d9 )

My understanding is that the appname no longer needs to be harbour- prefixed. Is that correct ? Or is it just for the settings part ?

The ApplicationName in the X-Sailjail section of the .desktop file does not have to be harbour-prefixed. This in turn means that the directory names in ~/{.local/share,.config,.cache} also no longer need to have the harbour- prefix. For the RPM package name and the binary name the old requirements still apply.

1 Like

Yea, and I distinctly remember there was a similar migration a long time ago when all apps were moved out of their “orga name” subdirectories. Was that early SailfishOS? Or even Meego Harmattan times? I forget.