121 lines
4.6 KiB
Markdown
121 lines
4.6 KiB
Markdown
# 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.
|