Add a readme

1 files changed, 118 insertions, 0 deletions

diff --git a/readme.md b/readme.md
new file mode 100644
index 0000000..1adea76
--- /dev/null
+++ b/readme.md
@@ -0,0 +1,118 @@
+# Go Website
+
+Designed to be a basic website written in Go, primarliy targeted at blogs but
+can easily be used for landing pages and other basic information sites.
+
+Entirely driven by the filesystem there's a special markdown format that
+lets you set some variables in yaml at the top and the rest of the page
+body in markdown for the rest.
+
+It's designed to be somewhat easy to use by an intelligent lay person, once the website is setup most pages can be edited from the dashboard once the user is logged in.
+
+Multiple users can be specified in the `auth.json` file. No `auth.json` file is required, the program will create and save one automatically when it first runs. Just be aware that the username/password defaults to admin admin.
+
+If you set a password clear text in `auth.json` it will be rewritten as the hash alone when the program is run.
+
+If you wish to use a file other than `auth.json` you can specify one from the command line flags.
+
+There's an exmaple website in `example-site`
+
+Additionally it's designed to handle a large amount of requests by caching the
+output of the templates in redis rather than rendering them dynamically on each
+page load. This is an optional feature, easily disabled.
+
+Internally page rendering is split into its own library with most of the site
+functionality being handled in the cmd, this allows you to build full custom
+applications with a somewhat familiar markdown rendering paradigm if you wish
+to edit the go.
+
+
+## Building
+
+If you're on Windows:
+
+ * Download and install Go: [https://go.dev/dl/](https://go.dev/dl/)
+ * Download and install git: [https://git-scm.com/download/win](https://git-scm.com/download/win)
+
+ Then from the "Git Bash" prompt cd to the directory in which you checked out this repostiroy and simply run `sh ./build.sh` You should now have a `server.exe` file that you can call to run the website.
+
+If you're on Linux:
+
+  * Install Go
+  * run `sh ./build.sh`
+
+MacOS is very similar, if Go is in your path the build script should produce a server.
+
+
+## Starting the example website
+
+After running the build script:
+
+```
+$ ./server -d ./example-site -l 127.0.0.1:8001 -r ""
+```
+
+The simply load up [http://localhost:8001](http://localhost:8001) in your
+web browser
+
+Feel free to edit anything in `example-site` to your heart's content.
+
+The only runtime requirements for the website are the website directory and the server executable.
+
+
+## Example git hook for automatically updating a production website
+
+Say you're like me and like editing your website from a command line editor and commiting each change. Well, it's easy enough to deploy your changes to your production website with a simple `git push`, simply clone the repository on your remote server and add this `post-receive` hook:
+
+```bash
+#!/bin/sh
+# .git/hooks/post-receive
+set -e
+# Requires `git config  receive.denyCurrentBranch "ignore"` in order to be useful
+unset GIT_DIR
+unset GIT_WORK_TREE
+cd ..
+git config receive.denyCurrentBranch "ignore"
+set -x
+git reset --hard HEAD
+redis-cli del 'cache:example.com'
+```
+
+Then on your local copy:
+
+`$ git remote add production myProductionServer.example.com:/path/to/checkout/on/disk`
+
+Now, when you run `git push production master` the `myProductionServer.example.com` machine will automatically update the git repository and clear the redis cache, in this case for `example.com`
+
+
+## Help output from `server`
+
+The options most people will be interested in are `-l`, `-d`, `-r`, `-c` and `-ac`
+
+```
+$ ./server -h
+Usage of Website:
+  -T string
+        Set the page time format, be careful with this (default "01.02.2006 15:04:05 MST")
+  -V    Be more verbose ( dump config, etc )
+  -ac string
+        Location for authorization configuration file (default "auth.json")
+  -c string
+        Location for the config file (default "conf.yml")
+  -cache-index
+        If set to false do not cache index (default true)
+  -d string
+        Directory to serve. (default ".")
+  -i string
+        Path in which, when called will rebuild the index and clear the cache (default "/reIndex")
+  -l string
+        Listening address (default "0.0.0.0:8001")
+  -r string
+        Redis server set to "" to disable (default "127.0.0.1:6379")
+  -rk string
+        Redis key to use for storing cached pages (default "go-website")
+  -timeout int
+        Seconds until page timeout for read and write (default 15)
+  -v    Print the version then exit
+
+```