From 6b3885379e83fa6148d5ec90e0789515b14aae24 Mon Sep 17 00:00:00 2001
From: Daniel Sissom <daniel@sissom.net>
Date: Wed, 28 Aug 2024 16:47:27 -0500
Subject: [PATCH] Updated readme with more detailed instructions.

---
 README.md | 135 +++++++++++++++++++++++++++++++++++++-----------------
 1 file changed, 92 insertions(+), 43 deletions(-)

diff --git a/README.md b/README.md
index f86c46c..780523e 100644
--- a/README.md
+++ b/README.md
@@ -1,83 +1,132 @@
 Example Web Server/Site Template
 ================================
 
+
 -------------------------------------------------
 Project Layout
 -------------------------------------------------
 
-## Project Working Copy
+### Project Working Copy
 
 ```
 ~/Projects/Web/example.com/			# git repo (git ignore www)
 	|
-	|- docker-compose.yml
+	|-- docker-compose.yml
 	|
-	|- service/
+	|-- service/
 	|	|
-	|	|- docker-compose.yml
+	|	|-- docker-compose.yml
 	|
-	|- www/							# git repo (git ignore build)
+	|-- www/						# git repo (git ignore build)
 	|	|
-	|	|- Makefile
+	|	|-- Makefile
 	|	|
-	|	|- index.pug
+	|	|-- index.pug
 	|	|
-	|	|- build/					# git repo (if not building target on server, e.g. static GitHub pages)
+	|	|-- build/					# git repo (if not building target on server, e.g. static GitHub pages)
 	|	|	|
-	|	|	|- index.html
+	|	|	|-- index.html
 	|	|
-	|	|- config/
+	|	|-- config/
 ```
 
-## Project Collaboration
+### Hosted Project Collaboration
 
 ```
-git@examplecodehost.com:organization/example.com.git
-git@examplecodehost.com:organization/www.example.com.git
+git@examplecodehost.com:organization/example.com.git			# server config repo
+git@examplecodehost.com:organization/www.example.com.git		# site source repo
 ```
 
-## Server Deployment
+### Server Deployment
 
 ```
 /usr/local/src/web/example.com/
 	|
-	|- server/						# bare git repo
+	|-- server/						# bare git repo for server config
+	|
+	|-- www/						# bare git repo for site build files (or optionally site source files if server builds project)
 	|
-	|- www/							# bare git repo
+	|-- build/						# optional bare git repo for build files if server builds project automatically
+```
+
+Git branches are checked out to different worktrees to be served:
 ```
+/srv/dev/example.com/				# dev branch server config
+	|
+	|-- docker-compose.yml
+	|
+	|-- www/						# dev branch built site
+
+/srv/beta/example.com/				# release branch server config
+	|
+	|-- docker-compose.yml
+	|
+	|-- www/						# release branch built site
+
+/srv/prod/example.com/				# master branch server config
+	|
+	|-- docker-compose.yml
+	|
+	|-- www/						# master branch built site
 
 ```
+Dev, beta, and prod could all be on different servers if appropriate.
+
+
+-------------------------------------------------
+Server Groups and Directory Permissions
+-------------------------------------------------
+
+
+Add your user (on the server) to the srv group.  Set directory permissions
+```
+# chown root:srv .
+# chmod g+ws .
+# setfacl -d -m g::rwx .
+```
+for all relevant directories (newly created subdirectories should inherit permissions):
+```
+/usr/local/src/web/example.com/
+/usr/local/src/web/example.com/server/
+/usr/local/src/web/example.com/www/
+/usr/local/src/web/example.com/build/
 /srv/dev/example.com/
+/srv/dev/example.com/www/
 /srv/beta/example.com/
+/srv/beta/example.com/www/
 /srv/prod/example.com/
+/srv/prod/example.com/www/
 ```
 
-In build upstream bare repo (webserver:/usr/local/src/web/example.com/www/), run:
-	# chown root:srv .
-	# chmod g+ws .
-	# setfacl -d -m g::rwx .
-	# git init --bare --shared=group
-	# git config receive.denyCurrentBranch updateInstead
-	# git config receive.denyNonFastForwards false
-	?(# git config core.sharedRepository true)    # if needed because of missing init option
-
-Set upstream and push branches to new bare repo, then run:
-	# git worktree add /srv/prod/example.com/www master
-	# git worktree add /srv/beta/example.com/www release
-	# git worktree add /srv/dev/example.com/www dev
-
-	# chmod -R g+w .
-	# chmod g+w /srv/*/example.com/www
-
-
-	# chown -R root:srv .
-	# chmod -R g+swX .
-	# chown root:srv /srv/prod/example.com/www
-	# chmod g+swX /srv/prod/example.com/www
-	# chown root:srv /srv/beta/example.com/www
-	# chmod g+swX /srv/beta/example.com/www
-	# chown root:srv /srv/dev/example.com/www
-	# chmod g+swX /srv/dev/example.com/www
-and add your user (on the server) to the srv group.
+In upstream bare repo directories (e.g. `webserver:/usr/local/src/web/example.com/www/`), run:
+```
+# git init --bare --shared=group
+# git config receive.denyCurrentBranch updateInstead
+# git config receive.denyNonFastForwards false
+# git config core.sharedRepository true			# if needed because of missing init option
+```
+
+In working copy repos, set upstream and push branches to new bare repos, then in
+the bare repos run:
+```
+# git worktree add /srv/prod/example.com/www master
+# git worktree add /srv/beta/example.com/www release
+# git worktree add /srv/dev/example.com/www dev
+```
+
+Maybe needed if above permissions weren't set correctly:
+```
+# chmod -R g+w .
+# chmod g+w /srv/*/example.com/www
+
+# chown -R root:srv .
+# chmod -R g+swX .
+# chown root:srv /srv/prod/example.com/www
+# chmod g+swX /srv/prod/example.com/www
+# chown root:srv /srv/beta/example.com/www
+# chmod g+swX /srv/beta/example.com/www
+# chown root:srv /srv/dev/example.com/www
+# chmod g+swX /srv/dev/example.com/www
+```