added a kind of end-to-end example of how to set everything up

README.md

@@ -43,24 +43,82 @@ binary is named `repo2html`, and is installed in `/usr/local/bin`.
 to compile repo2html into a binary file, follow the steps below:
 
 1. ensure you're in the repo2html git repository
-2. run `make dependencies` as root
+2. as root, run `make dependencies`
 3. run `make`
-4. run `make install` as root
+
+## server setup
+
+this section uses `example.com` as a placeholder value. ensure you replace
+`example.com` with your own domain below.
+
+this section assumes the following about your server:
+
+- you've generated public and private ssh keys on your local machine
+- you can access your server through ssh and have root access
+- you manage your firewall with `ufw`
+- you use `nginx` as your web server
+- you use letsencrypt to manage TLS certificates
+- you've added an A record for `git.example.com`
+
+### setting up a git user
+
+ensure you're in the repo2html git repository, and follow the steps below:
+
+1. as root, run `adduser git`
+2. as root, run `mkdir /var/www/git`
+3. as root, run `chown git:git /var/www/git`
+4. as root, run `ufw allow 9418`
+5. run `su git`
+6. run `mkdir ~/.ssh && chmod 700 ~/.ssh`
+7. run `touch ~/.ssh/authorized_keys && chmod 600 ~/.ssh/authorized_keys`
+8. add your public ssh key from your local machine to `~/.ssh/authorized_keys`
+9. run `mkdir -p ~/projects/my-repository`
+
+### setting up nginx
+
+1. as root, add the following contents to `/etc/nginx/sites-available/git.example.com`:
+
+    server {
+        root /var/www/git;
+        index index.html;
+        server_name git.example.com;
+    }
+
+2. as root, run `ln -s /etc/nginx/sites-available/git.example.com /etc/nginx/sites-enabled/`
+3. as root, run `nginx -t` to test your nginx configuration
+4. as root, run `certbot`, and follow the prompts
+5. as root, run `systemctl restart nginx`
 
 ## installation
 
-TODO
+ensure you're in the repo2html git repository, and follow the steps below:
+
+1. run `make install` as root
+2. run `cp post-receive ~/projects/my-repository/hooks/`
+3. run `chmod u+x ~/projects/my-repository/hooks/post-receive`
+4. run `cp git-daemon.service /etc/systemd/system/` as root
+5. run `systemctl enable --now git-daemon.service` as root
 
 ## using repo2html as a post-receive hook
 
-TODO
+this section uses `example.com` as a placeholder value. ensure you replace
+`example.com` with your own domain below.
 
-## using repo2html as a standalone command-line utility
+on your local machine, follow the steps below:
 
-TODO
+1. run `git init my-repository`
+2. run `cd my-repository`
+3. run `echo "hello" > my-file.txt`
+4. run `git add my-file.txt`
+5. run `git commit -m "my first commit"
+6. run `git remote add origin git@example.com:~/projects/my-repository`
+7. run `git push`
 
 ## configuration
 
+this section uses `example.com` as a placeholder value. ensure you replace
+`example.com` with your own domain below.
+
 you can configure repo2html by changing environment variables in the `post-receive` hook file.
 
 for details about the environment variables, refer to the list below:
@@ -77,14 +135,13 @@ TODO
 
 ## todos
 
-- update docs according to changes in `50bbb3686d37fc00c95aedde82bc7a58de53b410`. m455 updated things a bit, but he wants to touch up on way more things documentation-wise according to the changes in this commit.
+- documentation: convert a lot of the stuff i (m455) made in the readme into an e2e tutorial
-- e2e tutorial
+- documenation: scope the readme audience to folks who kind of know what they're doing with servers
-- if no README.md file exists in the root directory of the repository, then don't create the "about" nav link. instead, make the files page the index.html
+- feature: if no README.md file exists in the root directory of the repository, then don't create the "about" nav link. instead, make the files page the index.html
-- add a "license" nav link if a LICENSE file exists in the root directory of the repository. if no LICENSE file exists, then don't create the "license" nav link
+- feature: add a "license" nav link if a LICENSE file exists in the root directory of the repository. if no LICENSE file exists, then don't create the "license" nav link
-- add a "contributors" nav link
 
 ## hopes
 
-- clickable line numbers in source files
+- feature: clickable line numbers in source files
-- make repos with more files and directories less daunting (recursively generate a files list page for each directory in a repo?)
+- feature: make repos with more files and directories less daunting (recursively generate a files list page for each directory in a repo?)
-- nav link: Releases
+- feature: nav link: Releases