kittyBE

Back-end for the KittyURL project -- create short and memorable URLs with ease!

Goals

Provide endpoints for:

• account management (/api/v1/user/*),
• link management (/api/v1/link/*),
• authed link management (when a link is bound to a user, /api/v1/authed/*),
• user management (for admins only, /api/v1/admin/*),
• general info (/api/v1/info/*),

KittyBE should also integrate nicely with kittyFE and be easily dockerizable.

Running kittyBE

KittyURL has been verified to work on Node 18.20+ and PostgreSQL 16.11+.

On bare metal

Running the back-end is as simple as:

• Installing the dependencies:

  • To just download the required dependencies:

    npm i
    

  • To install an exact copy of all of the dependencies:

    npm ci
    

• Copying the .env.default file to .env, and customizing it to own preferences.

  Example: Say, you want to add a domain to the trusted CORS origins list. To do so, your .env file in your editor of choice and append a comma (,) with the origin you want to add (say, http://example.com). Your .env file might then look as follows: TRUSTED_ORIGINS=http://localhost:6568,http://example.com.

  Important: Make sure to change the ACCESS_TOKEN_PRIVATE_KEY variable to something secure, as this secret value will be used to generate user sessions. Setting a weak key will allow attackers to potentially bruteforce your secret and forge user tokens!

• Pasting your wordlist file into src/tools/wordlist.ts.

  No wordlist file exists by default in src/tools/wordlist.ts. This is because wordlists were meant to be as modular as possible (with the philosophy of "bring your own wordlist"). If you leave that as-is, you'll run into runtime errors.

  However, if you don't want to provide your own wordlist, and just want to get up and running as fast as possible, you're free to use the provided sample wordlist.example-large.ts file. Just copy it into src/tools/wordlist.ts:

  cp wordlist.example-large.ts src/tools/wordlist.ts
  

• Launching the web server:

  npm start
  

• And... that's it! Now view your instance at http://localhost:6567, and -- if you've set the DEBUG flag in your .env file to true -- you can also visit http://localhost:6567/kttydocs/ for Swagger documentation.

Using Docker

A Docker image is built for every release of kittyBE and kittyFE. For more instructions on how to run the project with Docker, please refer to the kittyurl repository (which contains a sample docker-compose.yaml file, as well as it's own .env file).

Wordlists

You're free to provide your own wordlist file by pasting it into src/tools/wordlist.ts. For an example of how a wordlist file should look like, see wordlist.example-large.ts, and pay attention to the methods it exports.

Troubleshooting

Two supplementary scripts have been provided for aid in troubleshooting database-related errors.

• Run pending migrations on your database In a rare case, when you need to run the migrations before launching the server (as it will try running pending migrations on every launch), use:

  npm run pendingMigration
  

• Issue a new migration During development it might be necessary to issue new migrations. To do that, use:

  # assuming you're in the base project directory
  npm run newMigration ./src/migrations/myMigrationName
  

  where myMigrationName is the name of your migration.

  Important: TypeORM uses the state of your connected database when diffing for changes, unlike some other solutions, which take past migrations into consideration.

Note: If using other relational database than Postgres, make sure to do the due diligence of researching how to enable bigint support for your database driver. No other database type than Postgres has been tested.