kittyurl/README.md

KittyURL

Create short and memorable URLs with ease!

Running KittyURL

No matter how you intend to run KittyURL, start off by cloning the repository.

git clone --recurse-submodules https://gitea.7o7.cx/kittyteam/kittyurl

Above will clone the parent repository with both kittyBE (backend) and kittyFE (frontend). Your best next move is to copy the .env.default file to .env, and tailoring it to your needs:

cp .env.default .env

# 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/frontend 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 and kittyFE. 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.

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 has been supplied in the 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:

  cd kittyBE
  

• issue docker buildx to build the image:

  # 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):

  # 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:

  cd ..
  

• replace images in docker-compose.yaml with your own image:

  # 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:

  docker compose pull
  

• start docker compose:

  # 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

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.