flat-manager serves and maintains a Flatpak repository. You point it at an ostree repository and it will allow Flatpak clients to install apps from the repository over HTTP. Additionally, it has an HTTP API that lets you upload new builds and manage the repository.
flat-manager is written in Rust, so you need Rust and Cargo installed. Everything works with the stable version of Rust, so you can get it from rustup or your distribution. On Fedora:
sudo dnf install cargo
PostgreSQL is used for the database, so the Postgres client libraries need to be installed first. On Fedora, this is done with:
sudo dnf install postgresql-devel
You also need ostree. On Fedora, this is done with:
sudo dnf install ostree-devel
Then build both the server and client by running:
cargo build
This builds both flat-manager and flat-manager-client since
they're part of the same workspace.
flat-manager reads the config.json file on startup in the
current directory, although the REPO_CONFIG environment variable
can be set to a different file. If you have a .env file in the
current directory or one of its parents, it will be read and used
to initialize environment variables.
The source repository contains an example.env and an
example-config.json that can be used as a basis:
cp example.env .env
cp example-config.json config.json
# edit config.json
The gpg-key and build-gpg-key config fields accept either a
single string or an array of strings, so you can sign with multiple
GPG keys:
"gpg-key": "KEYID"
"gpg-key": ["KEY1", "KEY2"]
flat-manager can be configured to run hook scripts during the upload
and publish processes. These are configured per-repository in the
config file; see example-config.json.
The publish hook runs in the build directory before a build is published
to a main repository. It can modify the build, for example by rewriting
the appstream files in the commits. It receives the FLAT_MANAGER_IS_REPUBLISH
environment variable, which is true if the publish was triggered by the
republish endpoint or false if the publish is part of a build.
If the publish is part of the build, the hook also receives the
FLAT_MANAGER_BUILD_ID environment variable.
Check scripts are run after a build is uploaded. Builds may not be
published unless all checks have passed. The check is marked as failed
if the command exits with a nonzero code (or marked as requiring review
if "reviewable": true is set).
Check scripts may also set their own status via the flat-manager API,
though this will be overridden if the command exits with a nonzero code.
To facilitate this, check scripts are run with FLAT_MANAGER_BUILD_ID and
FLAT_MANAGER_JOB_ID environment variables to pass to the API. The same
endpoint can be used by other systems for manual reviews.
flat-manager uses a PostgreSQL database to store information, and
requires you to specify its address in the configuration file.
The default example-config.json points this at:
"database-url": "postgres://%2Fvar%2Frun%2Fpostgresql/repo",
This is a database called repo accessed via the default (at
least on Fedora) UNIX domain socket. To install and start
PostgreSQL, do something like:
sudo dnf install postgresql-server postgresql-contrib
sudo systemctl enable postgresql
sudo postgresql-setup --initdb --unit postgresql
sudo systemctl start postgresql
On Debian-based systems:
sudo apt install postgresql
And create the repo database owned by your user:
sudo -u postgres createuser $(whoami)
sudo -u postgres createdb --owner=$(whoami) repo
Note that if you're doing development work, it is important to also
have DATABASE_URL=... set in the .env file for the Diesel
command-line application to work. This is not required in production
though.
flat-manager maintains a set of repositories specified in the
configuration, as well as a set of dynamically generated repositories
beneath the configured build-repo-base path. For testing with
the example configuration, these can be initialized by doing:
ostree --repo=repo init --mode=archive-z2
ostree --repo=beta-repo init --mode=archive-z2
mkdir build-repo
On a deployed system, these should be stored elsewhere, but make sure they are on the same filesystem so that hardlinks work between them as otherwise performance will be degraded.
All requests to the API require a token. Tokens are signed with a secret that has to be stored on the server. The default configuration contains:
"secret": "c2VjcmV0"
This is base64 of "secret", so don't use this in production, but it works for local testing. Otherwise, you can generate one based on some random data:
dd bs=256 count=1 if=/dev/random of=/dev/stdout | base64 -w 0
Each token can have various levels of privileges. For example one
could let you do everything, while another would only allow you to
upload builds to a particular build. There is an API to subset
your token for sharing with others (for example sending the above
upload-only token to a builder), but you can also generate a
token with the flat-manager-client gentoken subcommand:
echo -n "secret" | base64 | cargo run --bin flat-manager-client -- gentoken --base64 --secret-file - --name testtoken
The above matches the default secret, so can be used for testing.
Some token privileges are for managing flat-manager and shouldn't be
given to third parties who are just uploading apps. The token scopes
are: jobs, build, upload, publish, generate, download,
republish, reviewcheck, and tokenmanagement. See the
ClaimsScope enum in common/src/tokens.rs for details.
The client takes tokens via either the --token argument or in the
REPO_TOKEN environment variable.
To start the server, run:
cargo run --bin flat-manager
You can check the version with flat-manager --version. The server
listens on port 8080 by default. The number of worker threads can be
overridden with the ACTIX_WORKERS environment variable.
To test adding something to the repository, you can try building a simple app and exporting it to a repository. Use a recent version of flatpak and flatpak-builder to make sure you can build from Yaml files. This would normally happen on a different machine than the one serving the repository, but for testing we can just do it in a subdirectory:
git clone https://github.com/flathub/org.gnome.eog.git test-build
cd test-build
flatpak-builder --install-deps-from=flathub --repo=local-repo builddir org.gnome.eog.yml
cd ..
Then we can upload it to the repository by doing (assuming the default secret):
export REPO_TOKEN=$(echo -n "secret" | base64 | cargo run --bin flat-manager-client -- gentoken --base64 --secret-file - --name test)
cargo run --bin flat-manager-client -- push --commit $(cargo run --bin flat-manager-client -- create http://127.0.0.1:8080 stable) test-build/local-repo
This will create a new "build", upload the build to it and then "commit" the build.
The client supports these subcommands: create, push, commit,
publish, purge, prune, create-token, follow-job, and
gentoken. Run flat-manager-client --help for usage details.
Licensed under either of
- Apache License, Version 2.0 (LICENSE-APACHE or https://www.apache.org/licenses/LICENSE-2.0)
- MIT license (LICENSE-MIT or https://opensource.org/licenses/MIT)
at your option.
Unless you explicitly state otherwise, any contribution intentionally submitted for inclusion in the work by you, as defined in the Apache-2.0 license, shall be dual licensed as above, without any additional terms or conditions.