Properly document most of process

README.md

@@ -1,8 +1,94 @@
 # Reference repo for running Gitea with docker
 
+## Design
+
+This instance of Gitea uses the following components:
+
+- Gitea server, from [gitea/gitea](https://hub.docker.com/r/gitea/gitea) image
+- Nginx reverse proxy, from [nginx](https://hub.docker.com/_/nginx)) image
+- MariaDB MySQL-compatible database, from [mariadb](https://hub.docker.com/_/mariadb) image
+- Certbot ACME client, from [certbot/certbot](https://hub.docker.com/r/certbot/certbot) image
+
+It assumes a *Debian based* host in the UID/GID assigned to various containers, such as maintream Debian or Ubuntu.
+
+---
+
 ## Usage
 
+### Adding the Git user
+
+You should create the Linux `git` user and use sudo instead of running all commands as root
+
+`adduser git`
+
+You can leave all the misc info blank at the prompts - but don't forget to set a password!
+
+You'll also need to add the git user to the `sudoers` group, so you can use it to run the privileged Docker commands:
+
+`sudo usermod -a -G sudo git`
+
+### Nginx Setup
+
 1. In `nginx/sites-enabled/code.conf`, change all lines containing `code.example.com` to `subdomain.yourdomain.com`
-2. In the `letsencrypt.sh` script change the line containing `code.example.com` to `subdomain.yourdomain.com`, and change `email@example.com` to your email.
-3. In the `docker-compose.yml` file, change `ROOT_URL` to `https://subdomain.yourdomain.com/`. Do the same for `SSH_DOMAIN` but omit the `https://` and the `/` at the end.
-4. Make `letsencrypt.sh` executable and run it to get your SSL cert: `sudo chmod +x ./letsencrypt.sh; sudo./letsencrypt.sh`
+
+2. In the `docker-compose.yml` file, change `ROOT_URL` to `https://subdomain.yourdomain.com/`. Do the same for `SSH_DOMAIN`, omitting the `https`.
+
+### Gitea Setup
+
+Gitea requires a database (in this case MariaDB) to work. To set this up, you'll need a `.env` config file to give pass the DB login info to Docker. 
+
+1. Create the file
+   
+```
+touch ./.env
+```
+
+2. Open the file in a text editor and create a variable:
+
+```
+DB_PASSWORD=yourpasswordhere
+```
+
+> Note: You could do this directly in your `docker-compose.yml` file, but this is not a good idea in production, as it usually 
+> involves committing your credentials in git.
+
+### Host setup
+
+Since the Gitea container contains a built-in SSH server running on port 22 to enable git over ssh, you will get an error if you try to run this configuration out of the box.
+
+The simplest way to enable git over SSH is to change the port used for SSH on the host machine.
+
+You can change this by editing the file `/etc/ssh/sshd_config`, uncommenting `Port` and setting the value to something like `2222`.
+
+> **Note**: If you have a firewall like UFW configured, don't forget to allow incoming traffic on the new port *before* changing this setting, or you will be locked out of your server!
+
+To gain remote access to the machine again, simply prepend `-p 2222` to your future SSH commands:
+
+```
+ssh user@yourdomain.com -p 2222
+```
+
+### SSL Setup
+
+> Note: This section is incomplete.
+
+1. In the `letsencrypt.sh` script, change the line containing `code.example.com` to `subdomain.yourdomain.com`, and change `email@example.com` to your email.
+2. Make `letsencrypt.sh` executable
+
+```
+sudo chmod +x ./letsencrypt.sh
+```
+
+3. Run the script:
+
+```
+sudo ./letsencrypt.sh
+```
+
+### Server Standup
+
+Once you've finished setting these variables, you should be good to go.
+
+To start the instance, simply start the containers with Docker-compose:
+
+`docker-compose up -d`