docs: update README

.dockerignore

@@ -0,0 +1,4 @@
+# .env
+.env
+# Database
+db

.env.default

@@ -1,9 +1,13 @@
 # ========== Global config ==========
-
+DB_DATA_LOCATION=./db                              # Relative path in which database should be stored.
+CURRENT_DIRECTORY_ABSOLUTE_PATH=/path/to/kittyurl/ # Absolute path to current directory. Note the trailing slash.
 
 # ============= Backend =============
-BACKEND_PORT=6567              # Port on which the backend service should listen to requests.
-BACKEND_VERSION=latest         # Want to use a specific image for backend? Put the branch here followed by a release tag (like master-v1.2.3). Otherwise the latest one will get pulled.
+BACKEND_PORT=6567                                           # Port on which the backend service should listen to requests.
+BACKEND_VERSION=latest                                      # Want to use a specific image for backend? Put the branch here followed by a release tag (like master-v1.2.3). Otherwise the latest one will get pulled.
+ACCESS_TOKEN_PRIVATE_KEY=CHANGE_ME_TO_SOMETHING_RANDOM      # Used to generate user tokens. Make sure this is pretty random.
+TRUSTED_ORIGINS=http://localhost:6568,http://127.0.0.1:6568 # Comma separated list of trusted origins. Make sure to include your PUBLIC_URL here.
+PATH_TO_WORDLIST=kittyBE/wordlist.example-large.ts          # Relative path (considering CURRENT_DIRECTORY_ABSOLUTE_PATH) to wordlist to use when generating URLs. Note there is no slash at start.
 
 # Postgres and TypeORM
 PG_USER=kitty
@@ -21,3 +25,6 @@ DEBUG=false                    # Set to `false` to disable some features not mea
 # ============  Frontend ============
 FRONTEND_PORT=6568             # Port on which the frontend service should listen to requests.
 FRONTEND_VERSION=latest        # Want to use a specific image for frontend? Put the branch here followed by a release tag (like master-v1.2.3). Otherwise the latest one will get pulled.
+
+VITE_API_TARGET=http://localhost:6567 # The backend API base URL you want to use.
+VITE_ALLOWED_HOST=example.com         # Hosts allowed when visiting frontend. Probably should match PUBLIC_URL (tweak this when running a reverse proxy). To allow subdomains, add a dot (.) before the host address (vite.dev/config/server-options#server-allowedhosts).

.gitignore

@@ -1,3 +1,4 @@
 # .env
 .env
-
+# Database
+db

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.

docker-compose.yaml

@@ -6,16 +6,18 @@
 name: kittyurl
 services:
 
-  # kittyfe:
-  #   container_name: frontend
-  #   image: gitea.7o7.cx/kittyteam/kittyfe:${FRONTEND_VERSION:-latest}
-  #   env_file:
-  #     - .env
-  #   ports:
-  #     - ${FRONTEND_PORT}:6568
-  #   depends_on:
-  #     - kittybe
-  #   restart: unless-stopped
+  kittyfe:
+    container_name: frontend
+    image: gitea.7o7.cx/kittyteam/kittyfe:${FRONTEND_VERSION:-latest}
+    env_file:
+      - .env
+    ports:
+      - ${FRONTEND_PORT}:6568
+    depends_on:
+      - kittybe
+    volumes:
+      - ${CURRENT_DIRECTORY_ABSOLUTE_PATH}.env:/.env
+    restart: unless-stopped
 
   kittybe:
     container_name: backend
@@ -26,6 +28,11 @@ services:
       - ${BACKEND_PORT}:6567
     depends_on:
       - postgres
+    volumes:
+      # Change me if you want to store wordlist somewhere else.
+      # Remember, Docker requires you to point out absolute path when mounting
+      # only a single file.
+      - ${CURRENT_DIRECTORY_ABSOLUTE_PATH}${PATH_TO_WORDLIST}:/app/src/tools/wordlist.ts
     restart: unless-stopped
 
   postgres:
@@ -38,4 +45,6 @@ services:
       POSTGRES_USER: ${PG_USER}
       POSTGRES_PASSWORD: ${PG_PASS}
       POSTGRES_DB: ${PG_DB}
-
+    volumes:
+      - ${DB_DATA_LOCATION}:/var/lib/postgresql/data
+    shm_size: 128mb

static/503.html

@@ -0,0 +1,21 @@
+<!DOCTYPE html>
+<html lang="en">
+	<head>
+		<meta http-equiv="content-type" content="text/html; charset=UTF-8">
+		<meta charset="UTF-8">
+		<title>Kitty down!</title>
+	</head>
+	<body>
+		<center>
+			<div style="font-family: system-ui;">
+				<div>
+					<h1>Kitty down!</h1>
+					<p>Oops! Seems like you visited kittyurl while we're down for maintenance. Don't worry - we should be back in a moment!</p>
+				</div>
+				<div>
+					<img src="bigchungus.jpg" style="width: 12em;">
+				</div>
+			</div>
+		</center>
+	</body>
+</html>

static/apache2.conf

@@ -0,0 +1,108 @@
+<VirtualHost *:80>
+
+	ServerName example.com
+	ServerAlias *.example.com
+
+	ErrorLog /dev/null
+	CustomLog /dev/null combined
+
+	# Uncomment to enable http -> https rewrite.
+	# 
+	# RewriteEngine On
+	# RewriteCond %{SERVER_NAME} =example.com
+	# RewriteRule ^ https://%{SERVER_NAME}%{REQUEST_URI} [END,NE,R=permanent]
+	# Redirect / https://example.com%{REQUEST_URI}
+	# 
+	# If you decide to redirect to https,
+	# you're free to comment lines below.
+
+	# Feeling extra fancy? How about custom 503 page,
+	# when the server is down for maintenance?
+	# A sample page has been provided in the static/ directory.
+	<Directory "/var/www/html/kittyurl-static/">
+		Options -Indexes
+		AllowOverride All
+	</Directory>
+	Alias "/.well-known" "/var/www/html/kittyurl-static/.well-known"
+
+	ProxyPreserveHost On
+	ProxyPass /.well-known !
+	ProxyPass /.well-known/errors/ !
+	ErrorDocument 503 /.well-known/errors/503.html
+
+	# 1. Match EXACT root "/" (for frontend)
+	ProxyPassMatch   ^/$ http://127.0.0.1:6568/
+	ProxyPassReverse  /  http://127.0.0.1:6568/
+
+	# 2. Match "/assets/" and subpaths (for frontend)
+	ProxyPass        /assets/ http://127.0.0.1:6568/assets/
+	ProxyPassReverse /assets/ http://127.0.0.1:6568/assets/
+	ProxyPass         /panel/ http://127.0.0.1:6568/panel/
+	ProxyPassReverse  /panel/ http://127.0.0.1:6568/panel/
+	ProxyPass         /about/ http://127.0.0.1:6568/about/
+	ProxyPassReverse  /about/ http://127.0.0.1:6568/about/
+
+	# 3. Match ALL OTHER paths (order matters: least specific LAST)
+	# Forward any and all traffic to backend.
+	ProxyPass        / http://127.0.0.1:6567/
+	ProxyPassReverse / http://127.0.0.1:6567/
+
+	# Shared headers for ALL proxied requests
+	<Proxy *>
+		RequestHeader set X-Forwarded-Proto "http"
+		RequestHeader set X-Real-IP %{X-Forwarded-For}i
+	</Proxy>
+
+</VirtualHost>
+
+<IfModule mod_ssl.c>
+	<VirtualHost *:443>
+		Include /etc/letsencrypt/options-ssl-apache.conf
+
+		ServerName example.com
+		ServerAlias *.example.com
+
+		ErrorLog /dev/null
+		CustomLog /dev/null combined
+
+		# Feeling extra fancy? How about custom 503 page,
+		# when the server is down for maintenance?
+		# A sample page has been provided in the static/ directory.
+		<Directory "/var/www/html/kittyurl-static/">
+			Options -Indexes
+			AllowOverride All
+		</Directory>
+		Alias "/.well-known" "/var/www/html/kittyurl-static/.well-known"
+
+		ProxyPreserveHost On
+		ProxyPass /.well-known !
+		ProxyPass /.well-known/errors/ !
+		ErrorDocument 503 /.well-known/errors/503.html
+
+		# 1. Match EXACT root "/" (for frontend)
+		ProxyPassMatch   ^/$ http://127.0.0.1:6568/
+		ProxyPassReverse  /  http://127.0.0.1:6568/
+
+		# 2. Match "/assets/" and subpaths (for frontend)
+		ProxyPass        /assets/ http://127.0.0.1:6568/assets/
+		ProxyPassReverse /assets/ http://127.0.0.1:6568/assets/
+		ProxyPass         /panel/ http://127.0.0.1:6568/panel/
+		ProxyPassReverse  /panel/ http://127.0.0.1:6568/panel/
+		ProxyPass         /about/ http://127.0.0.1:6568/about/
+		ProxyPassReverse  /about/ http://127.0.0.1:6568/about/
+
+		# 3. Match ALL OTHER paths (order matters: least specific LAST)
+		# Forward any and all traffic to backend.
+		ProxyPass        / http://127.0.0.1:6567/
+		ProxyPassReverse / http://127.0.0.1:6567/
+
+		# Shared headers for ALL proxied requests
+		<Proxy *>
+			RequestHeader set X-Forwarded-Proto "https"
+			RequestHeader set X-Real-IP %{X-Forwarded-For}i
+		</Proxy>
+
+		SSLCertificateFile    /etc/letsencrypt/live/example.com/fullchain.pem
+		SSLCertificateKeyFile /etc/letsencrypt/live/example.com/privkey.pem
+	</VirtualHost>
+</IfModule>