new docs page: Deploying the Website

parent 6b435481
layout: page
title: Deploying the Website
The F-Droid website is built using [Jekyll]( and
[gitlab-ci]( The
whole website now works using a standard git
["fork" workflow](
that is well supported by gitlab, and well known from services like
GitHub. For all of the pages and information about apps and packages
distributed by _f-droid.org_, those pages are generated using our
[jekyll-fdroid]( plugin, which
takes the content from the
[_f-droid.org_ index file](
### Staging on development forks
All development forks of
automatically have a staging server setup and maintained by the
_gitlab-ci_ configuration. This automatically deploys the content of
the fork's _master_ branch to
[GitLab Pages]( For example, _nicoalt_'s
git fork is at <>, and the
_master_ branch from that is automatically deployed to
##### Deploying merge request branches
The current _gitlab-ci_ setup is optionally capable of pushing the
resulting HTML to a live webserver and linking to it automatically
from the GitLab merge request, deploying to
Doing so will allow for easier review of your merge requests, but is
not required. If you don't follow the steps below, your merge
requests will still run through the _gitlab-ci_ continuous integration
checks, but the resulting HTML will not be accessible online.
To configure this:
* Install the []( CLI: `npm install surge`
* Signup for []( `surge login`
* Get a "token" to allow CI to deploy on your behalf: `surge token`
* [Add two "Secret Variables"]( to your fork of this project:
* Navigate to your projects Settings -> CI/CD Pipelines -> Secret Variables.
* Add the following two variables:
* `SURGE_LOGIN`: The email you used to signup with `surge login`.
* `SURGE_TOKEN`: The value given when you ran `surge token`.
Now your CI jobs should be authorized to deploy to, and the
GitLab merge requests screen will automatically link to this
### Staging of the official website
Like with forks, the _master_ branch of the main git repo for the
website, <>, is automatically
deployed to <>. That is the
place to review the current state of the website before tagging a
### Deploying to
When an update to the website is tested and ready to go, a release
manager creates a PGP-signed release tag in the main git repo. The
deploy server monitors the main git repo for new tgs. When it sees a
new tag, it first checks the PGP signature on the git tag using a
manually configured GnuPG keyring that contains only the public keys
of the PGP keys that are allowed to tag website releases.
After the git tag is verified, the `` target in
is run to generate the actual files for the site. Those files are
then copied into place on the _f-droid.org_ servers.
* TODO document release tag naming scheme
### Setting up and running the deploy procedure
The deploy procedure was tested on a machine running Debian/stretch.
It should be triggered whenever the repo index is published, so it can
rebuild with the latest app information. This whole procedure can be
run as root, or just `gitlab-runner`. This final procedure is not
part of a script committed into the website git repo so that the
commands that run outside of docker cannot be modified via git.
1. [setup docker](
2. [setup gitlab-ci-multi-runner](
3. prepare _deploy-whitelist-keyring.gpg_ using GnuPG:
$ gpg --recv-keys 00aa5556
$ gpg --fingerprint 00aa5556 # verify it!
$ gpg --export 00aa5556 > /path/to/deploy-whitelist-keyring.gpg
4. get the website source code:
$ git clone
5. run the generation:
$ cd fdroid-website
$ git fetch --tags
$ sudo gitlab-runner exec docker \
--pre-build-script ./ \
--docker-volumes "/path/to/deploy-whitelist-keyring.gpg:/root/.gnupg/pubring.gpg:ro" \
--docker-volumes `pwd`/_site:/builds/output --env DEPLOY_DIR=/builds/output
6. deploy the site's files to the webserver, for example:
$ rsync -ax --delete --exclude repo/ --exclude archive/ _site/build/
......@@ -58,5 +58,6 @@ the main repository.
* [Verification Server](Verification_Server) Setting up a server to verify app builds are correct.
* [Whitelabel Builds](Whitelabel_Builds) custom builds of F-Droid
* [Privileged Extension]( How to use F-Droid Privileged Extension as a user and rom developer
* [Deploying the Website](Deploying_the_Website) How [fdroid-website.git]( becomes [](
* [Work in Progress]( Feel free to add your own topics and link to others.
Markdown is supported
0% or
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment