From cf87bbf05ca1fc4bb4373988c96ede859305a9b7 Mon Sep 17 00:00:00 2001
From: ebner <simon.ebner@psi.ch>
Date: Thu, 18 Apr 2024 11:30:31 +0200
Subject: [PATCH] add documentation for custom repos

---
 _toc.yml                                    |  1 +
 infrastructure-guide/custom_repositories.md | 78 +++++++++++++++++++++
 2 files changed, 79 insertions(+)
 create mode 100644 infrastructure-guide/custom_repositories.md

diff --git a/_toc.yml b/_toc.yml
index 6d556d2a..bcafcfe7 100644
--- a/_toc.yml
+++ b/_toc.yml
@@ -141,6 +141,7 @@ chapters:
       - file: infrastructure-guide/troubleshooting
       - file: infrastructure-guide/initial_setup
       - file: infrastructure-guide/test_systems
+      - file: infrastructure-guide/custom_repositories
 
   - file: rhel8/index
     sections:
diff --git a/infrastructure-guide/custom_repositories.md b/infrastructure-guide/custom_repositories.md
new file mode 100644
index 00000000..d8d58985
--- /dev/null
+++ b/infrastructure-guide/custom_repositories.md
@@ -0,0 +1,78 @@
+# Custom RPM Repositories
+
+## Usage
+The backend for these custom repos is on a NFS4 share. This share can be mounted from __lx-fs:/packages_misc__
+
+On __Linux__ systems you should be able to mount the share like this
+```bash
+mount -t nfs4 -o sec=krb5,nfsvers=4 lx-fs.psi.ch:/packages_misc /mnt
+```
+
+On __MacOS__ you could mount and access the share like this:
+```bash
+mount_nfs -o sec=krb5,nfsvers=4 lx-fs.psi.ch:/packages_misc ~/some_directory
+```
+
+(on __Windows__ - it should be/is also possible with Windows >=10 to mount the NFS4 share- https://learn.microsoft.com/en-us/windows-server/administration/windows-commands/mount - details to be added here)
+
+
+Once your folder/folders is/are created and your are autorized to write into these folders you can place RPMs and files into that directory/directories
+
+__Important__: Once mounted, to be able to change things on the filesystem you have to have a valid kerberosticket for your PSI user. 
+```
+kinit <username>@D.PSI.CH
+# or on standard PSI linux systems
+kinit
+```
+
+
+On lxsup.psi.ch you can easily access and test and use the NFS share by accessing `/packages_misc`.
+
+## Overview
+Custom repositories are provided by the central repository server as all other repositories. They will be available on the URL
+
+https://repos.psi.ch/&lt;os>/latest/&lt;repository_name>
+
+The custom repositories are snapshotted and tagged as any other repository.
+
+The content of the custom repositories are managed on a a dedicated NFS4 share. On this share groups can have different folders where they place/manage their rpms. These RPMs are periodically synced to the main repository share (i.e. every 15 minutes), so what you see on the `packages_misc` is not exactly what will end up on the repository server. Upon sync the repository will be automatically build via the create-repo command.
+
+The structure of the share is usually as follows:
+
+```
+<base>/<repository name>
+                        # content in the case of one repo for all major RHEL version
+                        /rhel7
+                        /rhel8
+                        /rhle9 # in case of different repo for major RHEL version
+```
+
+The access control is done by a Unix group usually named `unx-<something>_adm` (most of the time this is a group that also gives access to hiera repos)
+
+
+## Setup
+
+If you need a custom RPM repository where you can place your specific RPMs/packages please contact the Linux Core team (linux-eng@psi.ch).
+
+To setup the your custom repository/ies we need following information:
+- Name of the repository
+- Do you want to have your repository available for __all__ RHEL major versions (i.e. all RHEL major versions will see the same packages) or do you need a repository for each RHEL major version (i.e. you can have different packages for each RHEL major version)?
+
+### Implementation
+
+The packages_misc share is only root writeable from lx-sync-01.psi.ch. Therefore the initial setup needs to be done there.
+
+Creation of a new repo (on lx-sync-01 in /packages_misc):
+```
+cd /packages_misc
+mkdir <reponame>
+chgrp 35588 <reponame>  ## We need to use the numeric group id here as lx-sync is not directly connected to AD
+chmod g+w <reponame>
+chmod g+s <reponame>
+```
+
+To sync the repo and make it available there need to be a sync config added to https://git.psi.ch/linux-infra/rpm-repo-utils/-/tree/main/etc?ref_type=heads
+(inside the __*-misc__ directories)
+
+After adding this config the changes need to be deployed on lx-sync-01.psi.ch.
+(either bootstrap/ansible or a manual `git pull` in `/opt/rpm-repo-utils/`)
\ No newline at end of file