From f5d631e3070371637966c9b4431ad67804eddc6f Mon Sep 17 00:00:00 2001
From: Stoiko Ivanov <s.ivanov@proxmox.com>
Date: Fri, 9 Sep 2022 17:45:06 +0200
Subject: [PATCH] docs: add minimal sample nginx config

if users want to use their offline medium via http in their internal
network.

nginx config is based off the one we use for download.proxmox.com.

Signed-off-by: Stoiko Ivanov <s.ivanov@proxmox.com>
---
 docs/Makefile            | 11 +++++++++--
 docs/examples/nginx-conf | 20 ++++++++++++++++++++
 docs/offline-media.rst   | 12 ++++++++++++
 3 files changed, 41 insertions(+), 2 deletions(-)
 create mode 100644 docs/examples/nginx-conf

diff --git a/docs/Makefile b/docs/Makefile
index 6d680a7..d302818 100644
--- a/docs/Makefile
+++ b/docs/Makefile
@@ -12,6 +12,9 @@ MAN1_PAGES := 				\
 MAN5_PAGES :=				\
 	proxmox-offline-mirror.cfg.5
 
+EXAMPLE_FILES :=	\
+	examples/nginx-conf
+
 # Sphinx documentation setup
 SPHINXOPTS    =
 SPHINXBUILD   = sphinx-build
@@ -46,7 +49,7 @@ man-pages: ${GENERATED_SYNOPSIS}
 	${SPHINXBUILD} ${SPHINXOPTS} -b man ./ ${BUILDDIR}/man
 
 .PHONY: html
-html: ${GENERATED_SYNOPSIS} images/proxmox-logo.svg custom.css conf.py ${PRUNE_SIMULATOR_FILES} ${LTO_BARCODE_FILES} ${API_VIEWER_SOURCES}
+html: ${GENERATED_SYNOPSIS} images/proxmox-logo.svg custom.css conf.py ${PRUNE_SIMULATOR_FILES} ${LTO_BARCODE_FILES} ${API_VIEWER_SOURCES} ${EXAMPLE_FILES}
 	$(SPHINXBUILD) -b html $(ALLSPHINXOPTS) $(BUILDDIR)/html
 	install -m 0644 custom.js custom.css images/proxmox-logo.svg $(BUILDDIR)/html/_static/
 	@echo
@@ -83,12 +86,16 @@ install_pdf: latexpdf
 	install -dm755 $(DESTDIR)$(DOCDIR)
 	install -m 0644 output/latex/ProxmoxOfflineMirror.pdf $(DESTDIR)$(DOCDIR)/proxmox-offline-mirror.pdf
 
+install_examples: ${EXAMPLE_FILES}
+	install -dm755 $(DESTDIR)$(DOCDIR)/examples
+	install -m 0644 examples/nginx-conf $(DESTDIR)$(DOCDIR)/examples
+
 ifneq ($(filter nodoc,$(DEB_BUILD_PROFILES)),)
 
 install: install_manual_pages
 
 else
 
-install: install_manual_pages install_html install_pdf
+install: install_manual_pages install_html install_pdf install_examples
 
 endif
diff --git a/docs/examples/nginx-conf b/docs/examples/nginx-conf
new file mode 100644
index 0000000..7d69aa9
--- /dev/null
+++ b/docs/examples/nginx-conf
@@ -0,0 +1,20 @@
+# with the correct dns setup and path this corresponds to a sources.lists entry
+# deb [ check-valid-until=false ] http://proxmox-offline-mirror.domain.example/<mirror-name>/<snapshot-timestamp> <codename> <suite>
+server {
+	listen 80 default_server;
+	listen [::]:80 default_server;
+
+	server_name proxmox-offline-mirror.domain.example;
+
+	root /path/to/medium;
+	disable_symlinks off;
+	autoindex on;
+
+	error_log /var/log/nginx/proxmox-offline-mirror.error.log;
+	access_log /var/log/nginx/proxmox-offline-mirror.access.log;
+
+	location / {
+	        try_files $uri $uri/ =404;
+	}
+}
+
diff --git a/docs/offline-media.rst b/docs/offline-media.rst
index 70cfff2..066657d 100644
--- a/docs/offline-media.rst
+++ b/docs/offline-media.rst
@@ -47,5 +47,17 @@ setup will let you select the mirrors and snapshots and can generate a `sources.
 This snippet can be saved to the ``/etc/apt/sources.list.d`` directory. The default file name is
 ``offline-mirror.list``.  Don't forget to remove the snippet after the upgrade is done.
 
+You can also configure an HTTP server to provide the snapshots in your internal network.
+A minimal sample configuration for `nginx`:
+
+  .. literalinclude:: examples/nginx-conf
+
+The corresponding ``/etc/apt/sources.list.d`` file should contain
+
+.. code-block:: sources.list
+
+  deb [ check-valid-until=false ] http://proxmox-offline-mirror.domain.example/<mirror-name>/<snapshot-timestamp> <codename> <suite>
+
+
 To activate or update an offline subscription key, either use ``proxmox-offline-mirror-helper offline-key`` or
 ``proxmox-offline-mirror-helper setup``.