{"id":19153829,"url":"https://github.com/flatpak/meta-flatpak","last_synced_at":"2025-07-20T19:33:29.856Z","repository":{"id":40269495,"uuid":"414125650","full_name":"flatpak/meta-flatpak","owner":"flatpak","description":null,"archived":false,"fork":false,"pushed_at":"2022-05-17T08:27:47.000Z","size":199,"stargazers_count":7,"open_issues_count":5,"forks_count":3,"subscribers_count":3,"default_branch":"AGL","last_synced_at":"2025-07-08T19:32:59.168Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"Shell","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/flatpak.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"COPYING.MIT","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2021-10-06T08:12:59.000Z","updated_at":"2024-06-25T16:19:57.000Z","dependencies_parsed_at":"2022-08-17T21:50:58.375Z","dependency_job_id":null,"html_url":"https://github.com/flatpak/meta-flatpak","commit_stats":null,"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/flatpak/meta-flatpak","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/flatpak%2Fmeta-flatpak","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/flatpak%2Fmeta-flatpak/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/flatpak%2Fmeta-flatpak/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/flatpak%2Fmeta-flatpak/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/flatpak","download_url":"https://codeload.github.com/flatpak/meta-flatpak/tar.gz/refs/heads/AGL","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/flatpak%2Fmeta-flatpak/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":265097055,"owners_count":23710819,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2024-11-09T08:24:29.352Z","updated_at":"2025-07-20T19:33:29.839Z","avatar_url":"https://github.com/flatpak.png","language":"Shell","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Introduction\n\nmeta-flatpak is a Yocto layer with the primary aim to add support\nfor compiling, installing and running flatpak applications on devices\nwith a flatpak-enabled Yocto image.\n\nFlatpak (http://flatpak.org) is a framework for building, distributing\nand installing applications. It conceptually splits the software stack\ninto commonly used bits (runtimes, runtime SDKs) and application-specific\nbits (the application itself). Flatpak decouples the lifecycle of the\napplication from the lifecycle of the underlying OS/distro. The distro\nand the applications can be updated independently from each other. Flatpak\nadditionally provides application sandboxing out of the box and an\ninfrastructure for application deployment.\n\nFlatpak relies on OSTree/libOSTree (http://ostree.readthedocs.io.)\nas the distribution mechanism for applications and runtimes. OSTree is\na library and suite of command line tools that provide a version\ncontrol and distribution mechanism for bootable OS filesystem trees,\nor other binaries. It is very 'git-like' and indeed it has been\nlargely inspired by git. OSTree also contains functionality for\nmanaging the boot loader configuration as OSTree-managed filesystem\ntrees are deployed.\n\nFor more information about flatpak and OSTree please refer to their\ncorresponding documentations at the sites dedicated to these projects.\n\n\n# Basic Flatpak Functionality\n\nFlatpak provides a managed runtime by splitting up the software stack\nroughly into three categories: runtimes, runtime SDKs, and the applications\nthemselves.\n\nRuntimes are the common shared userspace functionality sitting above the\nkernel and below the applications in the stack. In a Linux desktop stack\na runtime could include, for instance, the posix-compatible libraries,\nX11 libraries, wayland, and the gnome desktop. Another one could provide\nthe KDE desktop instead of gnome, while a third one could opt for Xfce4,\ninstead.\n\nThe runtime SDKs include the runtime itself, the compiler toolchain and\nthe necessary other development tools for compiling and developing for\nthe runtime and the necessary headers, libraries, etc.\n\nFinally, the applications contain the application-specific bits and\nat least any libraries they use which are not provided by the runtime,\nalthough they choose to do so they can contain a copy of all the\nlibraries they depend on.\n\nWith this setup, to install an application you install the runtime the\napplication was compiled against and the application itself. If several\napplications use the same version of the same runtime, which is usually\nthe case, they share a single copy of that runtime version. Also, when\na runtime is updated, two or more versions can be co-hosted parallel\nas long as necessary, until all the applications have been updated to\nuse the latest one.\n\nTo develop/compile an application, you install the runtime SDK on your\ndevelopment machine and use flatpak-build to compile against your target\nruntime and SDK.\n\nRuntimes, runtime SDKs and applications are kept and published in flatpak\nrepositories, which are OSTree repositories with a flatpak-specific layout.\nRepositories in archive-z2 format can be published over HTTP using any\nHTTP server. Applications, runtimes, and runtime SDKs are pulled into\ndevices and development hosts from these published repositories. The\nrepositories support tags and branches in a git-like manner, allowing one\nto easily manage paraller versions and configurations of the same software.\nAdditionally, repositories support GPG-signing for verifying the\nauthenticity and intactness of the published components.\n\n\n# OSTree Functionality\n\nflatpak and consequently meta-flatpak require OSTree, since flatpak\nrepositories are OSTree repositories with a particular flatpak-specific\nfilesystem tree layout and branch naming conventions. To be self-contained\nmeta-flatpak can provide recipes for OSTree and its dependencies. However,\nsince there are parallel independent efforts/layers to bring OSTree support\nto Yocto (meta-updater and meta-ostree, for instance), flatpak can and will\nprefer to use OSTree from one of these layers, if it is present and enabled\n(provided the layer has its priority set to 6 or higher).\n\nIn the absence of an external OSTree layer, the OSTree functionality provided\nby meta-flatpak is limited to merely making the OSTree binaries and libraries\navailable. In particular, meta-flatpak does not provide any integration of\nOSTree to image update process and bootloader.\n\n\n# Additional Functionality\n\nIn addition to the basic flatpak functionality meta-flatpak contains a\nsmall daemon, flatpak-session, that if enabled will monitor certain\nremotes, install and update applications published there and automatically\nstart these applications at system startup time.\n\nThe pre-conditions for a remote to be treated this way is to\n\n  * have a system user associated with the remote, and\n  * the remote to be marked as enumerable\n\nA user is considered to be associated with remote \u003cr\u003e if the users\nGECOS is set to \"flatpak user for \u003cr\u003e\". All applications from a remote\nare run within an automatic seatless login session of the associated\nuser. Currently there is no way to guarantee startup order of applications\nif there are more than one installed from a single remote. Applications\nare started in the order of discovery.\n\n\n# Building And Testing meta-flatpak\n\nAt the moment the easiest way to test meta-flatpak is to use the pre-\nconfigured repository found at http://github.com/klihub/intel-iot-refkit.\nThis repository is a clone/fork of http://github.com/intel/intel-iot-refkit\nwith a few necessary patches and the flatpak layer added on top using git\nsubmodules.\n\n\n## Getting The Necessary Bits In Place\n\nClone the repository and let it pull in its submodules:\n\n```\ngit clone https://github.com/klihub/intel-iot-refkit.git\ngit submodule init\ngit submodule update --recursive\n```\n\n## Configuring Your Builds\n\nNext you need to tweak your default configuration a little bit to\nenable flatpak and make the built images more friendly for development\nor just general poking around. If you're uninterested in the details,\njust cut and paste the following section to the end of your\nconf/local.conf. Otherwise skip this and read on. We'll be doing the\nsame thing but one at a time and with a bit of explanation.\n\n```\n# Append these to your default build/conf/local.conf.\n\n# Chose the default configuration for developement.\nrequire conf/distro/include/refkit-development.inc\n\n# We'll be using qemu on our host, not real dedicated hardware.\n# We'll also want SDL-base VGA emulation for qemu.\nMACHINE=\"qemux86-64\"\nPACKAGECONFIG_append_pn-qemu-native = \" sdl\"\nPACKAGECONFIG_append_pn-nativesdk-qemu = \" sdl\"\n\n# We'll want to be able to ssh/scp to/from our box/qemu.\nREFKIT_IMAGE_EXTRA_FEATURES = \"debug-tweaks\"\nREFKIT_IMAGE_EXTRA_INSTALL += \"openssh-sshd openssh-ssh openssh-scp\"\n# We'll be playing with applications that need termcap and curses.\nREFKIT_IMAGE_EXTRA_INSTALL += \"ncurses\"\n\n# Pull in the configuration bits for enabling flatpak applications.\nrequire conf/distro/include/flatpak-applications.inc\n\n# By default meta-flatpak will only generate flatpak runtime repositories\n# for SDK images. We'll want to also test how we can use flatpak to drop\n# into a shell running inside a container with our runtime image. So we\n# ask meta flatpak to generate repositories for any flatpak-enabled image.\nFLATPAK_IMAGE_PATTERN = \"glob:*-flatpak*\"\n```\n\nNote that in the examples we'll be using qemu on our development host\nto run the images we build instead of using real dedicated hardware.\nYou can change the qemu-related bits in the configuration above if you\nprefer to test with real hardware instead.\n\n\nAlternatively you can execute the following set of commands to get to\nan equivalent configuration.\n\n* enable the default development configuration:\n\n```\nsed -e 's:^#\\(require .*/refkit-dev.*\\):\\1:' -i conf/local.conf\n```\n\n* select 64-bit x86 qemu as the target machine:\n\n```\necho 'MACHINE = \"qemux86-64\"' \u003e\u003e conf/local.conf\n```\n\n* we prefer SDL-based VGA emulation for qemu instead of VNC:\n\n```\necho 'PACKAGECONFIG_append_pn-qemu-native = \" sdl\"' \u003e\u003e conf/local.conf\necho 'PACKAGECONFIG_append_pn-nativesdk-qemu = \" sdl\"' \u003e\u003e conf/local.conf\n```\n\n* prefer a less secure but more development-friendly setup:\n\n```\necho 'REFKIT_IMAGE_EXTRA_FEATURES = \"debug-tweaks\"' \u003e\u003e conf/local.conf\n```\n\n* install sshd, ssh, and scp for easy copying stuff back and forth:\n\n```\necho 'REFKIT_IMAGE_EXTRA_INSTALL += \"openssh-sshd openssh-ssh openssh-scp\"' \u003e\u003e conf/local.conf\n```\n\n* we'll be compiling applications that need ncurses and termcap:\n\n```\necho 'REFKIT_IMAGE_EXTRA_INSTALL += \"ncurses\"' \u003e\u003e conf/local.conf\n```\n\n* pull in the configuration bits enabling flatpak applications:\n\n```\necho 'require conf/distro/include/flatpak-applications.inc' \u003e\u003e conf/local.conf\n```\n\nBy default meta-flatpak generates runtime repositories out of flatpak-\nenabled SDK-capable images. We'll want to play around with flatpak to\nsee how we can use it to drop into a shell running in a 'container'\nwith other runtime images. Hence we change the default configuration to\nmatch all images.\n\n* and finally enable flatpak repository generation for all images:\n\n```\necho 'FLATPAK_IMAGE_PATTERN = \"glob:*\"' \u003e\u003e conf/local.conf\n```\n\n\n## Building\n\nRemember that if you're running in a different shell (for instance in\na different terminal) than the set of preparating commands from the\nprevious section, you should initialize your environment for bitbaking.\nThis is done with the following command:\n\n```\n. ./refkit-init-build-env\n```\n\nor\n\n```\nsource ./refkit-init-build-env\n```\n\n\nOkay, now with everything hopefully set up properly, we should be ready\nto build a ourselves a few test images and repositories. We'll start with\nthe flatpak-enabled version of a minimal runtime image.\n\n\n```\n# Build a flatpak enabled minimal image.\nbitbake refkit-image-minimal-flatpak-runtime\n```\n\nWhile bitbake is pretty smart about avoiding unnecessary work and\nespecially compilation, there is no way around the fact that during\nyour initial build there is a fair bit of code to download and\ncompile. \n\nIf you don't have a fast machine with lots of memory and fast SSDs or\na very fast internet connection, this might be a good time to make and\ngrab a cup o'joe, sit back and wonder about whatever is your favourite\npastime subject to wonder about.\n\nOnce bitbake is finished you should be left with a bunch of image-related\nfiles in *tmp-glibc/deploy/images/qemux86-64*, all of which should be named\nafter the image you built, hence in our case\n*refkit-image-minimal-flatpak-runtime*.\n\nYou should also have a few similarly named flatpak-related files directly\nunder *build*, your current working directory. These should include:\n\n  * a flatpak (OSTree) repository containing your image (.flatpak)\n  * an Apache2 configuration file for exporting your repository (.http.conf)\n  * a GPG private key for signing your repository (.sec)\n  * a GPG public key for clients to check your signatures (.pub)\n\n\nOnce you have verified you got all these in place, you can go ahead and\nbuild the corresponding SDK image.\n\n```\n# Build a flatpak SDK image for the flatpak-enabled minimal image.\nbitbake refkit-image-minimal-flatpak-sdk\n```\n\nYou should get a similar bunch of corresponding image- and flatpak-related\nfiles in *tmp-glibc/deploy/images/qemux86-64* and directly in *build* all\nstarting with *refkit-image-minimal-flatpak-sdk*.\n\n\n# Testing\n\n## Testing The Basic Flatpak Functionality\n\nWe'd like to test first the full chain of generating and publishing a\nflatpak for our device (which in this case is our image running in qemu).\nTo get from source code to a flatpak application installed on our target\ndevice will take a fair number of steps:\n\n* publishing the repository hosting our flatpak-enabled images\n* installing the flatpak SDK image to our development host\n* taking some test code and flatpak-building it for our runtime image\n* exporting the resulting binary as a flatpak application in a repository\n* letting our target device know about the application repository\n* pulling in the flatpak application from the repository to the device, and\n* testing the application on our device\n\nLet's see what each of these steps means in practice in more detail.\n\n### Publishing SDK Image Repository\n\nWe need the SDK runtime to be able to compile for our target device.\nWith flatpak, the runtime, SDK runtime, and applications are all \ndistributed in a uniform way using OSTree repositories. We do have our\nfreshly built repository available, but we still need to let flatpak\non our develpment machine know about it and access it. Two things are\nnecessary for this:\n\n* we need to export the repository over HTTP\n* we need to let flatpak on our machine know about the repository\n\nmeta-flatpak has already generated an apache2 configuration fragment for\nexporting the repository. If you run apache on your machine, you simply\nneed to drop this in place and restart apache. For my distro of choice\nthis can be accomplished with the following commands:\n\n```\nmandark build $ sudo cp ./refkit-image-minimal-flatpak-sdk.flatpak.http.conf /etc/httpd/conf.d\nmandark build $ sudo systemctl restart httpd\n```\n\nNext we need to let flatpak on our machine know about the repository. This\ncan be done with the following command. If you're unsure about the correct\nURI and filesystem paths, take peak inside the generate http.conf file.\n\n```\nmandark build $ flatpak remote-add refkit-image-minimal-flatpak-sdk --gpg-import=./refkit-image-minimal.pub http://127.0.0.1/flatpak/refkit-image-minimal/sdk\n```\n\nYou should be able to see now your newly added remote repository when you\nlist the available remotes on your machine:\n\n```\nmandark build $ flatpak remote-list\ngnome                           \nrefkit-image-minimal-flatpak-sdk\nrefkit-runtime                  \nrefkit-runtime-minimal          \ncom.spotify.Client-1-origin     \ncom.spotify.Client-2-origin     \ncom.spotify.Client-3-origin     \ncom.spotify.Client-4-origin     \ncom.spotify.Client-origin       \n```\n\nYou should see *refkit-image-minimal-flatpak-sdk* show up in the list.\nAdditionally, you should see our SDK if you list the runtimes available\nfrom that remote:\n\n```\nmandark build $ flatpak remote-ls --runtime -d refkit-image-minimal-flatpak-sdk\nruntime/iot.refkit.BaseSdk/x86_64/20170210162508 a9b9124b15e3\nruntime/iot.refkit.BaseSdk/x86_64/current 71eedc5de6e8\n```\n\nYou should see *iot.refkit.BaseSdk* show up among the listed runtimes.\nLet's pull in the SDK runtime to our machine with the following command.\n\n```\nmandark build $ flatpak install refkit-image-minimal-flatpak-sdk iot.refkit.BaseSdk runtime/x86_64/current\nWarning: Can't find dependencies: No flatpak cache in remote summary\nUpdating: iot.refkit.BaseSdk/x86_64/current from refkit-image-minimal-flatpak-sdk\n\n110 metadata, 1515 content objects fetched; 12646 KiB transferred in 1 seconds  \nNow at 71eedc5de6e8.\n```\n\nWe chose to install the branch runtime/x86_64/current which meta-flatpak\nalways sets to point to the last version built. If you want to see all\navailable versions, you can run\n\nIf everything went ok this far, we should be now ready to compile some\ntest application for our target device using the flatpak runtime SDK.\nSince our image probably does not have a proper editor like emacs, let's\nclone vim and try to flatpak-build it so that we can do at least some\nbasic editing on the device.\n\n```\nmandark build $ mkdir test\nmandark build $ cd test\nmandark test $ git clone https://github.com/vim/vim.git\n```\n\nNext we create a directory for flatpak-build to put files into and\ninitialize and initialize flatpak-build to point to it and tell it\nthe runtime, SDK version and application name and version we'll be\nusing and building.\n\n```\nmandark test $ mkdir build.vim\nmandark test $ flatpak build-init build.vim org.vim.vim iot.refkit.BaseSdk iot.refkit.BasePlatform current\n```\n\nIf everything went successfully, we're now ready to go through the\nordinary configure/compile/install cycle for our application. We just\nneed to remember to prefix all these commands with flatpak build to\nlet it do its magic.\n\n```\nmandark test $ cd vim\nmandark vim $ flatpak build ../build.vim ./configure --prefix=/app\n...\nmandark vim $ flatpak build ../build.vim make\n...\nmandard vim $ flatpak build ../build.vim make install\n```\n\nThe first flatpak build/configure command configures vim for building\nas a flatpak application. Flatpak expects all files belonging to the\napplication relocated under /app so we provide the necessary option\nto configure. The second and third commands simply run the normal\ncompilation and installation commands under flatpak build.\n\nIf all went fine, we should next finalize the build, telling flatpak\nhow our application should be started. Additionally we'll tell flatpak\nthat our application will need fill read-write access to the home\ndirectory. Our editor would not be very handy if it couldn't save files.\nIf we wanted to give our editor read-write access to other directories\nwe can do so by giving more similar command-line arguments. If we wanted\nto provide access to the whole filesystem we could use 'host' as the\nargument instead of 'home' or a particular path. Read-only access can be\ngranted by appending :ro to the argument. For more options controlling\nthe sandboxing features of flatpak for an application see the manual page\nof flatpak-build-finish(1).\n\n```\nmandard vim $ flatpak build-finish ../build.vim --command=vim --filesystem=home\n```\n\nIf all goes fine flatpak generates an application metadata file\nin ../build.vim for us. Before exporting our application in the\nrepository we should take a look at this file and make any necessary\nadjustments we see fit.\n\nLet's first take a look at the content of our build directory:\n\n```\nmandark vim $ ls -Fal ../build.vim\ntotal 24\ndrwxrwxr-x 5 kli kli 4096 Feb  9 20:08 ./\ndrwxrwxr-x 5 kli kli 4096 Feb 10 18:56 ../\ndrwxrwxr-x 2 kli kli 4096 Feb  9 20:05 export/\ndrwxrwxr-x 4 kli kli 4096 Feb  9 20:05 files/\n-rw-rw-r-- 1 kli kli  167 Feb  9 20:08 metadata\ndrwxrwxr-x 3 kli kli 4096 Feb  9 20:02 var/\n```\n\nNext we take a peak at the metadata:\n\n```\nmandark vim $ cat ../build.vim/metadata \n[Context]\nfilesystems=home\n\n[Application]\nname=org.vim.vim\nruntime=iot.refkit.BasePlatform/x86_64/current\nsdk=iot.refkit.BaseSdk/x86_64/current\ncommand=vim\n```\n\nSince everything looks okay, we tell flatpak to do the final pieces\nof necessary processing to export vim to a flatpak repository.\n\n```\nmandark vim $ flatpak build-export --gpg-homedir=\u003cpath-to-build\u003e/gpg --gpg-sign=refkit-image-minimal@key ../vim.flatpak ../build.vim\nCommit: f15cb7341253a597536c16bfa2f219731eb8451e826f9527c8dc68e94db208e5\nMetadata Total: 289\nMetadata Written: 128\nContent Total: 1741\nContent Written: 1637\nContent Bytes Written: 28595251 (28.6 MB)\n```\n\nAs you can see, we provided flatpak with a GPG keyring (in the given\nGPG home directory) and a key ID to use for signing the application\nrepository. We used the key generated by meta-flatpak here but we\nreally could have used any other key of our choice.\n\nIf everything went fine, at this point we should have vim available\nin a our newly built flatpak repository, ../vim.flatpak. Now, to test\nour vim flatpak on the device, we need to first export our vim repository\nover HTTP. For that we wnat to generate a configuration fragment for\nexporting our application repositories. One easy way to do this is the\nfollowing command:\n\n```\nmandark vim $ cd ..\nmandark build $ echo -e \"Alias \\\"/apps/\\\" \\\"$(pwd)\\\"\\n\\n\u003cDirectory $(pwd)/\u003e\\n    Options Indexes FollowSymlinks\\n    Require all granted\\n\u003c/Directory\u003e\" \u003e flatpak-apps.http.conf\nmandark build $ cat flatpak-apps.http.conf\nAlias \"/apps/\" \"/v/src/users/kli/work/IoT/refkit/intel-iot-refkit/build/\"\n\n\u003cDirectory /v/src/users/kli/work/IoT/refkit/intel-iot-refkit/build/\u003e\n    Options Indexes FollowSymlinks\n    Require all granted\n\u003c/Directory\u003e\n```\n\nNow we drop this confiuration file into our apache configuration and\nrestart it. For my distro of choice this can be done with the following:\n\n```\nmandark build $ sudo cp flatpak-apps.http.conf /etc/httpd/conf.d\nmandark build $ sudo systemctl restart httpd\n```\n\nNext we need to boot up our test image with qemu. Before doing so, it\nmight be a good idea to give qemu a slightly more generous amount of\nmemory than the default 256 M. This can be done with the following\ncommands:\n\n```\nmandark build $ sed -e 's/-m 256/-m 1024/' -i tmp-glibc/deploy/images/qemux86-64/refkit-image-minimal-flatpak-runtime-qemux86-64.qemuboot.conf\n```\n\nOnce done, we can start our runtime image in qemu:\n\n```\nmandark build $ runqemu tmp-glibc/deploy/images/qemux86-64/refkit-image-minimal-flatpak-runtime-qemux86-64.qemuboot.conf \n```\n\nThis should boot the image in qemu and leave us with an emulated console\nwith an automaically logged in root shell (and this is why you should use\nthe debug-tweak feature only in your fully controlled and trusted development\nenvironment).\n\nBy default qemu uses a tap interface configured with 192.168.7.1 for the\nlocal end and 192.168.7.2 for the emulated host end. Hence, you should now\nbe able to also log in to your qemu instance using ssh with the following\ncommand:\n\n```\nmandark build $ ssh root@192.168.7.2\nLast login: Fri Feb 10 17:32:37 2017\n************************************\n*** This is a development image! ***\n*** Do not use in production.    ***\n************************************\nroot@qemux86-64:~#\n```\n\nIf this works, copy the public key matching the private key you used to\nsign our vim flatpak repository.\n\n```\nmandark build $ scp refkit-image-minimal.pub root@192.168.7.2:\n```\n\nLet the runtime image know about our repository:\n\n```\nmandark build $ ssh root@192.168.7.2\nLast login: Fri Feb 10 17:32:37 2017\n************************************\n*** This is a development image! ***\n*** Do not use in production.    ***\n************************************\nroot@qemux86-64:~# flatpak remote-add test --gpg-import=refkit-image-minimal.pub\nhttp://192.168.7.1/apps/vim.flatpak\nroot@qemux86-64:~# flatpak remote-ls -d test\napp/org.vim.vim/x86_64/master f15cb7341253\n```\n\nIf all went fine and you were able to list the applications, you can now\ninstall vim as a flatpak:\n\n```\nroot@qemux86-64:~# flatpak install test org.vim.vim\nInstalling: org.vim.vim/x86_64/master from test\n\n131 metadata, 1637 content objects fetched; 10253 KiB transferred in 23 seconds \nroot@qemux86-64:~# flatpak list -d\norg.vim.vim/x86_64/master test f15cb7341253 - 29.4 MB system,current \n```\n\nAnd finally, if everything went ok we should be able to test our vim\nflatpak:\n\n```\nroot@qemux86-64:~# flatpak run org.vim.vim test-file\n...edit and save something in the file...\nroot@qemux86-64:~# cat test-file \nThe quick brown fox jumps over the lazy dog.\n```\n\nAnd that's it. If all this worked so far you're image is flatpak-enabled.\nIt can pull in software from remote flatpak repositories, and you can\nbuild flatpak SDK runtimes which you can use to compile software and\nexport it to flatpak repositories to be consumed by devices running a\nflatpak-enabled image.\n\n## Testing Flatpak-Based Application Support\n\nIn addition to the functionality directly offered by flatpak, meta-flatpak\noffers additional functionality, generally referred to as *'support for\nflatpak-based 3rd-party applications'*.\n\nIn practice, this means a few conventions and a small daemon that uses\n*libflatpak*. The conventions in the current model/setup dictate that\napplications from a single provider are\n\n * published in a dedicated per-provider remote\n * associated with a dedicated per-provider system user, and\n * run in an automatically created seatless session for this user\n\nThe daemons task is to \n\n * monitor dedicated flatpak remotes,\n * install flatpak applications from these remotes,\n * pull in any available updates for installed applications, and\n * arrange for the applications to be started during system boot\n\nAdditionally, meta-flatpak offers a mechanism for pre-declaring a set of\nrepositories for the images built. Devices running these images should\nstart pulling in and running applications from these repositories without\nfuther manual interventions.\n\nmeta-flatpak/flatpak-session defines a few additional pieces of possible\nflatpak metadata flatpak 3-rd party applications. These are:\n\n * X-Install (boolean): whether the application should be autoinstalled\n * X-Start (boolean): whether the application should be autostarted\n * X-Urgency (string): how urgent an update is, 'critical', 'important'\n\nThese keys should be in the *Application* section of the metadata file.\nYou should tag applications that should be automatically installed and\nstarted in the dedicated users' session with *X-Install=yes*, and\n*X-Start=yes*. While currently these are the defaults in the absence of\nthese keys, the defaults might change in the future. Explicitly stating\nthese among the metadata prevents changes to the defaults from affecting\nthe exhibited behavior.\n\nTo test this functionality, we will\n\n * modify our configuration to pre-populate the image with 3 repositories\n * publish a dummy test application in these repositories\n * boot into our newly built image to check that the apps get pulled in and run\n\nFirst, let's modify our configuration and declare 3 remotes/repositories.\nDeclaring a remote happens by\n\n * listing the remote name in the variable *FLATPAK_APP_REPOS*,\n * providing the key and URL in \u003cr\u003e.key and \u003cr\u003e.url in *${TOPDIR}/conf*, and\n * providing passwd and group entries for the users in *${TOPDIR}/conf/flatpak-{passwd,group}*\n\n\nWe'll call our remotes/repositories in an unimaginative way simply *test1*,\n*test2*, and *test3*. Let's declare these now in local.conf:\n\n```\nmandark build $ echo \"FLATPAK_APP_REPOS=\\\"test1 test2 test3\\\"\" \u003e\u003e conf/local.conf\n```\n\nWe'll also call the associated system users simply *test1*, *test2*, and\n*test3*. Let's create the necessary passwd and group fragments for these:\n\n```\nmandark build $ cat conf/flatpak-passwd\ntest1:x:2000:2000:flatpak user for test1:/home/test1:/bin/sh\ntest2:x:2001:2001:flatpak user for test2:/home/test2:/bin/sh\ntest3:x:2002:2002:flatpak user for test3:/home/test3:/bin/sh\n\nmandark build $ cat conf/flatpak-group\ntest1:x:2000:\ntest2:x:2001:\ntest3:x:2002:\n```\n\nNote that we created the entries with GECOs matching our association criteria\nfor flatpak-session. Let's now add key and URL files for these remotes. For\nsimplicity, we'll reuse the key we generated for our SDK image repo earlier:\n\n```\nmandark build $ for i in 1 2 3; do cp refkit-image-minimal.pub conf/test$i.key; done\n\nmandark build $ cat conf/test1.url\nhttp://192.168.7.1/apps/test1\n\nmandark build $ cat conf/test2.url\nhttp://192.168.7.1/apps/test2\n\nmandark build $ cat conf/test3.url\nhttp://192.168.7.1/apps/test3\n```\n\nNext we rebuild our images, this time with information about these predefined\nrepositories included:\n\n```\nmandark build $ bitbake refkit-image-minimal-flatpak-runtime\n```\n\nOnce the image is built, we check that the necessary bits did make it into\nthe image:\n\n```\nmandark build $ ls -ls tmp-glibc/work/qemux86_64-refkit-linux/refkit-image-minimal-flatpak-runtime/1.0-r0/rootfs/etc/flatpak-session\ndrwxr-xr-x  2 kli kli 4096 Feb 14 15:42 ./\ndrwxr-xr-x 24 kli kli 4096 Feb 14 16:53 ../\n-rw-r--r--  1 kli kli 1187 Feb 14 15:42 test1.key\n-rw-r--r--  1 kli kli   37 Feb 14 15:42 test1.url\n-rw-r--r--  1 kli kli 1187 Feb 14 15:42 test2.key\n-rw-r--r--  1 kli kli   37 Feb 14 15:42 test2.url\n-rw-r--r--  1 kli kli 1187 Feb 14 15:42 test3.key\n-rw-r--r--  1 kli kli   37 Feb 14 15:42 test3.url\n\nmandark build $ grep test. tmp-glibc/work/qemux86_64-refkit-linux/refkit-image-minimal-flatpak-runtime/1.0-r0/rootfs/etc/passwd\ntest1:x:2000:2000:flatpak user for test1:/home/test1:/bin/sh\ntest2:x:2001:2001:flatpak user for test2:/home/test2:/bin/sh\ntest3:x:2002:2002:flatpak user for test3:/home/test3:/bin/sh\n\nmandark build $ grep test. tmp-glibc/work/qemux86_64-refkit-linux/refkit-image-minimal-flatpak-runtime/1.0-r0/rootfs/etc/group\ntest1:x:2000:\ntest2:x:2001:\ntest3:x:2002:\n```\n\nNext we need to create flatpak repositories for these remotes and populate\nthem with at least 1 application per repository. We'll do this by cloning\na dummy test application and flatpak-building it 3 times for the 3 different\nrepos with slightly different command line argument so that we'll be able\nto tell from the logs/systemd journal if each of them is running.\n\nLet's first clone the dummy code:\n\n```\nmandark build $ mkdir app-build\nmandark build $ cd app-build\nmandark app-build $ git clone https://github.com/klihub/dummy-test.git\n```\n\nNow let's flatpak-build the application 3 times:\n\n```\nmandark app-builds $ for i in test1 test2 test3; do mkdir build.dummy-test.$i; done\nmandark app-builds $ for i in test1 test2 test3; do flatpak build-init build.dummy-test.$i org.$i.dummy iot.refkit.BaseSdk iot.refkit.BasePlatform current; done\nmandark app-builds $ cd dummy-test\nmandark dummy-test $ for i in test1 test2 test3; do flatpak build ../build.dummy-test.$i ./configure --prefix=/app; flatpak build ../build.dummy-test.$i make; flatpak build ../build.dummy-test.$i make install; done\n/bin/sh: warning: setlocale: LC_ALL: cannot change locale (en_US.utf8)\nchecking for a BSD-compatible install... /usr/bin/install -c\nchecking whether build environment is sane... yes\nchecking for a thread-safe mkdir -p... ./install-sh -c -d\nchecking for gawk... gawk\nchecking whether make sets $(MAKE)... yes\nchecking whether make supports nested variables... yes\nchecking for gcc... gcc\nchecking whether the C compiler works... yes\n...\n```\n\nLet's finalize the builds for our applications and update their metadata.\n\n```\nmandark dummy-test $ for i in test1 test2 test3; do flatpak build-finish ../build.dummy-test.$i --command=\"dummy-test $i\"; done\nPlease review the exported files and the metadata\nPlease review the exported files and the metadata\nPlease review the exported files and the metadata\nmandark dummy-test $ for i in test1 test2 test3; do echo -e \"X-Install=yes\\nX-Start=yes\\n\" \u003e\u003e ../build.dummy-test.$i/metadata; done\nmandark dummy-test $ for i in test1 test2 test3; do cat../build.dummy-test.$i/metadata; done\n[Application]\nname=org.test1.dummy\nruntime=iot.refkit.BasePlatform/x86_64/current\nsdk=iot.refkit.BaseSdk/x86_64/current\ncommand=dummy-test test1\nX-Install=yes\nX-Start=yes\n\n[Application]\nname=org.test2.dummy\nruntime=iot.refkit.BasePlatform/x86_64/current\nsdk=iot.refkit.BaseSdk/x86_64/current\ncommand=dummy-test test2\nX-Install=yes\nX-Start=yes\n\n[Application]\nname=org.test3.dummy\nruntime=iot.refkit.BasePlatform/x86_64/current\nsdk=iot.refkit.BaseSdk/x86_64/current\ncommand=dummy-test test3\nX-Install=yes\nX-Start=yes\n\n```\n\nSince everything looks good, let's create the repositories and export the\napplications:\n\n```\nmandark dummy-test $ for i in test1 test2 test3; do flatpak build-export --gpg-homedir=../../gpg --gpg-sign=refkit-image-minimal@key ../$i.flatpak ../build.dummy-test.$i; done\nCommit: cb440db279ced372a9fa428dbe1e9808f43b10a41b8560d05fc2c6efeed73334\nMetadata Total: 9\nMetadata Written: 1\nContent Total: 2\nContent Written: 0\nContent Bytes Written: 0 (0 bytes)\nCommit: f84ec77a3babfa1f87f97a499c3781e8e8e39ea633795287a2bc9b6cea46796d\nMetadata Total: 9\nMetadata Written: 1\nContent Total: 2\nContent Written: 0\nContent Bytes Written: 0 (0 bytes)\nCommit: 57fcece02a087da2e5648bf78848d3f07d90910fd262e96b015caafc20012677\nMetadata Total: 9\nMetadata Written: 1\nContent Total: 2\nContent Written: 0\nContent Bytes Written: 0 (0 bytes)\n```\n\nNow, the final thing on the host side is to export these repositories over\nHTTP for consumption by the clients. For this we'll generate 3 apache2\nconfiguration fragments, one for each remote.\n\n```\ncd ..\nmandark app-builds $ for i in test1 test2 test3; do cat flatpak-apps-$i.conf; done\nAlias \"/apps/test1\" \"/home/kli/src/work/IoT/refkit/app-builds/test1.flatpak/\"\n\n\u003cDirectory /home/kli/src/work/IoT/refkit/app-builds/test1.flatpak/\u003e\n    Options Indexes FollowSymlinks\n    Require all granted\n\u003c/Directory\u003e\n\nAlias \"/apps/test2\" \"/home/kli/src/work/IoT/refkit/app-builds/test2.flatpak/\"\n\n\u003cDirectory /home/kli/src/work/IoT/refkit/app-builds/test2.flatpak/\u003e\n    Options Indexes FollowSymlinks\n    Require all granted\n\u003c/Directory\u003e\nAlias \"/apps/test3\" \"/home/kli/src/work/IoT/refkit/app-builds/test3.flatpak/\"\n\n\u003cDirectory /home/kli/src/work/IoT/refkit/app-builds/test3.flatpak/\u003e\n    Options Indexes FollowSymlinks\n    Require all granted\n\u003c/Directory\u003e\n```\n\nIf all look ok, we copy them in place, and restart our HTTP server:\n\n```\nmandark app-builds $ sudo cp -v flatpak-apps-test?.conf /etc/httpd/conf.d\n'flatpak-apps-test3.conf' -\u003e '/etc/httpd/conf.d/flatpak-apps-test3.conf'\n'flatpak-apps-test3.conf' -\u003e '/etc/httpd/conf.d/flatpak-apps-test3.conf'\n'flatpak-apps-test3.conf' -\u003e '/etc/httpd/conf.d/flatpak-apps-test3.conf'\n\nmandark app-builds $ sudo systemctl restart httpd\n```\n\nTo verify that everything works as expected, the one remaining thing\nis to boot our image and verify that eventually the applications get\npulled in and started.\n\n```\nmandark app-builds $ cd ..\nmandark build $ sed -e 's/-m 256/-m 1024/' -i tmp-glibc/deploy/images/qemux86-64/refkit-image-minimal-flatpak-runtime-qemux86-64.qemuboot.conf\nmandark build $ runqemu tmp-glibc/deploy/images/qemux86-64/refkit-image-minimal-flatpak-runtime-qemux86-64.qemuboot.conf\n```\n\nOnce the image has booted, clear the entry from .ssh/known_hosts and\nlog in with ssh:\n\n```\nmandark build $ sed -e 's/^.*192.168.7.2 .*$//g' -i ~/.ssh/known_hosts\nmandark build $ ssh root@192.168.7.2\nLast login: Fri Feb 10 17:32:37 2017\n************************************\n*** This is a development image! ***\n*** Do not use in production.    ***\n************************************\nroot@qemux86-64:~# \n```\n\nLet's check the process list and logs:\n\n```\nroot@qemux86-64:~# ps | grep \"dummy-test test\"\n...\n  755 test1     8380 S    dummy-test test1\n  756 test3     8380 S    dummy-test test3\n  757 test2     8380 S    dummy-test test2\n  797 root      7848 S    grep dummy-test test\nroot@qemux86-64:~# journalctl -a | grep flatpak-session\n...\nFeb 15 15:41:38 qemux86-64 flatpak-session[537]: I: flatpak: starting application org.test.test2\nFeb 15 15:41:38 qemux86-64 dbus-daemon[630]: Activating via systemd: service name='org.freedesktop.Flatpak' unit='flatpak-session-helper.service'\nFeb 15 15:41:38 qemux86-64 dbus-daemon[631]: Activating via systemd: service name='org.freedesktop.Flatpak' unit='flatpak-session-helper.service'\nFeb 15 15:41:38 qemux86-64 dbus-daemon[633]: Activating via systemd: service name='org.freedesktop.Flatpak' unit='flatpak-session-helper.service'\nFeb 15 15:41:42 qemux86-64 flatpak-session[536]: I: flatpak: starting application org.test1.dummy\nFeb 15 15:41:42 qemux86-64 flatpak-session[538]: I: flatpak: starting application org.test3.dummy\nFeb 15 15:41:42 qemux86-64 flatpak-session[537]: I: flatpak: starting application org.test2.dummy\nFeb 15 15:41:45 qemux86-64 flatpak-session[538]: \u003ctest3 (dummy-test): user 2002/test3\u003e iteration #0\nFeb 15 15:41:45 qemux86-64 flatpak-session[536]: \u003ctest1 (dummy-test): user 2000/test1\u003e iteration #0\nFeb 15 15:41:45 qemux86-64 flatpak-session[537]: \u003ctest2 (dummy-test): user 2001/test2\u003e iteration #0\nFeb 15 15:41:46 qemux86-64 flatpak-session[536]: \u003ctest1 (dummy-test): user 2000/test1\u003e iteration #0\nFeb 15 15:41:46 qemux86-64 flatpak-session[538]: \u003ctest3 (dummy-test): user 2002/test3\u003e iteration #0\nFeb 15 15:41:46 qemux86-64 flatpak-session[537]: \u003ctest2 (dummy-test): user 2001/test2\u003e iteration #0\nFeb 15 15:42:15 qemux86-64 flatpak-session[538]: \u003ctest3 (dummy-test): user 2002/test3\u003e iteration #1\nFeb 15 15:42:15 qemux86-64 flatpak-session[536]: \u003ctest1 (dummy-test): user 2000/test1\u003e iteration #1\nFeb 15 15:42:15 qemux86-64 flatpak-session[537]: \u003ctest2 (dummy-test): user 2001/test2\u003e iteration #1\nFeb 15 15:42:16 qemux86-64 flatpak-session[536]: \u003ctest1 (dummy-test): user 2000/test1\u003e iteration #1\nFeb 15 15:42:16 qemux86-64 flatpak-session[538]: \u003ctest3 (dummy-test): user 2002/test3\u003e iteration #1\nFeb 15 15:42:16 qemux86-64 flatpak-session[537]: \u003ctest2 (dummy-test): user 2001/test2\u003e iteration #1\n...\n```\n\nIf your output looks similar enough, your image took the pre-defined remotes\nin use, discovered and installed the applications in them, and started them\nup.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fflatpak%2Fmeta-flatpak","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fflatpak%2Fmeta-flatpak","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fflatpak%2Fmeta-flatpak/lists"}