webtemplate_server/README.md

Example Web Server/Site Template
================================


-------------------------------------------------
Git Branching
-------------------------------------------------

```
hotfix                   *--*
                        /    \
master  *--------------*------*----------*------------*----------*--------------
         \            /        \        /            /          /
release   \      *---*----------*------*------------*----------*----------------
           \    /     \          \      \          /          /
dev         *--*--*----*----*--*--*--*---*-----*--*----*--*--*------------------
                   \       /          \       /
feature             *--*--*            *--*--*
```


-------------------------------------------------
Project Layout
-------------------------------------------------

### Project Working Copy

```
~/Projects/Web/example.com/			# git repo (git ignore www)
	|
	|-- docker-compose.yml
	|
	|-- service/
	|	|
	|	|-- docker-compose.yml
	|
	|-- www/						# git repo (git ignore build)
	|	|
	|	|-- Makefile
	|	|
	|	|-- index.pug
	|	|
	|	|-- build/					# git repo (if not building target on server, e.g. static GitHub pages)
	|	|	|
	|	|	|-- index.html
	|	|
	|	|-- config/
```

### Hosted Project Collaboration

```
git@examplecodehost.com:organization/example.com.git			# server config repo
git@examplecodehost.com:organization/www.example.com.git		# site source repo
```

### Server Deployment

```
/usr/local/src/web/example.com/
	|
	|-- server/						# bare git repo for server config
	|
	|-- www/						# bare git repo for site build files (or optionally site source files if server builds project)
	|
	|-- 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 upstream bare repo directories (e.g. `webserver:/usr/local/src/web/example.com/www/`), run:
```
# git init --bare --shared=group
# git config set --local receive.denyCurrentBranch updateInstead
# git config set --local receive.denyNonFastForwards false
# git config set --local core.sharedRepository true			# if needed because of missing init option
```

In order to push to shared repositories under `/usr/local/src/`, set the global git config option:
```
$ git config set --global safe.directory "/usr/local/src/*"
```

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
```