docs: update README
This commit is contained in:
120
README.md
120
README.md
@@ -1,2 +1,120 @@
|
||||
# kittyurl
|
||||
# KittyURL
|
||||
*Create short and memorable URLs with ease!*
|
||||
|
||||
|
||||
|
||||
## 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.
|
||||
|
||||
21
static/503.html
Normal file
21
static/503.html
Normal file
@@ -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>
|
||||
108
static/apache2.conf
Normal file
108
static/apache2.conf
Normal file
@@ -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>
|
||||
BIN
static/bigchungus.jpg
Normal file
BIN
static/bigchungus.jpg
Normal file
Binary file not shown.
|
After Width: | Height: | Size: 122 KiB |
BIN
static/firefox_landing.png
Normal file
BIN
static/firefox_landing.png
Normal file
Binary file not shown.
|
After Width: | Height: | Size: 62 KiB |
Reference in New Issue
Block a user