# 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 ..
	```
- replace 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
	...
	```
- pull images not already present:
	```sh
	docker compose pull
	```
- start 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.