Hello World

Developers can quickly get started using the tutorial below. More detailed information is available in the Flatpak developer documentation.

1. Install Flatpak

First we need to install Flatpak itself. The instructions here are for Fedora or Ubuntu. Details for other distros can be found on the getting Flatpak page.

If you are using Fedora, run:

$ sudo dnf install flatpak

On Ubuntu, Flatpak is available through a PPA. To install it, run:

$ sudo add-apt-repository ppa:alexlarsson/flatpak
$ sudo apt update
$ sudo apt install flatpak

2. Install a runtime

Flatpak requires every app to specify a runtime that it uses for its dependencies. We'll use the GNOME 3.22 development platform runtime for this. To install the runtime, we first need to add the repository that provides it. Run:

$ flatpak remote-add --from gnome https://sdk.gnome.org/gnome.flatpakrepo

And then install the runtime itself:

$ flatpak install gnome org.gnome.Platform//3.22

3. Create your app

First we need to create the directory structure for the app:

$ mkdir hello
$ mkdir hello/files
$ mkdir hello/files/bin
$ mkdir hello/export

Now let's add something simple: create a file in hello/files/bin/ called hello.sh. Then add the following to the file and save it:

#!/bin/sh
echo "Hello world, from a sandbox"

Now we need to provide some information about the application. In Flatpak this is specified in a key-value file called metadata, which goes in the hello directory.

For a simple app this doesn't contain much, so we can create it manually:

[Application]
name=org.test.Hello
runtime=org.gnome.Platform/x86_64/3.22
command=hello.sh

This specifies the application identifier (org.test.Hello) as well as the runtime the application uses and the command to start the app with.

4. Put the app in a repository

Congratulations, you've made an app! To be able to install it, you need to put it in a repository. This is done with the build-export command. From the parent of the hello directory, run:

$ flatpak build-export repo hello

This will initialize a local repository in the "repo" directory and export the app to it.

5. Install

Now we're ready to add the repository that was just created and install the app. This is done with two commands:

$ flatpak --user remote-add --no-gpg-verify tutorial-repo repo
$ flatpak --user install tutorial-repo org.test.Hello

This will install the remote and the app in the user's home directory due to the --user argument. This is useful for test builds and other local things.

6. Run

All that's left is to run the app. This can be done with:

$ flatpak run org.test.Hello

This will print Hello world, from a sandbox.

Ta da! That's it: you've successfully built, installed and run your first Flatpak. Many of these steps are simplified by Flatpak's built in tools. For information on how to use them, as well as how to build and distribute more complex apps see the developer documentation.