docs: update README

README.md

@@ -1,2 +1,120 @@
-# kittyurl
+# KittyURL
+*Create short and memorable URLs with ease!*
 
+![Landing page](/static/firefox_landing.png "Landing page")
+
+## Running KittyURL
+No matter how you intend to run KittyURL, start off by cloning the repository.
+```sh
+git clone --recurse-submodules https://gitea.7o7.cx/kittyteam/kittyurl
+```
+Above will clone the parent repository with both [kittyBE](https://gitea.7o7.cx/kittyteam/kittyBE) (backend) and [kittyFE](https://gitea.7o7.cx/kittyteam/kittyFE) (frontend).
+Your best next move is to copy the .env.default file to .env, and tailoring it to your needs:
+```sh
+cp .env.default .env
+```
+```sh
+# Open with your editor of choice and customize the configuration
+nano .env
+vim .env
+```
+
+### On bare metal
+For complete guides on how to setup [backend](https://gitea.7o7.cx/kittyteam/kittyBE)/[frontend](https://gitea.7o7.cx/kittyteam/kittyFE) on a bare metal machine, please refer to the instructions in their respective repository's READMEs.
+
+### Using Docker
+A Docker image is built for every release of [kittyBE](https://gitea.7o7.cx/kittyteam/-/packages/container/kittybe/latest) and [kittyFE](https://gitea.7o7.cx/kittyteam/-/packages/container/kittyfe/latest). If you want to run a container image built locally, see: *Using your own Docker images*.
+
+#### .env file
+Taking your time to understand the .env file is really important, as it contains the service configuration.
+
+> **Important**: One crucial out-of-the-box change you want to apply is updating the CURRENT_DIRECTORY_ABSOLUTE_PATH constant, as it is required for mounting your .env file - and thus, configuration - inside of the Docker containers!
+
+Other than that, you can, for instance, change BACKEND_PORT and FRONTEND_PORT to the one's you want to use.
+
+#### Wordlists
+You're free to provide your own wordlist file in a similar fashion to how it's done on [bare metal](https://gitea.7o7.cx/kittyteam/kittyBE).
+
+If you've pulled KittyURL repository recursively with it's submodules and want to use the default, provided wordlist - great news, you're good to go!
+
+If, however, you'd want to replace the default wordlist file with your own, update the PATH_TO_WORDLIST constant in your .env file.
+
+### Reverse proxy
+Running KittyURL behind a reverse proxy is encouraged. This way, you can make both frontend and backend available on a single port.
+
+A sample, tested Apache2 HTTPD [configuration](https://gitea.7o7.cx/kittyteam/kittyurl/src/branch/master/static/apache2.conf) has been supplied in the [static](https://gitea.7o7.cx/kittyteam/kittyurl/src/branch/master/static) directory.
+
+## Using your own Docker images
+Say, you want to build a container image for kittyBE and then use it. To do so, you'd need to:
+
+- enter the directory containing kittyBE:
+	```sh
+	cd kittyBE
+	```
+- issue `docker buildx` to build the image:
+	```sh
+	# Assuming:
+	# - you want to cross build for both x86_64 and AARCH64,
+	# - you want to tag your build as `latest` and push it to gitea.7o7.cx/kittyteam/kittybe package.
+	# If you don't intend to push it to an image repository, use whatever package name/tag you like.
+	docker buildx build --platform linux/amd64,linux/arm64 -t gitea.7o7.cx/kittyteam/kittybe:latest .
+	```
+- publish image (optional):
+	```sh
+	# Make sure you are signed in to your image repository:
+	docker login gitea.7o7.cx
+
+	# Push the image
+	docker push gitea.7o7.cx/kittyteam/kittybe:latest
+	```
+- navigate to the parent directory of KittyURL:
+	```sh
+	cd ..
+	```
+- replacing images in docker-compose.yaml with your own image:
+	```yaml
+	# From this:
+	...
+  	kittybe:
+	    container_name: backend
+	    image: gitea.7o7.cx/kittyteam/kittybe:${BACKEND_VERSION:-latest}
+	...
+	# To this:
+	...
+  	kittybe:
+	    container_name: backend
+	    image: gitea.7o7.cx/kittyteam/kittybe:latest
+	...
+	# Or this:
+	...
+  	kittybe:
+	    container_name: backend
+	    image: my_custom_image_name
+	...
+	```
+- pulling images not already present:
+	```sh
+	docker compose pull
+	```
+- starting docker compose:
+	```sh
+	# Normally
+	docker compose up
+
+	# Or in detached state
+	docker compose up -d
+	```
+
+Voila! You're now up and running with your own Docker image!
+
+## Troubleshooting
+<img src="/static/bigchungus.jpg" alt="Kitty down!" width="200"/>
+
+### Invalid host. Is your browser sending the host header? (no_host)
+This error gets triggered when the PUBLIC_URL constant and the Host header (as received by backend) are mismatched.
+
+This might be because:
+- User is sending an ill-formatted request (with wrong or no Host header),
+- PUBLIC_URL constant from the .env file is not set to the actual, publicly accessible URL.
+
+Please consider changing PUBLIC_URL, or verifying the server can access the Host header of a request.