From 6cab77cf22926932895c5e3ed289aa5289d9bd80 Mon Sep 17 00:00:00 2001
From: Julian Mutter <julian.mutter@comumail.de>
Date: Mon, 22 Jun 2026 08:37:36 +0200
Subject: [PATCH] Add Readme

---
 Readme.md | 47 +++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 47 insertions(+)
 create mode 100644 Readme.md

diff --git a/Readme.md b/Readme.md
new file mode 100644
index 000000000..001b7b4b1
--- /dev/null
+++ b/Readme.md
@@ -0,0 +1,47 @@
+# Frajul's F-Droid Repo
+
+This contains the code for the deployment of my own F-Droid.
+
+## Deployment overview
+The deployment works via `docker`.
+The container is defined in `flake.nix`.
+Every `30 min`, it runs the script `hosting/update.sh`, which git-pulls this repo to update its scripts, then executes `scripts/update-apks.sh` and if any apks have been added or removed, it runs `fdroid update` to re-build the repo, which is located in the `fdroid` directory.
+
+This repo is served by a `caddy` server from the container on port `:8080`.
+
+### How to build and deploy
+To build the container run:
+```sh
+nix build .#container
+```
+
+To load the resulting `gitlab.julian-mutter.de/julian/fdroid-frajul:latest` container into the local docker daemon, run:
+```sh
+docker load < result
+```
+
+For building and deploying the container to the remote registry, simply run the following command, which is provided by the `flake.nix` dev shell:
+```sh
+deploy
+```
+
+## Container configuration
+### Environment variables
+- *SOPS_AGE_KEY*
+
+The files `fdroid/config.yml` and `fdroid/keystore.p12` are encrypted with `sops`.
+The update script automatically decrypts them on the first start of the container.
+For this to work the environment variable `SOPS_AGE_KEY` must be set to the age key used for encrypting.
+This key can be generated by running `age-keygen -o key.txt`.
+
+### External volumes
+- */apks*
+
+The update script downloads new apk versions into the `/apks` directory.
+The apks in there are synced on each update run to the `/src/code/fdroid/repo` directory, where they are served from.
+Therefore, the `/apks` directory is the perfect place to mount an external volume to persist all apks and avoid re-downloading on container restart.
+
+## Apk update scripts
+To automatically pull new versions of an apk, create a bash script in the `scripts/apk-update-scripts` directory.
+This script should be idempotent and download all available apk versions with differring file names into the `/apks` directory, if not already present. 
+All these scripts are automatically run regularly by `scripts/update-apks.sh`.