Documentation update

README.md

@@ -2,13 +2,26 @@
 
 Monolithic repository for my homelab
 
+# Navigation
+This repo is (mostly) organized into the following structure:
+```bash
+/ # The root contains repository meta-information like .gitignore, .gitlab-ci.yml, .gitmodules, and README.md. 
+  docs/ # The /docs directory is for all self-contained documentation that is not tied to a specific service. Service-specific documentation is contained in /$host/config/$service/README.md
+    img/ # supporting images for use in docs
+
+  $host/ # There are separate directories for the details and configuration of each host. At the root of `/$host/` we have non-authoritative documentation and reference. This includes printouts of hardware configs (`inxi -b`), host-specific procedure docs, useful scripts, etc.. 
+    config/ # Anything in the `/$host/config` directory is used as a source of truth from which hosts pull and apply the defined configuration.
+        $service/ # for Docker-enabled hosts each service stack will be configured within a directory
+            docker-compose.yml # all services (except minecraft, which needed a more modular system) use docker-compose.yml to define their stack configuration. 
+            .env # contains environment variables to be used by multiple containers within a stack
+            README.md # if a service stack has documentation specific to itself, it will be contained within this file. This usually contains procedure for interacting with a container and system configuration changes that could not be tracked in code (e.g. /etc/fstab or crontab or /etc/docker/daemon.json)
+```
+
 # Getting an SSH Key
 1. `TMP=$(echo "$HOME/.ssh/$(echo $HOSTNAME)_id_rsa") && ssh-keygen -b 8192 -t rsa -C "$USER@$HOSTNAME" -f $TMP -N "" && echo "IdentityFile $TMP" > $HOME/.ssh/config && cat $(echo "$TMP").pub`
 2. Go to Jafner -> Preferences -> SSH Keys.
 3. Add the pubkey and save.
 
-
-
 # Pulling Only Relevant Subdir
 Per: https://stackoverflow.com/questions/4114887
 
@@ -25,4 +38,4 @@ git checkout main
 To disable sparse checkout, simply run `git sparse-checkout disable`. 
 With this, it can also be re-eneabled with `git sparse-checkout init`.
 You can use these two commands to toggle sparse checkout.
-Per: https://stackoverflow.com/questions/36190800/how-to-disable-sparse-checkout-after-enabled
+Per: https://stackoverflow.com/questions/36190800/how-to-disable-sparse-checkout-after-enabled

server/README.md

@@ -28,25 +28,80 @@ For files greater than 2 GB, use one of the following:
 
 /dev/md0 /mnt/md0 ext4 defaults,nofail,discard 0 0
 ```
+# Boilerplates
+Below are useful boilerplate files for configuring new services.
+## `.env`
+```ini
+## Generic
+TZ=America/Los_Angeles # used by most images
+PUID=1000 # used by LSIO images
+PGID=1000 # used by LSIO images
+ADMIN_EMAIL=joey@jafner.net
 
-## Example docker-compose.yml for Web app
+## Container volume mapping
+DOCKER_DATA=/home/joey/data/<service>
+# DOCKER_DATA=/mnt/md0/<service> # for services whose internal data may be large (e.g. modded minecraft servers with large world files)
+DOCKER_CONFIG=/home/joey/homelab/server/config/<service>/config 
+
+## Additional volume mapping
+MEDIA_DIR=/mnt/nas/media
+VIDEO_DIR=/mnt/nas/media/Video
+MOVIE_DIR=/mnt/nas/media/Video/Movies
+SHOWS_DIR=/mnt/nas/media/Video/Shows
+BOOKS_DIR=/mnt/nas/calibre
+MUSIC_DIR=/mnt/nas/media/Audio/Music
+DOWNLOAD_DIR=/mnt/nas/torrenting/<service|tracker> # e.g. /mnt/nas/torrenting/GGN or /mnt/nas/torrenting/jdownloader2
+
+## SMTP Config
+SMTP_HOST=smtp.gmail.com
+SMTP_PORT=465
+SMTP_USER=noreply@jafner.net
+SMTP_PASS=
+SMTP_SSL=true
+SMTP_TLS=false
+## Configure client to use SSL, not TLS
 ```
-version: "3"
-services:
-  <SERVICE>:
-    container_name: <SERVICE>
-    image: 
-    restart: unless-stopped
-    volumes:
-    environment:
-    networks:
-      - web
-    labels:
-      - traefik.http.routers.<SERVICE>.rule=Host(`<SERVICE>.jafner.net`)
-      - traefik.http.routers.<SERVICE>.tls.certresolver=lets-encrypt
-      # - traefik.http.routers.<SERVICE>.middlewares=lan-only@file # optional lan-only testing
 
+## Web App `docker-compose.yml `
+```yml
+version: '3'
+services:
+    <service>:
+        image: 
+        container_name: <stack>_<service>
+        user: "1000:1000"
+        restart: unless-stopped
+        environment:
+            PUID: ${PUID}
+            PGID: ${PGID}
+        volumes:
+            - ${DOCKER_DATA}/<service>:/path/to/data
+        labels:
+            - traefik.http.routers.<service>.rule=Host(`<service>.jafner.net`)
+            - traefik.http.routers.<service>.tls.certresolver=lets-encrypt
+            - traefik.http.routers.<service>.middlewares=<middlewares> # available middlewares are available in homelab/server/config/traefik/config/middlewares.yaml
+            - traefik.http.services.<service>.loadbalancer.server.port=<port>
+        networks:
+            - web
+            - <service>
+        depends_on:
+            - landing_db
+    <service>_db:
+        image: 
+        container_name: <service>_db
+        user: "1000:1000"
+        restart: unless-stopped
+        networks:
+            - <service>
+        environment:
+            PUID: ${PUID}
+            PGID: ${PGID}
+        volumes:
+            - ${DOCKER_DATA}/db:/var/lib/mysql
+        labels:
+            - traefik.enable=false
 networks:
-  web:
-    external: true
-```
+    web:
+        external: true
+    <service>:
+```