diff --git a/README.md b/README.md index ae3813d..d54617b 100644 --- a/README.md +++ b/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 +Kitty down! + +### 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. diff --git a/static/503.html b/static/503.html new file mode 100644 index 0000000..841bc8d --- /dev/null +++ b/static/503.html @@ -0,0 +1,21 @@ + + + + + + Kitty down! + + +
+
+
+

Kitty down!

+

Oops! Seems like you visited kittyurl while we're down for maintenance. Don't worry - we should be back in a moment!

+
+
+ +
+
+
+ + \ No newline at end of file diff --git a/static/apache2.conf b/static/apache2.conf new file mode 100644 index 0000000..26c11a7 --- /dev/null +++ b/static/apache2.conf @@ -0,0 +1,108 @@ + + + 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. + + Options -Indexes + AllowOverride All + + 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 + + RequestHeader set X-Forwarded-Proto "http" + RequestHeader set X-Real-IP %{X-Forwarded-For}i + + + + + + + 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. + + Options -Indexes + AllowOverride All + + 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 + + RequestHeader set X-Forwarded-Proto "https" + RequestHeader set X-Real-IP %{X-Forwarded-For}i + + + SSLCertificateFile /etc/letsencrypt/live/example.com/fullchain.pem + SSLCertificateKeyFile /etc/letsencrypt/live/example.com/privkey.pem + + \ No newline at end of file diff --git a/static/bigchungus.jpg b/static/bigchungus.jpg new file mode 100644 index 0000000..4082fc6 Binary files /dev/null and b/static/bigchungus.jpg differ diff --git a/static/firefox_landing.png b/static/firefox_landing.png new file mode 100644 index 0000000..a44ece5 Binary files /dev/null and b/static/firefox_landing.png differ