{"id":13929409,"url":"https://github.com/flatpak/flat-manager","last_synced_at":"2025-04-09T18:18:04.895Z","repository":{"id":38185259,"uuid":"168719647","full_name":"flatpak/flat-manager","owner":"flatpak","description":"Manager for flatpak repositories","archived":false,"fork":false,"pushed_at":"2025-04-08T02:11:46.000Z","size":935,"stargazers_count":196,"open_issues_count":29,"forks_count":44,"subscribers_count":12,"default_branch":"master","last_synced_at":"2025-04-09T18:17:58.950Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"Rust","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","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":"LICENSE-APACHE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null}},"created_at":"2019-02-01T15:40:29.000Z","updated_at":"2025-04-09T12:09:47.000Z","dependencies_parsed_at":"2024-01-20T09:43:44.946Z","dependency_job_id":null,"html_url":"https://github.com/flatpak/flat-manager","commit_stats":{"total_commits":435,"total_committers":22,"mean_commits":"19.772727272727273","dds":0.3402298850574713,"last_synced_commit":"d1c3d36da7b5779163ff70007c4d2f145cfce664"},"previous_names":[],"tags_count":14,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/flatpak%2Fflat-manager","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/flatpak%2Fflat-manager/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/flatpak%2Fflat-manager/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/flatpak%2Fflat-manager/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/flatpak","download_url":"https://codeload.github.com/flatpak/flat-manager/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":248085326,"owners_count":21045139,"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-08-07T18:02:19.712Z","updated_at":"2025-04-09T18:18:04.874Z","avatar_url":"https://github.com/flatpak.png","language":"Rust","funding_links":[],"categories":["others","Rust"],"sub_categories":[],"readme":"# flat-manager\n\nflat-manager serves and maintains a Flatpak repository. You point it\nat an ostree repository and it will allow Flatpak clients to install\napps from the repository over HTTP. Additionally, it has an HTTP API\nthat lets you upload new builds and manage the repository.\n\n## Building the server\n\nThe server is written in Rust, so you need to have Rust and Cargo\ninstalled. Everything works with the stable version of Rust,\nso you can get it from [rustup](https://github.com/rust-lang/rustup.rs)\nor your distribution. On Fedora:\n\n    sudo dnf install cargo\n\nPostgreSQL is used for the database, so the Postgres client libraries\nneed to be installed first. On Fedora, this is done with:\n\n    sudo dnf install postgresql-devel\n\nYou also need ostree. On Fedora, this is done with:\n\n    sudo dnf install ostree-devel\n\nThen build the server by running:\n\n    cargo build\n\n## Building the client\n\nflat-manager contains a Python-based client that can be used\nto talk to the server. To run this, you need Python 3 as\nwell as the aiohttp packages, installed via pip or the\ndistribution packages. On Fedora, this can be installed using:\n\n    sudo dnf install python3-aiohttp\n\n## Configuration\n\nflat-manager reads the `config.json` file on startup in the\ncurrent directory, although the `REPO_CONFIG` environment variable\ncan be set to a different file. If you have a `.env` file in the\ncurrent directory or one of its parents, it will be read and used\nto initialize environment variables.\n\nThe source repository contains an `example.env` and an\n`example-config.json` that can be used as a basis:\n\n    cp example.env .env\n    cp example-config.json config.json\n    # edit config.json\n\n### Hooks\n\nflat-manager can be configured to run hook scripts during the upload\nand publish processes. These are configured per-repository in the\nconfig file; see `example-config.json`.\n\nThe publish hook runs in the build directory before a build is published\nto a main repository. It can modify the build, for example by rewriting\nthe appstream files in the commits. It receives the `FLAT_MANAGER_IS_REPUBLISH`\nenvironment variable, which is `true` if the publish was triggered by the\nrepublish endpoint or `false` if the publish is part of a build.\nIf the publish is part of the build, the hook also receives the\n`FLAT_MANAGER_BUILD_ID` environment variable.\n\nCheck scripts are run after a build is uploaded. Builds may not be\npublished unless all checks have passed. The check is marked as failed\nif the command exits with a nonzero code (or marked as requiring review\nif `\"reviewable\": true` is set).\n\nCheck scripts may also set their own status via the flat-manager API,\nthough this will be overridden if the command exits with a nonzero code.\nTo facilitate this, check scripts are run with `FLAT_MANAGER_BUILD_ID` and\n`FLAT_MANAGER_JOB_ID` environment variables to pass to the API. The same\nendpoint can be used by other systems for manual reviews.\n\n## Database\n\nflat-manager uses a PostgreSQL database to store information, and\nrequires you to specify its address in the configuration file.\nThe default `example-config.json` points this at:\n\n    \"database-url\": \"postgres://%2Fvar%2Frun%2Fpostgresql/repo\",\n\nThis is a database called `repo` accessed via the default (at\nleast on Fedora) UNIX domain socket. To install and start\nPostgreSQL, do something like:\n\n    sudo dnf install postgresql-server postgresql-contrib\n    sudo systemctl enable postgresql\n    sudo postgresql-setup --initdb --unit postgresql\n    sudo systemctl start postgresql\n\nOn Debian-based systems:\n\n   sudo apt install postgresql\n\nAnd create the `repo` database owned by your user:\n\n    sudo -u postgres createuser $(whoami)\n    sudo -u postgres createdb --owner=$(whoami) repo\n\nNote that if you're doing development work, it is important to also\nhave `DATABASE_URL=...` set in the `.env` file for the Diesel\ncommand-line application to work. This is not required in production\nthough.\n\n## Repositories\n\nflat-manager maintains a set of repositories specified in the\nconfiguration, as well as a set of dynamically generated repositories\nbeneath the configured `build-repo-base` path. For testing with\nthe example configuration, these can be initialized by doing:\n\n    ostree --repo=repo init --mode=archive-z2\n    ostree --repo=beta-repo init --mode=archive-z2\n    mkdir build-repo\n\nOn a deployed system, these should be stored elsewhere, but make sure\nthey are on the same filesystem so that hardlinks work between them as\notherwise performance will be degraded.\n\n## Tokens\n\nAll requests to the API require a token. Token are signed with a secret\nthat has to be stored on the server. The default configuration contains:\n\n    \"secret\": \"c2VjcmV0\"\n\nThis is base64 of \"secret\", so don't use this in production, but it\nworks for local testing. Otherwise, you can generate one based on\nsome random data:\n\n    dd bs=256 count=1 if=/dev/random of=/dev/stdout | base64 -w 0\n\nEach token can have various levels of privileges. For example one\ncould let you do everything, while another would only allow you to\nupload builds to a particular build. There is an API to subset\nyour token for sharing with others (for example sending the above\nupload-only token to a builder), but you can also generate a\ntoken with the gentoken command:\n\n    echo -n \"secret\" | base64 | cargo run --bin gentoken -- --base64 --secret-file - --name testtoken\n\nThe above matches the default secret, so can be used for testing.\n\nSome token privileges are for managing flat-manager and shouldn't be\ngiven to third parties who are just uploading apps. The token privileges\nare described in the [`ClaimsScope` enum in `tokens.rs`](https://github.com/flatpak/flat-manager/blob/d1c3d36da7b5779163ff70007c4d2f145cfce664/src/tokens.rs#L21-L46).\n\nThe client takes tokens via either the `--token` argument or in the\n`REPO_TOKEN` environment variable.\n\nFor a production setup, you will also want to generate a token\nfor `delta-generator`. This can be done by following the above\ncommand with these arguments:\n\n    echo -n \"secret\" | base64 | cargo run --bin gentoken -- --base64 --secret-file - --name delta-generator --sub delta --scope generate\n\n## Running\n\nTo start the server, run:\n\n    cargo run --bin flat-manager\n\nIt will listen on port 8080 by default.\n\nTo test adding something to the repository, you can try building a\nsimple app and exporting it to a repository. Use a recent version of\nflatpak and flatpak-builer to make sure you can build from Yaml files.\nThis would normally happen on a different machine than the one serving\nthe repository, but for testing we can just do it in a subdirectory:\n\n    git clone https://github.com/flathub/org.gnome.eog.git test-build\n    cd test-build\n    flatpak-builder --install-deps-from=flathub --repo=local-repo builddir org.gnome.eog.yml\n    cd ..\n\nThen we can upload it to the repository by doing (assuming the default secret):\n\n    export REPO_TOKEN=$(echo -n \"secret\" | base64 | cargo run --bin gentoken -- --base64 --secret-file - --name test)\n    ./flat-manager-client push --commit $(./flat-manager-client create http://127.0.0.1:8080 stable) test-build/local-repo\n\nThis will create a new \"build\", upload the build to it and then \"commit\" the build.\n\n## License\n\nLicensed under either of\n\n- Apache License, Version 2.0\n   ([LICENSE-APACHE](LICENSE-APACHE) or https://www.apache.org/licenses/LICENSE-2.0)\n- MIT license\n   ([LICENSE-MIT](LICENSE-MIT) or https://opensource.org/licenses/MIT)\n\nat your option.\n\n## Contribution\n\nUnless you explicitly state otherwise, any contribution intentionally submitted\nfor inclusion in the work by you, as defined in the Apache-2.0 license, shall be\ndual licensed as above, without any additional terms or conditions.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fflatpak%2Fflat-manager","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fflatpak%2Fflat-manager","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fflatpak%2Fflat-manager/lists"}